gate-cache 0.7.0__tar.gz → 0.9.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.
Files changed (66) hide show
  1. gate_cache-0.9.0/PKG-INFO +503 -0
  2. gate_cache-0.9.0/README.md +467 -0
  3. {gate_cache-0.7.0 → gate_cache-0.9.0}/pyproject.toml +6 -2
  4. {gate_cache-0.7.0 → gate_cache-0.9.0}/pyproject.toml.orig +3 -2
  5. {gate_cache-0.7.0 → gate_cache-0.9.0}/src/gate_cache/__init__.py +1 -1
  6. gate_cache-0.9.0/src/gate_cache/agent/prompt.md +24 -0
  7. gate_cache-0.9.0/src/gate_cache/agent/skill.md +181 -0
  8. gate_cache-0.9.0/src/gate_cache/cli.py +637 -0
  9. gate_cache-0.9.0/src/gate_cache/config.py +51 -0
  10. gate_cache-0.9.0/src/gate_cache/console.py +115 -0
  11. gate_cache-0.9.0/src/gate_cache/dashboard/__init__.py +1 -0
  12. gate_cache-0.9.0/src/gate_cache/dashboard/app.py +136 -0
  13. gate_cache-0.9.0/src/gate_cache/dashboard/server.py +533 -0
  14. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Arc.svelte-CNpcs8X3.js +1 -0
  15. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Bar-0aBK7UpN.js +1 -0
  16. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Bar-DcuSsIRy.css +1 -0
  17. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/BrushContext.svelte-CCZcZhce.js +1 -0
  18. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/ChartAnnotations.svelte-rQYciYRB.js +1 -0
  19. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/DefaultTooltip-B5CAhh2Q.css +1 -0
  20. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/DefaultTooltip-CY_C86gN.js +1 -0
  21. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Labels-DR5FYZws.js +1 -0
  22. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Labels-sEaJtb97.css +1 -0
  23. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Legend-DeowBKKb.css +1 -0
  24. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Legend-d30gUpuK.js +1 -0
  25. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Path-MiPiAzgz.css +1 -0
  26. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Path.canvas-DOOOEuJg.js +1 -0
  27. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Path.svg-BEFmR18I.js +2 -0
  28. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Points-Boe_SZ9_.js +1 -0
  29. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Points.html-DjDCSC2I.js +1 -0
  30. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Spline-1ZDp-X2F.js +1 -0
  31. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/TransformContext.svelte-BICq8-YE.js +1 -0
  32. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Voronoi.svelte-UEy6r0as.js +1 -0
  33. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/d3-quadtree-DlddCuIi.js +1 -0
  34. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/d3-scale-BZIMHxO8.js +1 -0
  35. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/index-Bp9x91ei.css +1 -0
  36. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/index-CYgojWsw.js +21 -0
  37. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/index-client-B3yOqiGu.js +2 -0
  38. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/key.svelte-B7SM1zzp.js +1 -0
  39. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/scales.svelte-CzvR6oHT.js +1 -0
  40. gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/transition-7dBkedGA.js +6 -0
  41. gate_cache-0.9.0/src/gate_cache/dashboard/static/favicon.svg +1 -0
  42. gate_cache-0.9.0/src/gate_cache/dashboard/static/index.html +23 -0
  43. gate_cache-0.9.0/src/gate_cache/dashboard/static/theme.js +11 -0
  44. gate_cache-0.9.0/src/gate_cache/env.py +17 -0
  45. gate_cache-0.9.0/src/gate_cache/gate.py +1015 -0
  46. gate_cache-0.9.0/src/gate_cache/gate_lock.py +284 -0
  47. {gate_cache-0.7.0 → gate_cache-0.9.0}/src/gate_cache/markers.py +16 -8
  48. {gate_cache-0.7.0 → gate_cache-0.9.0}/src/gate_cache/runner.py +51 -9
  49. {gate_cache-0.7.0 → gate_cache-0.9.0}/src/gate_cache/snapshot.py +188 -56
  50. gate_cache-0.9.0/src/gate_cache/stats/__init__.py +1 -0
  51. gate_cache-0.9.0/src/gate_cache/stats/archive.py +442 -0
  52. gate_cache-0.9.0/src/gate_cache/stats/clear.py +58 -0
  53. gate_cache-0.9.0/src/gate_cache/stats/config.py +197 -0
  54. gate_cache-0.9.0/src/gate_cache/stats/context.py +521 -0
  55. gate_cache-0.9.0/src/gate_cache/stats/lock.py +74 -0
  56. gate_cache-0.9.0/src/gate_cache/stats/queries.py +1309 -0
  57. gate_cache-0.9.0/src/gate_cache/stats/recorder.py +255 -0
  58. gate_cache-0.9.0/src/gate_cache/wait_settings.py +110 -0
  59. gate_cache-0.7.0/PKG-INFO +0 -323
  60. gate_cache-0.7.0/README.md +0 -287
  61. gate_cache-0.7.0/src/gate_cache/cli.py +0 -308
  62. gate_cache-0.7.0/src/gate_cache/console.py +0 -66
  63. gate_cache-0.7.0/src/gate_cache/gate.py +0 -427
  64. {gate_cache-0.7.0 → gate_cache-0.9.0}/LICENSE +0 -0
  65. {gate_cache-0.7.0 → gate_cache-0.9.0}/src/gate_cache/git.py +0 -0
  66. {gate_cache-0.7.0 → gate_cache-0.9.0}/src/gate_cache/scratch.py +0 -0
