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.
- {gate_cache-0.6.0 → gate_cache-0.7.0}/PKG-INFO +46 -7
- {gate_cache-0.6.0 → gate_cache-0.7.0}/README.md +44 -5
- {gate_cache-0.6.0 → gate_cache-0.7.0}/pyproject.toml +12 -12
- {gate_cache-0.6.0 → gate_cache-0.7.0}/pyproject.toml.orig +12 -12
- {gate_cache-0.6.0 → gate_cache-0.7.0}/src/gate_cache/__init__.py +1 -1
- {gate_cache-0.6.0 → gate_cache-0.7.0}/src/gate_cache/cli.py +99 -38
- {gate_cache-0.6.0 → gate_cache-0.7.0}/src/gate_cache/console.py +23 -0
- {gate_cache-0.6.0 → gate_cache-0.7.0}/src/gate_cache/gate.py +163 -85
- gate_cache-0.7.0/src/gate_cache/markers.py +445 -0
- {gate_cache-0.6.0 → gate_cache-0.7.0}/src/gate_cache/runner.py +7 -1
- {gate_cache-0.6.0 → gate_cache-0.7.0}/src/gate_cache/snapshot.py +124 -21
- gate_cache-0.6.0/src/gate_cache/markers.py +0 -297
- {gate_cache-0.6.0 → gate_cache-0.7.0}/LICENSE +0 -0
- {gate_cache-0.6.0 → gate_cache-0.7.0}/src/gate_cache/git.py +0 -0
- {gate_cache-0.6.0 → gate_cache-0.7.0}/src/gate_cache/scratch.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.3
|
|
2
2
|
Name: gate-cache
|
|
3
|
-
Version: 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.
|
|
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
|
-
|
|
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 `
|
|
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
|
-
|
|
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 `
|
|
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.
|
|
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.
|
|
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.
|
|
170
|
-
"coverage>=7.
|
|
171
|
-
"duty>=1.10.
|
|
172
|
-
"pre-commit>=4.
|
|
173
|
-
"prek>=0.5.
|
|
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.
|
|
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.
|
|
181
|
+
"pytest>=9.2.0",
|
|
182
182
|
"rich>=15.0.0",
|
|
183
|
-
"ruff>=0.
|
|
183
|
+
"ruff>=0.17.5",
|
|
184
184
|
"shellcheck-py>=0.11.0.1",
|
|
185
|
-
"ty>=0.0.
|
|
186
|
-
"typos>=1.
|
|
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.
|
|
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.
|
|
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.
|
|
33
|
-
"coverage>=7.
|
|
34
|
-
"duty>=1.10.
|
|
35
|
-
"pre-commit>=4.
|
|
36
|
-
"prek>=0.5.
|
|
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.
|
|
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.
|
|
44
|
+
"pytest>=9.2.0",
|
|
45
45
|
"rich>=15.0.0",
|
|
46
|
-
"ruff>=0.
|
|
46
|
+
"ruff>=0.17.5",
|
|
47
47
|
"shellcheck-py>=0.11.0.1",
|
|
48
|
-
"ty>=0.0.
|
|
49
|
-
"typos>=1.
|
|
48
|
+
"ty>=0.0.104",
|
|
49
|
+
"typos>=1.52.2",
|
|
50
50
|
"yamllint>=1.38.0",
|
|
51
51
|
]
|
|
52
52
|
|
|
@@ -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
|
|
38
|
-
command, verbatim. Without --name, the gate name is the command
|
|
39
|
-
set of arguments has its own records. Give --name to share
|
|
40
|
-
commands that check the same thing, or to key on inputs that the
|
|
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
|
|
79
|
-
passed on the current git tree
|
|
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.
|
|
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
|
-
|
|
184
|
-
|
|
213
|
+
@dataclass(frozen=True)
|
|
214
|
+
class _RunArgs:
|
|
215
|
+
"""The options before -- and the command after it."""
|
|
185
216
|
|
|
186
|
-
|
|
187
|
-
|
|
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,
|
|
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
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
index
|
|
204
|
-
|
|
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
|
-
|
|
225
|
-
|
|
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
|
-
|
|
231
|
-
if not command:
|
|
292
|
+
run = _split_run(tokens)
|
|
293
|
+
if not run.command:
|
|
232
294
|
raise _UsageError(_NO_COMMAND)
|
|
233
|
-
if name
|
|
234
|
-
|
|
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"
|