gate-cache 0.6.0__tar.gz → 0.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: gate-cache
3
- Version: 0.6.0
3
+ Version: 0.7.0
4
4
  Summary: Skip lint and test gates that already passed on the exact same git tree.
5
5
  Author: Nate Landau
6
6
  Author-email: Nate Landau <github@natenate.org>
@@ -30,7 +30,7 @@ Classifier: Programming Language :: Python :: 3.12
30
30
  Classifier: Programming Language :: Python :: 3.13
31
31
  Classifier: Programming Language :: Python :: 3.14
32
32
  Classifier: Programming Language :: Python :: 3.15
33
- Requires-Dist: platformdirs>=4.13.0,<5.0.0
33
+ Requires-Dist: platformdirs>=4.14.5,<5.0.0
34
34
  Requires-Python: >=3.11
35
35
  Description-Content-Type: text/markdown
36
36
 
@@ -47,10 +47,12 @@ $ gate-cache -- uv run pytest
47
47
  ============================= 412 passed in 94.20s =============================
48
48
 
49
49
  $ gate-cache -- uv run pytest
50
- gate-cache: uv run pytest already passed on tree aaff74984ccc, skipping
50
+ gate-cache: uv run pytest already passed on tree aaff74984ccc, skipping (saved 1m 34s)
51
51
  ```
52
52
 
53
- A change to any file that git does not ignore changes the content, so no marker matches and the command runs again. A CI runner that starts from a fresh clone has no markers, so it runs every command.
53
+ The time in parentheses is how long the command ran when it passed, so the time that the skip saves is approximate.
54
+
55
+ A change to any file that git does not ignore changes the content, so no marker matches and the command runs again. To make a gate match only the files that its command reads, [scope the gate to its paths](#scope-a-gate-to-its-paths). A CI runner that starts from a fresh clone has no markers, so it runs every command.
54
56
 
55
57
  ## Install
56
58
 
@@ -85,6 +87,28 @@ gate-cache exits with the exit code of the command, or with 0 when it skips the
85
87
 
86
88
  The tree includes uncommitted edits and untracked files that git does not ignore. A gate that passes on uncommitted work therefore skips in the commit hook when you commit the same content. gate-cache computes the tree from a private copy of the index, so it never stages files or changes your index.
87
89
 
90
+ ## Scope a gate to its paths
91
+
92
+ In a repository with several parts, a change to the docs or to one part does not change the result of the tests of another part. A gate that has `--path` options matches only the content under those paths:
93
+
94
+ ```sh
95
+ gate-cache --name api-test --path api/ --path uv.lock -- uv run pytest api/tests
96
+ ```
97
+
98
+ After this gate passes, a change to `README.md` or to `web/` lets it skip, and so does a rebase that brings in only those changes. A change under `api/` or to `uv.lock` makes it run again.
99
+
100
+ Each `--path` is a git pathspec. gate-cache reads it from the top of the repository, so a recipe that runs in a subdirectory and a hook that runs at the top give the same paths. A directory covers every file under it. The order of the paths has no effect. Wildcards and `:(exclude)` work:
101
+
102
+ ```sh
103
+ gate-cache --name scripts-test --path scripts/ --path ':(exclude)scripts/fixtures/' -- uv run pytest scripts
104
+ ```
105
+
106
+ In a pathspec, `*` also matches `/`, so `*.just` matches a `.just` file in every directory. `**/justfile` matches only a `justfile` inside a directory. To also match the `justfile` at the top, use `:(glob)**/justfile`.
107
+
108
+ > **Warning:** List every file and directory that the command reads, including lock files and shared config. The gate skips when nothing under its paths changed. A change to a file outside the paths does not make the gate run again.
109
+
110
+ If a path matches no file, gate-cache runs the command without the cache and prints that path. A typo in a path therefore never makes a gate skip.
111
+
88
112
  ## Run it as a hook
89
113
 
90
114
  gate-cache works with [prek](https://github.com/j178/prek) and with [pre-commit](https://pre-commit.com) 3.2 or later. Each `gate-cache` hook takes the same arguments as the command line:
@@ -226,9 +250,24 @@ $ gate-cache status --name "uv run ruff check ."
226
250
  last run: exit code 1
227
251
  ```
228
252
 
