You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This commit is a big refactor of the pybm project. Highlights include:
* Providers were cut from the scope, with venv now being the sole
virtual environment provider.
* A new `PythonVenv` class was added to manage central venv operations
in a class.
* The source was reformatted globally with isort, a new precommit hook.
* A __main__ file was added to enable calling pybm via python module
syntax.
* The JSON reporter was refactored to make a cleaner presentation of
results. Specifically, aggregates are not recalculated by reductions
if already present.
<commit-ish> Commit, branch or tag to create a git worktree for.
8
+
<name> Unique name for the created workspace. Can be used to reference workspaces from the command line.
9
+
<dest> Destination directory of the new worktree. Defaults to repository-name@{commit|branch|tag}.
10
+
11
+
optional arguments:
12
+
-h, --help Show this message and exit.
13
+
-v Enable verbose mode. Makes pybm log information that might be useful for debugging.
14
+
-f, --force Force worktree creation. Useful for checking out a branch multiple times with different custom requirements.
15
+
-R, --resolve-commits
16
+
Always resolve the given git ref to its associated commit. If the given ref is a branch name, this detaches the HEAD (see https://git-scm.com/docs/git-checkout#_detached_head).
17
+
--no-checkout Skip worktree checkout after creation. Useful for sparsely checking out branches.
18
+
-L <path-to-venv>, --link-existing <path-to-venv>
19
+
Link an existing Python virtual environment to the created pybm workspace. Raises an error if the path does not exist or is not recognized as a valid Python virtual environment.
20
+
```
21
+
22
+
Use `pybm create` to create a new benchmark workspace for a specified git reference:
23
+
24
+
```shell
25
+
pybm create my-branch my-workspace
26
+
```
27
+
28
+
This operation creates a benchmark workspace for a git branch named my-branch, and gives it the name my-workspace. This
29
+
given name can be used in pybm to reference a workspace, so it is useful to give expressive names to workspaces.
30
+
31
+
By default, the benchmark workspace with the repository root worktree is given the name `main`; if you choose not to
32
+
specify a name, pybm defaults to the `workspace_i` naming scheme, where `i` is an index starting at 1.
33
+
34
+
Further positional and optional arguments are:
35
+
36
+
The `-L` option can be used to link an existing virtual environment to a benchmark workspace. Suppose you have a
37
+
ready workspace at `/path/to/venv`; then `pybm workspace create my-branch -L /path/to/venv` will link the existing virtual
38
+
environment into the benchmark workspace.
39
+
40
+
✅ Not only branch names work as valid git references - you can also supply tag names or full/partial commit SHAs. In the
41
+
latter case, the SHA fragment is directly passed to git, which can fail to resolve a unique reference if the fragment is
42
+
too short. For a project with lots of commits, increasing the SHA fragment length can help avoid resolution errors.
Copy file name to clipboardexpand all lines: docs/commands/run.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -24,7 +24,7 @@ optional arguments:
24
24
--context <context> Additional global context, given as strings in the format--context='key'='value'. Keys must be unique, supplying two or more context values forthe same key resultsin an error.
25
25
```
26
26
27
-
The `pybm run`command is perhaps the heart of `pybm`'s functionality. It is responsible for discovering, dispatching
27
+
The `pybm run`command is responsible for discovering, dispatching
28
28
and running the appropriate benchmarks across the chosen workspaces. There are multiple nuances to running benchmarks
<commit-ish> Commit, branch or tag to create a git worktree for.
37
-
<name> Unique name for the created workspace. Can be used to reference workspaces from the command line.
38
-
<dest> Destination directory of the new worktree. Defaults to repository-name@{commit|branch|tag}.
39
-
40
-
optional arguments:
41
-
-h, --help Show this message and exit.
42
-
-v Enable verbose mode. Makes pybm log information that might be useful for debugging.
43
-
-f, --force Force worktree creation. Useful for checking out a branch multiple times with different custom requirements.
44
-
-R, --resolve-commits
45
-
Always resolve the given git ref to its associated commit. If the given ref is a branch name, this detaches the HEAD (see https://git-scm.com/docs/git-checkout#_detached_head).
46
-
--no-checkout Skip worktree checkout after creation. Useful for sparsely checking out branches.
47
-
-L <path-to-venv>, --link-existing <path-to-venv>
48
-
Link an existing Python virtual environment to the created pybm workspace. Raises an error if the path does not exist or is not recognized as a valid Python virtual environment.
49
-
```
50
-
51
-
Use `pybm workspace create` to create a new benchmark workspace for a specified git reference:
52
-
53
-
```shell
54
-
pybm workspace create my-branch my-workspace
55
-
```
56
-
57
-
This operation creates a benchmark workspace for a git branch named my-branch, and gives it the name my-workspace. This
58
-
given name can be used in pybm to reference a workspace, so it is useful to give expressive names to workspaces.
59
-
60
-
By default, the benchmark workspace with the repository root worktree is given the name `main`; if you choose not to
61
-
specify a name, pybm defaults to the `workspace_i` naming scheme, where `i` is an index starting at 1.
62
-
63
-
Further positional and optional arguments are:
64
-
65
-
The `-L` option can be used to link an existing virtual environment to a benchmark workspace. Suppose you have a
66
-
ready workspace at `/path/to/venv`; then `pybm workspace create my-branch -L /path/to/venv` will link the existing virtual
67
-
environment into the benchmark workspace.
68
-
69
-
✅ Not only branch names work as valid git references - you can also supply tag names or full/partial commit SHAs. In the
70
-
latter case, the SHA fragment is directly passed to git, which can fail to resolve a unique reference if the fragment is
71
-
too short. For a project with lots of commits, increasing the SHA fragment length can help avoid resolution errors.
72
-
73
-
## pybm workspace delete
74
-
75
-
```
76
-
pybm workspace delete <identifier> [<options>]
77
-
78
-
positional arguments:
79
-
<id> Information that uniquely identifies the workspace. Can be name, checked out commit/branch/tag name, or worktree root directory.
80
-
81
-
optional arguments:
82
-
-h, --help Show this message and exit.
83
-
-v Enable verbose mode. Makes pybm log information that might be useful for debugging.
84
-
-f, --force Force worktree removal, including untracked files and changes.
85
-
```
86
-
87
-
Use the `pybm workspace delete` command to delete a benchmark workspace. The identifier can be the git reference name (
88
-
partial SHAs also work), a benchmark workspace name or a directory name.
89
-
90
-
In the (standard) case of a virtual environment being created directly inside the git worktree, this virtual environment
91
-
will be removed upon deletion of the benchmark workspace; this behavior cannot be changed as git physically removes
92
-
the associated worktree. If you want to reuse a Python virtual environment, consider linking it explicitly from another
93
-
location with the `-L` switch in the `pybm workspace create` command - pybm will not remove these.
0 commit comments