@@ -0,0 +1,503 @@
1
+ Metadata-Version: 2.3
2
+ Name: gate-cache
3
+ Version: 0.9.0
4
+ Summary: Skip lint and test gates that already passed on the exact same git tree.
5
+ Author: Nate Landau
6
+ Author-email: Nate Landau <github@natenate.org>
7
+ License: MIT License
8
+
9
+ Copyright (c) 2026 Nate Landau
10
+
11
+ Permission is hereby granted, free of charge, to any person obtaining a copy
12
+ of this software and associated documentation files (the "Software"), to deal
13
+ in the Software without restriction, including without limitation the rights
14
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15
+ copies of the Software, and to permit persons to whom the Software is
16
+ furnished to do so, subject to the following conditions:
17
+
18
+ The above copyright notice and this permission notice shall be included in all
19
+ copies or substantial portions of the Software.
20
+
21
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27
+ SOFTWARE.
28
+ Classifier: Programming Language :: Python :: 3.11
29
+ Classifier: Programming Language :: Python :: 3.12
30
+ Classifier: Programming Language :: Python :: 3.13
31
+ Classifier: Programming Language :: Python :: 3.14
32
+ Classifier: Programming Language :: Python :: 3.15
33
+ Requires-Dist: platformdirs>=4.14.5,<5.0.0
34
+ Requires-Python: >=3.11
35
+ Description-Content-Type: text/markdown
36
+
37
+ # gate-cache
38
+
39
+ Skip a command that already passed on the same code.
40
+
41
+ A lint or test command often runs many times on code that did not change. It runs when you finish the work, in a pre-commit hook, after a rebase that changed nothing, and in a pre-push hook. When an agent works in the repository, it runs the same command again. If the command takes minutes, the repeat runs take most of the time between finished code and a pushed branch.
42
+
43
+ gate-cache remembers which commands passed on which code. It wraps a command, and the command line is the name of the gate. When the command passes, gate-cache writes a marker for that name and for the exact content of the files in the working copy that git does not ignore. The next time the same name runs on the same content, gate-cache finds the marker, skips the command, and exits 0 at once.
44
+
45
+ ```console
46
+ $ gate-cache -- uv run pytest
47
+ ============================= 412 passed in 94.20s =============================
48
+
49
+ $ gate-cache -- uv run pytest
50
+ gate-cache: uv run pytest already passed on tree aaff74984ccc, skipping (saved 1m 34s)
51
+ ```
52
+
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.
56
+
57
+ ## Install
58
+
59
+ gate-cache requires Python 3.11 or later, on macOS or Linux.
60
+
61
+ ```sh
62
+ uv tool install gate-cache
63
+ ```
64
+
65
+ The prek and pre-commit hooks install gate-cache themselves, so the hooks work without this step. In a project without Python tooling, `uvx gate-cache` runs gate-cache without an install.
66
+
67
+ ## Add gate-cache to a project with an agent
68
+
69
+ A coding agent can add gate-cache to a project in any language. Open an agent session at the top of the repository and give it this prompt:
70
+
71
+ ```text
72
+ Run `uvx gate-cache --prompt` and follow the instructions that it prints.
73
+ ```
74
+
75
+ The agent reads the guide that gate-cache prints and asks you which commands to wrap, how to install gate-cache, which gates to scope to their paths, and whether git hooks run the gates. Then it wraps the commands, makes sure that each gate works, and stops before it commits. The instructions always match the version of gate-cache that the agent runs.
76
+
77
+ If the repository already uses gate-cache, the agent reviews the setup instead. It compares each gate with the guide of the latest gate-cache release, and reports any defects and any features that the setup does not use. It changes nothing until you choose which recommendations to apply.
78
+
79
+ Two flags print text for agents:
80
+
81
+ - `gate-cache --prompt` prints the setup and review task that the agent follows.
82
+ - `gate-cache --skill` prints the guide for an agent that works in a repository that uses gate-cache. The output is a `SKILL.md` file. To give it to Claude Code in every session, save it as a skill:
83
+
84
+ ```sh
85
+ mkdir -p ~/.claude/skills/gate-cache
86
+ gate-cache --skill > ~/.claude/skills/gate-cache/SKILL.md
87
+ ```
88
+
89
+ Run the second command again after you upgrade gate-cache. `gate-cache --help` tells agents to run `gate-cache --skill`, so an agent without the saved skill also finds the guide.
90
+
91
+ ## Run a command through gate-cache
92
+
93
+ The command goes after `--`:
94
+
95
+ ```sh
96
+ gate-cache -- uv run pytest
97
+ gate-cache -- uv run ruff check .
98
+ ```
99
+
100
+ The command and its arguments are the name of the gate. Each name has its own markers, so a pass of `uv run pytest -k unit` never skips `uv run pytest`.
101
+
102
+ To choose the name yourself, put `--name` before `--`:
103
+
104
+ ```sh
105
+ gate-cache --name pytest -- uv run pytest
106
+ ```
107
+
108
+ With `--name`, the name alone identifies the gate, and the arguments of the command are not part of it. Give a name when two different command lines do the same check and must share markers, or when a gate depends on [inputs that git does not track](#inputs-that-git-does-not-track).
109
+
110
+ gate-cache exits with the exit code of the command, or with 0 when it skips the command. It writes a marker only when the command passes, so a command that failed runs again the next time.
111
+
112
+ 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.
113
+
114
+ ## Run the same gate twice at once
115
+
116
+ If a run finds another run of the same gate in progress on the same content, it waits. The two runs have the same name and the same tree, and they can be in different worktrees of the repository. The waiting run prints a line that names the worktree of the other run and its age:
117
+
118
+ ```console
119
+ $ gate-cache -- uv run pytest
120
+ gate-cache: uv run pytest is running in /work/app-feature (started 1m 12s ago), waiting
121
+ gate-cache: uv run pytest already passed on tree aaff74984ccc, skipping (saved 1m 34s)
122
+ ```
123
+
124
+ The wait is not a hang. When the other run ends, gate-cache checks the content again. If the other run passed, the waiting run skips. Otherwise it runs the command.
125
+
126
+ A run waits at most 15 minutes in total. After that, gate-cache prints `running anyway` and runs the command. [Settings](#settings) shows how to change the limit and how to report the failure of the other run instead of running again. Waiting works on macOS and Linux.
127
+
128
+ ## Scope a gate to its paths
129
+
130
+ 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:
131
+
132
+ ```sh
133
+ gate-cache --name api-test --path api/ --path uv.lock -- uv run pytest api/tests
134
+ ```
135
+
136
+ 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.
137
+
138
+ 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:
139
+
140
+ ```sh
141
+ gate-cache --name scripts-test --path scripts/ --path ':(exclude)scripts/fixtures/' -- uv run pytest scripts
142
+ ```
143
+
144
+ 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`.
145
+
146
+ > **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.
147
+
148
+ 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.
149
+
150
+ ## Run it as a hook
151
+
152
+ 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:
153
+
154
+ ```yaml
155
+ repos:
156
+ - repo: https://github.com/natelandau/gate-cache
157
+ rev: v0.9.0
158
+ hooks:
159
+ - id: gate-cache
160
+ name: pytest
161
+ args: [--, uv, run, pytest]
162
+ files: ^(src/|tests/)
163
+ - id: gate-cache
164
+ name: ruff
165
+ args: [--, uv, run, ruff, check, .]
166
+ ```
167
+
168
+ The hook runs at commit time and at push time. At commit time, gate-cache matches the content that you commit.
169
+
170
+ The hook runs in its own virtual environment, and the wrapped command inherits that environment. A command started with `uv run`, or a project command such as `just test`, runs in the project environment. `uv run` prints a warning that `VIRTUAL_ENV` does not match the project. The warning has no effect on the run.
171
+
172
+ The gate-cache that a hook installs records stats when recording is on, but that install has no dashboard UI. Only a release wheel contains the UI, and a hook builds gate-cache from source. A git or path dependency also builds from source and has no UI. To view the dashboard, run `gate-cache dashboard` from the install that `uv tool install gate-cache` makes.
173
+
174
+ Hooks, agents, and your terminal all read and write the same markers. When one of them runs `gate-cache -- uv run pytest` and it passes, the others skip `uv run pytest` on the same content.
175
+
176
+ ## Examples
177
+
178
+ These examples show gate-cache inside the task runner of a project. When a recipe holds the wrapped command, everything that runs the recipe uses the same name and the same markers.
179
+
180
+ ### justfile
181
+
182
+ ```just
183
+ test:
184
+ gate-cache -- uv run pytest
185
+
186
+ lint:
187
+ gate-cache -- uv run ruff check .
188
+ ```
189
+
190
+ After `just test` passes, the next `just test` on the same content skips pytest.
191
+
192
+ ### Recipes with arguments
193
+
194
+ A recipe that passes its arguments to the command needs no `--name`. Each set of arguments gives a different command line, so each set has its own markers:
195
+
196
+ ```just
197
+ test *args:
198
+ gate-cache -- uv run pytest {{ args }}
199
+ ```
200
+
201
+ `just test` runs under the name `uv run pytest`, and `just test -k unit` runs under the name `uv run pytest -k unit`. A pass of the unit tests never skips the full suite.
202
+
203
+ If the recipe gives `--name`, the arguments are not part of the name. Put them in the name, or a pass of `just test -k unit` also skips `just test`.
204
+
205
+ An absolute path in the command, such as `{{ justfile_directory() }}/tests`, puts the location of the worktree in the name. Each worktree then has its own markers, so a pass in one worktree never skips the gate in another. To share markers across worktrees, use relative paths.
206
+
207
+ ### Inputs that git does not track
208
+
209
+ A marker does not cover ignored files, environment variables, or tool versions. To make a gate depend on one of these inputs, put its value in the name, after an `@`. When the value changes, the name changes, so no marker matches and the command runs again:
210
+
211
+ ```just
212
+ # Run again when the uv version changes
213
+ test:
214
+ gate-cache --name "test@uv$(uv --version | cut -d' ' -f2)" -- uv run pytest
215
+
216
+ # Run again when the ignored .env file changes
217
+ integration:
218
+ gate-cache --name "integration@$(git hash-object .env)" -- uv run pytest tests/integration
219
+ ```
220
+
221
+ The text before the first `@` is the gate, and the text after it is the key. The stats dashboard counts the runs of every key toward the gate, so `test@uv0.13.0` and `test@uv0.14.0` show as one gate, `test`. This rule applies only to a name with no spaces and with text on both sides of the `@`. A name with a space, such as a command line, is one gate. To key on more than one input, join the values after one `@`, such as `test@node22-3f2a9c`.
222
+
223
+ `git hash-object` prints a hash of the file, so the name does not hold the secrets in `.env`. Do not put a secret value in a name, because the marker and `gate-cache status` record the name as plain text. Without `--name`, the command line is the name, so give `--name` to a command that takes a secret as an argument.
224
+
225
+ The shell of the recipe expands `$(...)` before gate-cache starts. A hook `entry` or `args` list does not go through a shell, so put the command in a recipe and call the recipe from the hook. To look up the gate with `gate-cache status --name`, give the expanded name, such as `test@uv0.13.0`.
226
+
227
+ ### Makefile
228
+
229
+ ```make
230
+ test:
231
+ gate-cache -- uv run pytest
232
+
233
+ lint:
234
+ gate-cache -- uv run ruff check .
235
+ ```
236
+
237
+ ### A hook that calls the recipe
238
+
239
+ A local hook can run the recipe instead of the gate-cache hook repository:
240
+
241
+ ```yaml
242
+ repos:
243
+ - repo: local
244
+ hooks:
245
+ - id: test
246
+ name: test
247
+ entry: just test
248
+ language: system
249
+ pass_filenames: false
250
+ stages: [pre-commit, pre-push]
251
+ ```
252
+
253
+ With this hook, a commit, a push, an agent, and your terminal all run `just test` and share its markers. The recipe runs in the project environment, so `uv run` prints no `VIRTUAL_ENV` warning. This form needs `gate-cache` and `just` on the `PATH`.
254
+
255
+ ### CI
256
+
257
+ gate-cache turns off caching when the `CI` variable is on. A variable is on when its value is not empty, `0`, or `false`. Case and spaces around the value do not matter. Many CI systems set `CI=true` in every job, for example GitHub Actions and GitLab CI/CD. Jenkins does not set `CI`.
258
+
259
+ When caching is off, gate-cache runs the command each time and writes no marker.
260
+
261
+ `GATE_CACHE_DISABLE` overrides `CI`. To keep caching on when `CI` is on, set `GATE_CACHE_DISABLE` to `0` or `false`:
262
+
263
+ ```sh
264
+ GATE_CACHE_DISABLE=0 just test
265
+ ```
266
+
267
+ To turn off caching when `CI` is not set, set `GATE_CACHE_DISABLE` to `1`:
268
+
269
+ ```sh
270
+ GATE_CACHE_DISABLE=1 just test
271
+ ```
272
+
273
+ ## See what already passed
274
+
275
+ `gate-cache status` lists the names that passed on the current content, and the names that ran on it without a pass:
276
+
277
+ ```console
278
+ $ gate-cache status
279
+ tree: aaff74984cccd156a469afa7d9ab10e4777beb24
280
+ passed: uv run pytest
281
+ missed: uv run ruff check . (exit code 1)
282
+ ```
283
+
284
+ A name is missed when its command failed, or when it exited 0 but changed the files. A later pass of the same name removes it from the `missed` line.
285
+
286
+ With `--name`, it reports on one name. For a gate that ran without `--name`, give the same command after `--`. gate-cache then looks up the command line as the name:
287
+
288
+ ```console
289
+ $ gate-cache status -- uv run ruff check .
290
+ name: uv run ruff check .
291
+ tree: aaff74984cccd156a469afa7d9ab10e4777beb24
292
+ marker: /path/to/repo/.git/gate-cache/7d94ca2f57ec0a77f60d328fb405d339fb0c2a645991b97c042ac54403104e9e
293
+ result: miss
294
+ last run: exit code 1
295
+ ```
296
+
297
+ 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.
298
+
299
+ For a scoped gate, give the same `--path` options with `--name` or the command. The report adds a `paths` line and a `scope` line, and the `tree` line shows the whole tree:
300
+
301
+ ```console
302
+ $ gate-cache status --name api-test --path api/ --path uv.lock
303
+ name: api-test
304
+ paths: api/ uv.lock
305
+ scope: paths:7c462ce94adead1b7ab99f8e4212ffac194c562e0d178151207c1f01e0073615
306
+ tree: aaff74984cccd156a469afa7d9ab10e4777beb24
307
+ marker: /path/to/repo/.git/gate-cache/4156a896efe2ed16204b6d2525acbfbd9c4dd808dbfc135571e4f631b7d7754a
308
+ result: hit
309
+ duration: 1m 34s
310
+ ```
311
+
312
+ Without `--name` or a command, `status` also lists the scoped gates that passed or missed on the current content of their paths.
313
+
314
+ `status` runs nothing. With `--name` or a command, it exits 0 when a marker matches and 1 when none does. Without either, 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.
315
+
316
+ With `--json`, `status` writes one JSON object to stdout instead of text. The exit codes do not change:
317
+
318
+ ```console
319
+ $ gate-cache status --json
320
+ {
321
+ "enabled": true,
322
+ "tree": "aaff74984cccd156a469afa7d9ab10e4777beb24",
323
+ "reason": null,
324
+ "passed": ["uv run pytest"],
325
+ "missed": [
326
+ {"name": "uv run ruff check .", "exit_code": 1, "reason": "exit code 1", "timestamp": "2026-10-12T12:31:55Z"}
327
+ ]
328
+ }
329
+ ```
330
+
331
+ `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.
332
+
333
+ ## Start fresh
334
+
335
+ A marker records only the content of the files that git does not ignore. A new tool version, a changed environment variable, or a change to a service does not change that content, so the old markers still match. To make a gate run again when one of these inputs changes, put the input in the name, as [Inputs that git does not track](#inputs-that-git-does-not-track) shows.
336
+
337
+ `gate-cache clear` permanently deletes every marker for the repository, and the records of missed runs. After a clear, every gate runs again in full. Before it deletes anything, it shows a warning and asks you to type `yes`. Any other answer stops the command with exit code 1, and no markers are deleted:
338
+
339
+ ```console
340
+ $ gate-cache clear
341
+ gate-cache: WARNING: this permanently deletes every recorded pass for this repository.
342
+ gate-cache: markers: /path/to/repo/.git/gate-cache
343
+ gate-cache: Every gate runs again in full, even on code that already passed.
344
+ gate-cache: Recorded run stats are not affected.
345
+ gate-cache: This cannot be undone.
346
+ gate-cache: type 'yes' to clear markers: yes
347
+ gate-cache: removed 3 markers
348
+ ```
349
+
350
+ If standard input is not a terminal, as in a script, the command refuses with exit code 1 unless you give `--yes` (or `-y`):
351
+
352
+ ```sh
353
+ gate-cache clear --yes
354
+ ```
355
+
356
+ `GATE_CACHE_DISABLE=1` runs every command without the cache, for one command or for a whole session:
357
+
358
+ ```sh
359
+ GATE_CACHE_DISABLE=1 git push
360
+ ```
361
+
362
+ ## Stats dashboard
363
+
364
+ gate-cache can record each run of a gate and show the record in a local dashboard. The dashboard shows how much time the skips saved, and how much remains after the time that gate-cache itself used. It also shows how often gates skip, how often a run waited for another run of the same gate, and which gates fail and pass on the same content. Recording is off until you turn it on:
365
+
366
+ ```sh
367
+ gate-cache stats on
368
+ ```
369
+
370
+ `gate-cache stats` without an action shows whether recording is on, what decided it, and where the config file and the data live:
371
+
372
+ ```console
373
+ $ gate-cache stats
374
+ recording: on
375
+ decided by: config
376
+ config: /path/to/config/gate-cache/config.toml
377
+ data: /path/to/state/gate-cache
378
+ ```
379
+
380
+ The paths depend on your system, so run the command to see them. `gate-cache stats off` turns recording off. Both actions write `[stats] enabled` in the config file and keep every other line of the file. Recorded data stays in place when you turn recording off.
381
+
382
+ To open the dashboard, run:
383
+
384
+ ```sh
385
+ gate-cache dashboard
386
+ ```
387
+
388
+ The dashboard listens on `127.0.0.1` and opens in your browser. It listens on port 7878, or on a free port when 7878 is taken. With `--port N`, it listens on that port only, and the command fails when the port is in use. With `--no-browser`, it does not open a browser. Only one dashboard runs at a time. A second `gate-cache dashboard` prints the address of the running one and opens it, unless you give `--no-browser`. Press Ctrl-C to stop it.
389
+
390
+ The dashboard has pages for an overview, gates, recent activity, and flaky gates. The range picker at the top sets the time range. You can pick a relative range such as 7 days, a calendar period such as This week, or custom dates. The repo filter at the top accepts several repositories at once. On the overview, the Breakdown panel groups the runs by repo, gate, source (such as a git hook, CI, or a coding agent), branch, or machine. Click a repo to filter the dashboard to it, a gate to open its details, or any other row to see its runs. A gate that ran without `--name` shows its command line on one line, and you see the full command when you hover over it. When a gate has more than one key, the gate details, Activity, Recent failures, and Flaky show the key of each run. To scope the overview to some days, click a day on the calendar or the daily chart, or drag across days on the daily chart. Click the same day again or remove the chip to see the whole range again. A count on the overview, such as failures or an outcome, opens the Activity page with the runs that the count stands for. The dashboard updates while it runs, so new runs appear within seconds. The theme button at the top right cycles between the system theme (the default), light, and dark, and the dashboard remembers your choice.
391
+
392
+ The dashboard also shows what your gates cost to run. The Time gates ran card is the total time that gates ran, failed runs included, with its change against the previous period. It does not count the time that gate-cache itself used or waited. Under the daily chart, the Time gates ran chart shows one bar per day, split into the five gates that took the most time and Other. It has All, Passing, and Failing views, and you pick days on it the same way as on the daily chart. A legend entry opens the details of that gate. Top gates can rank by Time ran and shows the average and median run time of each gate. The Breakdown panel has a Time ran column, and Avg run and Median run columns when it groups by gate. Click a column header to sort by it. A header with a dotted underline explains its column when you hover or focus it, and an info icon on a headline card does the same for the card. The first column of a wide table stays in view while the table scrolls sideways. The Gates table adds these columns:
393
+
394
+ - Time ran: the total time that the gate ran.
395
+ - Avg run, Median run, and p90 run: the average run time of the passing runs, and the run times that half and nine tenths of them do not exceed.
396
+ - CPU/wall: the CPU seconds per second of run time. A value near 1x means that the gate used one core.
397
+ - Peak memory: the highest memory use of a run.
398
+ - Saved by cache: the run time that skipped calls did not spend.
399
+ - Lost to failures: the time that failed runs used.
400
+
401
+ The details of a gate show a histogram of its run times, which needs 5 passing runs. They split failures into early failures, which ended before half of the median passing run, and late failures. They also show the time that the gate ran by source. Average, median, and p90 count passing runs only. CPU and memory show only for runs that recorded them. Skipped runs and runs from older gate-cache versions show n/a.
402
+
403
+ `gate-cache stats clear` permanently deletes all recorded stats. You cannot undo it. Like `gate-cache clear`, it shows a warning and asks you to type `yes`. Any other answer stops the command with exit code 1, and no stats are deleted. While it waits for your answer, `gate-cache dashboard` cannot start, and it reports that a dashboard is already running or that stats clear is in progress. If standard input is not a terminal, as in a script, the command refuses with exit code 1 unless you give `--yes` (or `-y`):
404
+
405
+ ```sh
406
+ gate-cache stats clear --yes
407
+ ```
408
+
409
+ It keeps the random machine ID. It refuses while the dashboard runs. It does not delete markers. Use `gate-cache clear` for those.
410
+
411
+ ### What gate-cache records
412
+
413
+ Each run of a gate adds one event with these fields:
414
+
415
+ - the time the run finished
416
+ - the path of the git directory of the repository
417
+ - the gate name and the `--path` values
418
+ - the tree key that the run used
419
+ - the outcome
420
+ - the run time of the command, and the time that a skip saved
421
+ - the exit code of the command
422
+ - the reason that caching was off, for a run without the cache
423
+ - the gate-cache version, the platform, and what started the run: CI, a git hook, a coding agent, or a terminal
424
+ - the path of the working tree, the directory in it where the gate ran, the branch, and the commit
425
+ - the URL of the `origin` remote, without user names or credentials
426
+ - the host name of the machine and a random machine ID
427
+ - the time that gate-cache took to decide, the age of the marker of a skip, and the CPU time and peak memory of the command
428
+ - the full command line, when `--name` gives a name that is not the command line
429
+ - the time the run waited for another run of the same gate, whether the wait reached its limit, and whether the run reported the failure of that run instead of running the command
430
+
431
+ An event holds no command output and no file content. The gate name is the command line unless you give `--name`, so a secret in a command line is in the record. When you give `--name`, the event also holds the command line, so a secret that you give to the command as an argument is in the record. Never put a secret in a gate name or in a command line. The working tree path and the host name often contain your user name or your real name. The machine ID is random and does not identify you. Recording is off until you turn it on. The data never leaves your machine, and `gate-cache stats clear` deletes it. The dashboard listens only on `127.0.0.1` and rejects requests for any other host name. Its pages load scripts, styles, and images only from the dashboard itself, and other sites cannot show the dashboard in a frame. The one outside request is the dashboard font, Geist, from `cdn.jsdelivr.net`. That request sends no stats data. Without a connection to jsDelivr, the dashboard uses your system font.
432
+
433
+ ### When recording is on
434
+
435
+ The setting comes from the first of these that applies:
436
+
437
+ 1. `GATE_CACHE_STATS`, when it is not empty. A value of `0` or `false` turns recording off, and any other value turns it on.
438
+ 2. `CI`. When `CI` is on, recording is off.
439
+ 3. `[stats] enabled` in the config file.
440
+ 4. Off.
441
+
442
+ A CI runner is not your machine, so CI does not record unless `GATE_CACHE_STATS` is on. Recording never changes whether a command skips, its exit code, or its output. A failure to record is silent.
443
+
444
+ ### Where the data lives
445
+
446
+ The data directory comes from the first of these that applies:
447
+
448
+ 1. `GATE_CACHE_DATA_DIR`, when it is not empty. A relative path starts from the current directory.
449
+ 2. `data_dir` in the `[stats]` table of the config file, when it is a text value that is not empty. A relative path starts from the directory of the config file, so every repository uses the same data.
450
+ 3. The state directory of your platform.
451
+
452
+ A leading `~` in either value expands to your home directory. gate-cache ignores a `data_dir` value that is not text. `gate-cache stats` shows the data directory that applies.
453
+
454
+ ```toml
455
+ [stats]
456
+ enabled = true
457
+ data_dir = "~/gate-cache-stats"
458
+ ```
459
+
460
+ To try the dashboard on test data and keep your real stats unchanged, set a separate data directory:
461
+
462
+ ```sh
463
+ GATE_CACHE_DATA_DIR=/tmp/gc-uat GATE_CACHE_STATS=1 gate-cache dashboard
464
+ ```
465
+
466
+ ## Settings
467
+
468
+ Five environment variables control gate-cache.
469
+
470
+ | Variable | Effect | Default |
471
+ | ------------------------- | ------------------------------------------------------------------------------ | ------- |
472
+ | `GATE_CACHE_DISABLE` | If on, turns off caching. If `0` or `false`, keeps caching on when `CI` is on. | not set |
473
+ | `CI` | If on, turns off caching. A value in `GATE_CACHE_DISABLE` overrides it. | not set |
474
+ | `GATE_CACHE_MAX_AGE_DAYS` | Each time gate-cache records a result, it deletes markers older than this number of days. | `30` |
475
+ | `GATE_CACHE_STATS` | If on, records stats, even in CI. If `0` or `false`, turns recording off. If empty, `CI` and then the config file decide. | not set |
476
+ | `GATE_CACHE_DATA_DIR` | The directory for recorded stats. If empty, `[stats] data_dir` in the config file and then the platform state directory decide. | not set |
477
+
478
+ A variable is on when its value is not empty, `0`, or `false`. Case and spaces around the value do not matter.
479
+
480
+ ### Waiting for a concurrent run
481
+
482
+ The `[wait]` table of the config file, the file that `gate-cache stats` shows, sets two values. Each flag below goes before `--` and overrides its config value.
483
+
484
+ | Config key | Flag | Effect | Default |
485
+ | ---------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
486
+ | `timeout` | `--wait-timeout SECONDS` | The longest total wait of one run, in whole seconds. `0` turns waiting off. | `900` |
487
+ | `failed` | `--on-wait-failure rerun\|report` | What a run does when the run that it waited for failed. `rerun` runs the command. `report` prints `NAME failed on tree HASH in WORKTREE (exit N), not running again` and exits with that code. | `rerun` |
488
+
489
+ ```toml
490
+ [wait]
491
+ timeout = 300
492
+ failed = "report"
493
+ ```
494
+
495
+ An invalid value in the config file prints a warning and uses the default. With `report`, only a command that exited with a code other than 0 counts as a failure. A run that passed but changed files, or a run that was interrupted, does not.
496
+
497
+ Each marker is one small file in the `.git` directory of the repository, so all worktrees of the repository share the markers. Waiting uses lock files in `.git/gate-cache-locks/`. gate-cache deletes old lock files with old markers, and `gate-cache clear` leaves them in place.
498
+
499
+ ## Learn more
500
+
501
+ - [How gate-cache works](docs/how-it-works.md) describes the exact rules for a skip, what a marker covers, the marker format for tools that read markers directly, and how gate-cache stores and measures stats.
502
+ - `gate-cache --help` gives the full command reference.
503
+ - `gate-cache --skill` gives the guide for coding agents.