229
- The `last run` line shows only when the name ran on this content without a pass.
253
+ The `last run` line shows only when the name ran on this content without a pass. The `duration` line shows how long the command ran when it passed.
254
+
255
+ For a scoped gate, give the same `--path` options with `--name`. The report adds a `paths` line and a `scope` line, and the `tree` line shows the whole tree:
256
+
257
+ ```console
258
+ $ gate-cache status --name api-test --path api/ --path uv.lock
259
+ name: api-test
260
+ paths: api/ uv.lock
261
+ scope: paths:7c462ce94adead1b7ab99f8e4212ffac194c562e0d178151207c1f01e0073615
262
+ tree: aaff74984cccd156a469afa7d9ab10e4777beb24
263
+ marker: /path/to/repo/.git/gate-cache/4156a896efe2ed16204b6d2525acbfbd9c4dd808dbfc135571e4f631b7d7754a
264
+ result: hit
265
+ duration: 1m 34s
266
+ ```
267
+
268
+ Without `--name`, `status` also lists the scoped gates that passed or missed on the current content of their paths.
230
269
 
231
- `status` runs nothing. With `--name`, it exits 0 when a marker matches and 1 when none does. Without `--name`, it exits 0 when at least one name passed. When gate-cache cannot match the content, for example during a merge conflict, the `tree` line gives the reason.
270
+ `status` runs nothing. With `--name`, it exits 0 when a marker matches and 1 when none does. Without `--name`, it exits 0 when at least one name passed. When gate-cache cannot match the content, for example during a merge conflict, the `tree` line gives the reason. For a scoped gate whose paths match no file, the `scope` line gives it.
232
271
 
233
272
  With `--json`, `status` writes one JSON object to stdout instead of text. The exit codes do not change:
234
273
 
@@ -245,7 +284,7 @@ $ gate-cache status --json
245
284
  }
246
285
  ```
247
286
 
248
- `reason` tells why gate-cache cannot match the content, and is `null` when it can. When caching is off, `enabled` is `false`, `reason` names the variable, and the other keys are empty or `null`. With `--name`, the object has the `name`, `marker`, `result`, and `last_run` keys in place of `passed` and `missed`.
287
+ `reason` tells why gate-cache cannot match the content, and is `null` when it can. When caching is off, `enabled` is `false`, `reason` names the variable, and the other keys are empty or `null`. With `--name`, the object has the `name`, `marker`, `result`, `last_run`, and `duration` keys in place of `passed` and `missed`. `duration` is the run time in seconds of the matching pass, or `null`. With `--path`, `tree` holds the scope value, and the object adds the `paths` and `full_tree` keys.
249
288
 
250
289
  ## Start fresh
251
290
 
@@ -11,10 +11,12 @@ $ gate-cache -- uv run pytest
11
11
  ============================= 412 passed in 94.20s =============================
12
12
 
13
13
  $ gate-cache -- uv run pytest
14
- gate-cache: uv run pytest already passed on tree aaff74984ccc, skipping
14
+ gate-cache: uv run pytest already passed on tree aaff74984ccc, skipping (saved 1m 34s)
15
15
  ```
16
16
 
17
- A change to any file that git does not ignore changes the content, so no marker matches and the command runs again. A CI runner that starts from a fresh clone has no markers, so it runs every command.
17
+ The time in parentheses is how long the command ran when it passed, so the time that the skip saves is approximate.
18
+
19
+ A change to any file that git does not ignore changes the content, so no marker matches and the command runs again. To make a gate match only the files that its command reads, [scope the gate to its paths](#scope-a-gate-to-its-paths). A CI runner that starts from a fresh clone has no markers, so it runs every command.
18
20
 
19
21
  ## Install
20
22
 
@@ -49,6 +51,28 @@ gate-cache exits with the exit code of the command, or with 0 when it skips the
49
51
 
50
52
  The tree includes uncommitted edits and untracked files that git does not ignore. A gate that passes on uncommitted work therefore skips in the commit hook when you commit the same content. gate-cache computes the tree from a private copy of the index, so it never stages files or changes your index.
51
53
 
54
+ ## Scope a gate to its paths
55
+
56
+ In a repository with several parts, a change to the docs or to one part does not change the result of the tests of another part. A gate that has `--path` options matches only the content under those paths:
57
+
58
+ ```sh
59
+ gate-cache --name api-test --path api/ --path uv.lock -- uv run pytest api/tests
60
+ ```
61
+
62
+ After this gate passes, a change to `README.md` or to `web/` lets it skip, and so does a rebase that brings in only those changes. A change under `api/` or to `uv.lock` makes it run again.
63
+
64
+ Each `--path` is a git pathspec. gate-cache reads it from the top of the repository, so a recipe that runs in a subdirectory and a hook that runs at the top give the same paths. A directory covers every file under it. The order of the paths has no effect. Wildcards and `:(exclude)` work:
65
+
66
+ ```sh
67
+ gate-cache --name scripts-test --path scripts/ --path ':(exclude)scripts/fixtures/' -- uv run pytest scripts
68
+ ```
69
+
70
+ In a pathspec, `*` also matches `/`, so `*.just` matches a `.just` file in every directory. `**/justfile` matches only a `justfile` inside a directory. To also match the `justfile` at the top, use `:(glob)**/justfile`.
71
+
72
+ > **Warning:** List every file and directory that the command reads, including lock files and shared config. The gate skips when nothing under its paths changed. A change to a file outside the paths does not make the gate run again.
73
+
74
+ If a path matches no file, gate-cache runs the command without the cache and prints that path. A typo in a path therefore never makes a gate skip.
75
+
52
76
  ## Run it as a hook
53
77
 
54
78
  gate-cache works with [prek](https://github.com/j178/prek) and with [pre-commit](https://pre-commit.com) 3.2 or later. Each `gate-cache` hook takes the same arguments as the command line:
@@ -190,9 +214,24 @@ $ gate-cache status --name "uv run ruff check ."
190
214
  last run: exit code 1
191
215
  ```
192
216
 
193
- The `last run` line shows only when the name ran on this content without a pass.
217
+ The `last run` line shows only when the name ran on this content without a pass. The `duration` line shows how long the command ran when it passed.
218
+
219
+ For a scoped gate, give the same `--path` options with `--name`. The report adds a `paths` line and a `scope` line, and the `tree` line shows the whole tree:
220
+
221
+ ```console
222
+ $ gate-cache status --name api-test --path api/ --path uv.lock
223
+ name: api-test
224
+ paths: api/ uv.lock
225
+ scope: paths:7c462ce94adead1b7ab99f8e4212ffac194c562e0d178151207c1f01e0073615
226
+ tree: aaff74984cccd156a469afa7d9ab10e4777beb24
227
+ marker: /path/to/repo/.git/gate-cache/4156a896efe2ed16204b6d2525acbfbd9c4dd808dbfc135571e4f631b7d7754a
228
+ result: hit
229
+ duration: 1m 34s
230
+ ```
231
+
232
+ Without `--name`, `status` also lists the scoped gates that passed or missed on the current content of their paths.
194
233
 
195
- `status` runs nothing. With `--name`, it exits 0 when a marker matches and 1 when none does. Without `--name`, it exits 0 when at least one name passed. When gate-cache cannot match the content, for example during a merge conflict, the `tree` line gives the reason.
234
+ `status` runs nothing. With `--name`, it exits 0 when a marker matches and 1 when none does. Without `--name`, it exits 0 when at least one name passed. When gate-cache cannot match the content, for example during a merge conflict, the `tree` line gives the reason. For a scoped gate whose paths match no file, the `scope` line gives it.
196
235
 
197
236
  With `--json`, `status` writes one JSON object to stdout instead of text. The exit codes do not change:
198
237
 
@@ -209,7 +248,7 @@ $ gate-cache status --json
209
248
  }
210
249
  ```
211
250
 
212
- `reason` tells why gate-cache cannot match the content, and is `null` when it can. When caching is off, `enabled` is `false`, `reason` names the variable, and the other keys are empty or `null`. With `--name`, the object has the `name`, `marker`, `result`, and `last_run` keys in place of `passed` and `missed`.
251
+ `reason` tells why gate-cache cannot match the content, and is `null` when it can. When caching is off, `enabled` is `false`, `reason` names the variable, and the other keys are empty or `null`. With `--name`, the object has the `name`, `marker`, `result`, `last_run`, and `duration` keys in place of `passed` and `missed`. `duration` is the run time in seconds of the matching pass, or `null`. With `--path`, `tree` holds the scope value, and the object adds the `paths` and `full_tree` keys.
213
252
 
214
253
  ## Start fresh
215
254
 
@@ -6,12 +6,12 @@ classifiers = [
6
6
  "Programming Language :: Python :: 3.14",
7
7
  "Programming Language :: Python :: 3.15",
8
8
  ]
9
- dependencies = ["platformdirs>=4.13.0,<5.0.0"]
9
+ dependencies = ["platformdirs>=4.14.5,<5.0.0"]
10
10
  description = "Skip lint and test gates that already passed on the exact same git tree."
11
11
  name = "gate-cache"
12
12
  readme = "README.md"
13
13
  requires-python = ">=3.11"
14
- version = "0.6.0"
14
+ version = "0.7.0"
15
15
 
16
16
  [[project.authors]]
17
17
  name = "Nate Landau"
@@ -166,23 +166,23 @@ error-on-warning = true
166
166
 
167
167
  [dependency-groups]
168
168
  dev = [
169
- "commitizen>=4.19.0",
170
- "coverage>=7.16.2",
171
- "duty>=1.10.0",
172
- "pre-commit>=4.6.2",
173
- "prek>=0.5.4",
169
+ "commitizen>=4.19.3",
170
+ "coverage>=7.17.3",
171
+ "duty>=1.10.1",
172
+ "pre-commit>=4.7.0",
173
+ "prek>=0.5.11",
174
174
  "pytest-clarity>=1.0.1",
175
175
  "pytest-cov>=7.1.0",
176
176
  "pytest-devtools>=1.3.0",
177
- "pytest-mock>=3.16.0",
177
+ "pytest-mock>=3.17.0",
178
178
  "pytest-repeat>=0.9.4",
179
179
  "pytest-sugar>=1.1.1",
180
180
  "pytest-xdist>=3.8.0",
181
- "pytest>=9.1.1",
181
+ "pytest>=9.2.0",
182
182
  "rich>=15.0.0",
183
- "ruff>=0.16.9",
183
+ "ruff>=0.17.5",
184
184
  "shellcheck-py>=0.11.0.1",
185
- "ty>=0.0.84",
186
- "typos>=1.50.3",
185
+ "ty>=0.0.104",
186
+ "typos>=1.52.2",
187
187
  "yamllint>=1.38.0",
188
188
  ]
@@ -8,14 +8,14 @@
8
8
  "Programming Language :: Python :: 3.15",
9
9
  ]
10
10
  dependencies = [
11
- "platformdirs>=4.13.0,<5.0.0",
11
+ "platformdirs>=4.14.5,<5.0.0",
12
12
  ]
13
13
  description = "Skip lint and test gates that already passed on the exact same git tree."
14
14
  license = { file = "LICENSE" }
15
15
  name = "gate-cache"
16
16
  readme = "README.md"
17
17
  requires-python = ">=3.11"
18
- version = "0.6.0"
18
+ version = "0.7.0"
19
19
 
20
20
  [project.scripts]
21
21
  gate-cache = "gate_cache.cli:main"
@@ -29,24 +29,24 @@
29
29
 
30
30
  [dependency-groups]
31
31
  dev = [
32
- "commitizen>=4.19.0",
33
- "coverage>=7.16.2",
34
- "duty>=1.10.0",
35
- "pre-commit>=4.6.2",
36
- "prek>=0.5.4",
32
+ "commitizen>=4.19.3",
33
+ "coverage>=7.17.3",
34
+ "duty>=1.10.1",
35
+ "pre-commit>=4.7.0",
36
+ "prek>=0.5.11",
37
37
  "pytest-clarity>=1.0.1",
38
38
  "pytest-cov>=7.1.0",
39
39
  "pytest-devtools>=1.3.0",
40
- "pytest-mock>=3.16.0",
40
+ "pytest-mock>=3.17.0",
41
41
  "pytest-repeat>=0.9.4",
42
42
  "pytest-sugar>=1.1.1",
43
43
  "pytest-xdist>=3.8.0",
44
- "pytest>=9.1.1",
44
+ "pytest>=9.2.0",
45
45
  "rich>=15.0.0",
46
- "ruff>=0.16.9",
46
+ "ruff>=0.17.5",
47
47
  "shellcheck-py>=0.11.0.1",
48
- "ty>=0.0.84",
49
- "typos>=1.50.3",
48
+ "ty>=0.0.104",
49
+ "typos>=1.52.2",
50
50
  "yamllint>=1.38.0",
51
51
  ]
52
52
 
@@ -1,3 +1,3 @@
1
1
  """Skip lint and test gates that already passed on the exact same git tree."""
2
2
 
3
- __version__ = "0.6.0"
3
+ __version__ = "0.7.0"
@@ -5,6 +5,7 @@ from __future__ import annotations
5
5
  import argparse
6
6
  import shlex
7
7
  import sys
8
+ from dataclasses import dataclass
8
9
  from typing import TYPE_CHECKING
9
10
 
10
11
  from gate_cache import __version__
@@ -19,12 +20,16 @@ _INTERRUPTED = 130
19
20
  _INFO_FLAGS = {"-h", "--help", "--version"}
20
21
  _NAME_NEEDS_VALUE = "--name needs a value, e.g. gate-cache --name pytest -- uv run pytest"
21
22
  _NEEDS_SEPARATOR = "put -- before the command, e.g. gate-cache -- uv run pytest"
23
+ _NEEDS_VALUE = {
24
+ "--name": _NAME_NEEDS_VALUE,
25
+ "--path": "--path needs a value, e.g. gate-cache --path src/ -- uv run pytest",
26
+ }
22
27
  _NAME_REPEATED = "--name given more than once"
23
28
  _NO_COMMAND = "no command given after --"
24
29
 
25
30
  _USAGE = """\
26
- gate-cache [--name NAME] -- COMMAND [ARGS...]
27
- gate-cache status [--name NAME] [--json]
31
+ gate-cache [--name NAME] [--path PATHSPEC]... -- COMMAND [ARGS...]
32
+ gate-cache status [--name NAME [--path PATHSPEC]...] [--json]
28
33
  gate-cache clear"""
29
34
 
30
35
  _HELP = """\
@@ -34,11 +39,11 @@ runs the command, records a pass keyed on the git tree of the working copy
34
39
  tree is identical. A pass on uncommitted work therefore skips when the same
35
40
  content is committed.
36
41
 
37
- -- is required, and only --name may come before it. Everything after -- is the
38
- command, verbatim. Without --name, the gate name is the command itself, so each
39
- set of arguments has its own records. Give --name to share records between
40
- commands that check the same thing, or to key on inputs that the tree does not
41
- cover.
42
+ -- is required, and only --name and --path may come before it. Everything after
43
+ -- is the command, verbatim. Without --name, the gate name is the command
44
+ itself, so each set of arguments has its own records. Give --name to share
45
+ records between commands that check the same thing, or to key on inputs that the
46
+ tree does not cover.
42
47
 
43
48
  Exit codes:
44
49
  run the command's own exit code, or 0 when a recorded pass lets it skip.
@@ -63,10 +68,18 @@ secret in a name, because markers and status store it as plain text. Without
63
68
  secret argument. Never wrap checks that depend on the commit message or the
64
69
  branch name.
65
70
 
71
+ --path scopes a gate to the files it reads, so a change elsewhere in the
72
+ repository does not run it again. Each --path is a git pathspec, read from the
73
+ top of the work tree whatever the current directory, and globs and :(exclude)
74
+ work. Repeat --path for each path. The gate skips when nothing under its paths changed,
75
+ so a path left out is a skip that should have run. A path that matches no file
76
+ runs the command without the cache.
77
+
66
78
  Typical use:
67
79
  gate-cache -- uv run pytest -x
68
80
  gate-cache --name pytest -- uv run pytest -x
69
81
  gate-cache --name "test-$(git hash-object .env)" -- uv run pytest
82
+ gate-cache --name api-test --path api/ -- uv run pytest
70
83
  """
71
84
 
72
85
  _RUN_HELP = """\
@@ -75,8 +88,9 @@ subcommands:
75
88
  clear Delete every recorded pass for this repository.
76
89
 
77
90
  run:
78
- gate-cache [--name NAME] -- COMMAND [ARGS...] runs COMMAND unless it already
79
- passed on the current git tree. On a skip, it prints one line to stderr and
91
+ gate-cache [--name NAME] [--path PATHSPEC]... -- COMMAND [ARGS...] runs COMMAND
92
+ unless it already passed on the current git tree, or on the same content under
93
+ its paths. On a skip, it prints one line to stderr and
80
94
  exits 0 without running anything. Otherwise it runs the command and exits with
81
95
  its exit code. The command runs without caching (and nothing is recorded) when
82
96
  GATE_CACHE_DISABLE or CI turns caching off, the tree is unknown (for example an
@@ -91,10 +105,13 @@ Report whether gates would skip, without running anything.
91
105
 
92
106
  With --name, print the tree hash (or why it is unknown), the marker path,
93
107
  hit or miss, and how the last run on this tree failed when it did. Exit 0 on a
94
- hit, 1 otherwise.
108
+ hit, 1 otherwise. Repeat --path with --name to look up a gate scoped to those
109
+ paths.
95
110
 
96
111
  Without --name, list the gates that passed on the current tree and the gates
97
- that ran on it without passing. Exit 0 when at least one gate passed, 1 otherwise.
112
+ that ran on it without passing. Scoped gates are listed when they passed or
113
+ missed on the current content of their paths. Exit 0 when at least one gate
114
+ passed, 1 otherwise.
98
115
  """
99
116
 
100
117
  _CLEAR_HELP = """\
@@ -145,6 +162,12 @@ def _main_parser() -> argparse.ArgumentParser:
145
162
  help="Gate name. Records match only when the name and the tree both match. "
146
163
  "Defaults to the command and its arguments, quoted as a shell would.",
147
164
  )
165
+ parser.add_argument(
166
+ "--path",
167
+ metavar="PATHSPEC",
168
+ help="Key on only the files under this git pathspec, read from the top of the work "
169
+ "tree. Repeat for each path.",
170
+ )
148
171
  return parser
149
172
 
150
173
 
@@ -161,6 +184,13 @@ def _status_parser() -> argparse.ArgumentParser:
161
184
  action=_StoreOnce,
162
185
  help="Gate name to look up. Omit it to list every gate that ran on this tree.",
163
186
  )
187
+ parser.add_argument(
188
+ "--path",
189
+ action="append",
190
+ default=[],
191
+ metavar="PATHSPEC",
192
+ help="Look up the gate scoped to these paths. Repeat for each path. Needs --name.",
193
+ )
164
194
  parser.add_argument(
165
195
  "--json",
166
196
  dest="as_json",
@@ -180,35 +210,62 @@ def _clear_parser() -> argparse.ArgumentParser:
180
210
  )
181
211
 
182
212
 
183
- def _split_run(tokens: list[str]) -> tuple[str | None, list[str]]:
184
- """Split a run invocation into its --name value and the command after the first --.
213
+ @dataclass(frozen=True)
214
+ class _RunArgs:
215
+ """The options before -- and the command after it."""
185
216
 
186
- Only `--name X` or `--name=X` may precede `--`, so a stray option such as `--version`
187
- or the first word of the command can never be mistaken for one of ours.
217
+ name: str | None
218
+ paths: list[str]
219
+ command: list[str]
220
+
221
+
222
+ def _option_value(tokens: list[str], index: int, option: str) -> tuple[str, int] | None:
223
+ """Read `option X` or `option=X` at index, returning the value and the next index.
224
+
225
+ Raises:
226
+ _UsageError: When the option has no value or an empty one, such as an unset shell
227
+ variable.
228
+ """
229
+ arg = tokens[index]
230
+ if arg == option:
231
+ if index + 1 == len(tokens) or tokens[index + 1] == "--":
232
+ raise _UsageError(_NEEDS_VALUE[option])
233
+ value, after = tokens[index + 1], index + 2
234
+ elif arg.startswith(f"{option}="):
235
+ value, after = arg.removeprefix(f"{option}="), index + 1
236
+ else:
237
+ return None
238
+ if not value:
239
+ raise _UsageError(_NEEDS_VALUE[option])
240
+ return value, after
241
+
242
+
243
+ def _split_run(tokens: list[str]) -> _RunArgs:
244
+ """Split a run invocation into its options and the command after the first --.
245
+
246
+ Only `--name` and `--path`, each as `--opt X` or `--opt=X`, may precede `--`, so a stray
247
+ option such as `--version` or the first word of the command can never be mistaken for
248
+ one of ours.
188
249
 
189
250
  Raises:
190
- _UsageError: When anything else precedes `--`, `--` is missing, or `--name` is
191
- missing its value or given twice.
251
+ _UsageError: When anything else precedes `--`, `--` is missing, an option is
252
+ missing its value, or `--name` is given twice.
192
253
  """
193
254
  name: str | None = None
255
+ paths: list[str] = []
194
256
  index = 0
195
257
  while index < len(tokens):
196
- arg = tokens[index]
197
- if arg == "--":
198
- return name, tokens[index + 1 :]
199
- if arg == "--name":
200
- if index + 1 == len(tokens) or tokens[index + 1] == "--":
201
- raise _UsageError(_NAME_NEEDS_VALUE)
202
- value = tokens[index + 1]
203
- index += 2
204
- elif arg.startswith("--name="):
205
- value = arg.removeprefix("--name=")
206
- index += 1
258
+ if tokens[index] == "--":
259
+ return _RunArgs(name=name, paths=paths, command=tokens[index + 1 :])
260
+ if (found := _option_value(tokens=tokens, index=index, option="--name")) is not None:
261
+ if name is not None:
262
+ raise _UsageError(_NAME_REPEATED)
263
+ name, index = found
264
+ elif (found := _option_value(tokens=tokens, index=index, option="--path")) is not None:
265
+ value, index = found
266
+ paths.append(value)
207
267
  else:
208
268
  break
209
- if name is not None:
210
- raise _UsageError(_NAME_REPEATED)
211
- name = value
212
269
  raise _UsageError(_NEEDS_SEPARATOR)
213
270
 
214
271
 
@@ -221,18 +278,22 @@ def _dispatch(tokens: list[str]) -> int:
221
278
  if tokens and tokens[0] in _INFO_FLAGS:
222
279
  _main_parser().parse_args(tokens) # prints help or the version, then exits
223
280
  if tokens and tokens[0] == "status":
224
- args = _status_parser().parse_args(tokens[1:])
225
- return gate_status(args.name, as_json=args.as_json)
281
+ parser = _status_parser()
282
+ args = parser.parse_args(tokens[1:])
283
+ if args.path and args.name is None:
284
+ parser.error("--path needs --name")
285
+ if "" in args.path:
286
+ parser.error(_NEEDS_VALUE["--path"])
287
+ return gate_status(args.name, as_json=args.as_json, paths=args.path)
226
288
  if tokens and tokens[0] == "clear":
227
289
  _clear_parser().parse_args(tokens[1:])
228
290
  return clear_cache()
229
291
 
230
- name, command = _split_run(tokens)
231
- if not command:
292
+ run = _split_run(tokens)
293
+ if not run.command:
232
294
  raise _UsageError(_NO_COMMAND)
233
- if name == "":
234
- raise _UsageError(_NAME_NEEDS_VALUE)
235
- return run_gate(shlex.join(command) if name is None else name, command)
295
+ name = shlex.join(run.command) if run.name is None else run.name
296
+ return run_gate(name, run.command, paths=run.paths)
236
297
 
237
298
 
238
299
  def main() -> None:
@@ -7,6 +7,8 @@ import sys
7
7
 
8
8
  _DIM = "\033[2m"
9
9
  _RESET = "\033[0m"
10
+ _MINUTE = 60
11
+ _HOUR = 3600
10
12
 
11
13
 
12
14
  def say(message: str) -> None:
@@ -41,3 +43,24 @@ def kv(rows: dict[str, str]) -> None:
41
43
  print(f" {dim}{key}{reset}: {pad}{first}") # noqa: T201
42
44
  for line in rest:
43
45
  print(f"{' ' * (2 + cell_width)}{line}") # noqa: T201
46
+
47
+
48
+ def format_duration(seconds: float) -> str:
49
+ """Render a run time compactly for the skip line and status.
50
+
51
+ Args:
52
+ seconds: Elapsed time in seconds.
53
+
54
+ Returns:
55
+ `<1s` below one second, else `42s`, `1m 34s`, or `1h 2m`.
56
+ """
57
+ if seconds < 1:
58
+ return "<1s"
59
+ # Round half up; round() would round half to even.
60
+ total = int(seconds + 0.5)
61
+ if total < _MINUTE:
62
+ return f"{total}s"
63
+ if total < _HOUR:
64
+ return f"{total // _MINUTE}m {total % _MINUTE}s"
65
+ minutes = (total + _MINUTE // 2) // _MINUTE
66
+ return f"{minutes // _MINUTE}h {minutes % _MINUTE}m"