gate-cache 0.6.0__tar.gz → 0.8.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 (68) hide show
  1. gate_cache-0.8.0/PKG-INFO +488 -0
  2. gate_cache-0.8.0/README.md +452 -0
  3. {gate_cache-0.6.0 → gate_cache-0.8.0}/pyproject.toml +17 -13
  4. {gate_cache-0.6.0 → gate_cache-0.8.0}/pyproject.toml.orig +14 -13
  5. {gate_cache-0.6.0 → gate_cache-0.8.0}/src/gate_cache/__init__.py +1 -1
  6. gate_cache-0.8.0/src/gate_cache/agent/prompt.md +11 -0
  7. gate_cache-0.8.0/src/gate_cache/agent/skill.md +177 -0
  8. gate_cache-0.8.0/src/gate_cache/cli.py +636 -0
  9. gate_cache-0.8.0/src/gate_cache/config.py +51 -0
  10. gate_cache-0.8.0/src/gate_cache/console.py +115 -0
  11. gate_cache-0.8.0/src/gate_cache/dashboard/__init__.py +1 -0
  12. gate_cache-0.8.0/src/gate_cache/dashboard/app.py +136 -0
  13. gate_cache-0.8.0/src/gate_cache/dashboard/server.py +484 -0
  14. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Arc.svelte-BJ8loEOb.js +1 -0
  15. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Bar-DQUfE5ZY.js +1 -0
  16. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Bar-DcuSsIRy.css +1 -0
  17. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/BrushContext.svelte-C-wFbghj.js +1 -0
  18. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/ChartAnnotations.svelte-B2_NW2WT.js +1 -0
  19. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/DefaultTooltip-C53ir0g7.css +1 -0
  20. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/DefaultTooltip-S6pJdSim.js +1 -0
  21. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Labels-OE4x1xdX.js +1 -0
  22. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Labels-sEaJtb97.css +1 -0
  23. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Legend-CwKDgmED.js +1 -0
  24. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Legend-DeowBKKb.css +1 -0
  25. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Path-MiPiAzgz.css +1 -0
  26. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Path.canvas-BJu5Zu14.js +1 -0
  27. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Path.svg-CMpSs27p.js +2 -0
  28. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Points-CaIpnL4S.js +1 -0
  29. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Points.html-6PBuO4Yr.js +1 -0
  30. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Spline-CheNKKUI.js +1 -0
  31. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/TransformContext.svelte-CJ1x6IlJ.js +1 -0
  32. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Voronoi.svelte-C4J_TVhL.js +1 -0
  33. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/d3-quadtree-DlddCuIi.js +1 -0
  34. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/d3-scale-DJX62D6g.js +1 -0
  35. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/index-3jI0ZFKA.js +18 -0
  36. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/index-BFVfitfh.css +1 -0
  37. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/index-client-y1DkY4QG.js +2 -0
  38. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/key.svelte-x8TjJ5F6.js +1 -0
  39. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/scales.svelte-D57BD9dU.js +1 -0
  40. gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/transition-C58PZtCD.js +4 -0
  41. gate_cache-0.8.0/src/gate_cache/dashboard/static/favicon.svg +1 -0
  42. gate_cache-0.8.0/src/gate_cache/dashboard/static/index.html +23 -0
  43. gate_cache-0.8.0/src/gate_cache/dashboard/static/theme.js +11 -0
  44. gate_cache-0.8.0/src/gate_cache/env.py +17 -0
  45. gate_cache-0.8.0/src/gate_cache/gate.py +1015 -0
  46. gate_cache-0.8.0/src/gate_cache/gate_lock.py +284 -0
  47. gate_cache-0.8.0/src/gate_cache/markers.py +453 -0
  48. {gate_cache-0.6.0 → gate_cache-0.8.0}/src/gate_cache/runner.py +58 -10
  49. gate_cache-0.8.0/src/gate_cache/snapshot.py +599 -0
  50. gate_cache-0.8.0/src/gate_cache/stats/__init__.py +1 -0
  51. gate_cache-0.8.0/src/gate_cache/stats/archive.py +424 -0
  52. gate_cache-0.8.0/src/gate_cache/stats/clear.py +58 -0
  53. gate_cache-0.8.0/src/gate_cache/stats/config.py +197 -0
  54. gate_cache-0.8.0/src/gate_cache/stats/context.py +521 -0
  55. gate_cache-0.8.0/src/gate_cache/stats/lock.py +74 -0
  56. gate_cache-0.8.0/src/gate_cache/stats/queries.py +1040 -0
  57. gate_cache-0.8.0/src/gate_cache/stats/recorder.py +255 -0
  58. gate_cache-0.8.0/src/gate_cache/wait_settings.py +110 -0
  59. gate_cache-0.6.0/PKG-INFO +0 -284
  60. gate_cache-0.6.0/README.md +0 -248
  61. gate_cache-0.6.0/src/gate_cache/cli.py +0 -247
  62. gate_cache-0.6.0/src/gate_cache/console.py +0 -43
  63. gate_cache-0.6.0/src/gate_cache/gate.py +0 -349
  64. gate_cache-0.6.0/src/gate_cache/markers.py +0 -297
  65. gate_cache-0.6.0/src/gate_cache/snapshot.py +0 -364
  66. {gate_cache-0.6.0 → gate_cache-0.8.0}/LICENSE +0 -0
  67. {gate_cache-0.6.0 → gate_cache-0.8.0}/src/gate_cache/git.py +0 -0
  68. {gate_cache-0.6.0 → gate_cache-0.8.0}/src/gate_cache/scratch.py +0 -0
@@ -0,0 +1,488 @@
1
+ Metadata-Version: 2.3
2
+ Name: gate-cache
3
+ Version: 0.8.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
+ Two flags print text for agents:
78
+
79
+ - `gate-cache --prompt` prints the setup task that the agent follows.
80
+ - `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:
81
+
82
+ ```sh
83
+ mkdir -p ~/.claude/skills/gate-cache
84
+ gate-cache --skill > ~/.claude/skills/gate-cache/SKILL.md
85
+ ```
86
+
87
+ 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.
88
+
89
+ ## Run a command through gate-cache
90
+
91
+ The command goes after `--`:
92
+
93
+ ```sh
94
+ gate-cache -- uv run pytest
95
+ gate-cache -- uv run ruff check .
96
+ ```
97
+
98
+ 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`.
99
+
100
+ To choose the name yourself, put `--name` before `--`:
101
+
102
+ ```sh
103
+ gate-cache --name pytest -- uv run pytest
104
+ ```
105
+
106
+ 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).
107
+
108
+ 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.
109
+
110
+ 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.
111
+
112
+ ## Run the same gate twice at once
113
+
114
+ 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:
115
+
116
+ ```console
117
+ $ gate-cache -- uv run pytest
118
+ gate-cache: uv run pytest is running in /work/app-feature (started 1m 12s ago), waiting
119
+ gate-cache: uv run pytest already passed on tree aaff74984ccc, skipping (saved 1m 34s)
120
+ ```
121
+
122
+ 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.
123
+
124
+ 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.
125
+
126
+ ## Scope a gate to its paths
127
+
128
+ 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:
129
+
130
+ ```sh
131
+ gate-cache --name api-test --path api/ --path uv.lock -- uv run pytest api/tests
132
+ ```
133
+
134
+ 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.
135
+
136
+ 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:
137
+
138
+ ```sh
139
+ gate-cache --name scripts-test --path scripts/ --path ':(exclude)scripts/fixtures/' -- uv run pytest scripts
140
+ ```
141
+
142
+ 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`.
143
+
144
+ > **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.
145
+
146
+ 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.
147
+
148
+ ## Run it as a hook
149
+
150
+ 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:
151
+
152
+ ```yaml
153
+ repos:
154
+ - repo: https://github.com/natelandau/gate-cache
155
+ rev: v0.8.0
156
+ hooks:
157
+ - id: gate-cache
158
+ name: pytest
159
+ args: [--, uv, run, pytest]
160
+ files: ^(src/|tests/)
161
+ - id: gate-cache
162
+ name: ruff
163
+ args: [--, uv, run, ruff, check, .]
164
+ ```
165
+
166
+ The hook runs at commit time and at push time. At commit time, gate-cache matches the content that you commit.
167
+
168
+ 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.
169
+
170
+ 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.
171
+
172
+ 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.
173
+
174
+ ## Examples
175
+
176
+ 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.
177
+
178
+ ### justfile
179
+
180
+ ```just
181
+ test:
182
+ gate-cache -- uv run pytest
183
+
184
+ lint:
185
+ gate-cache -- uv run ruff check .
186
+ ```
187
+
188
+ After `just test` passes, the next `just test` on the same content skips pytest.
189
+
190
+ ### Recipes with arguments
191
+
192
+ 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:
193
+
194
+ ```just
195
+ test *args:
196
+ gate-cache -- uv run pytest {{ args }}
197
+ ```
198
+
199
+ `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.
200
+
201
+ 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`.
202
+
203
+ 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.
204
+
205
+ ### Inputs that git does not track
206
+
207
+ 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. When the value changes, the name changes, so no marker matches and the command runs again:
208
+
209
+ ```just
210
+ # Run again when the uv version changes
211
+ test:
212
+ gate-cache --name "test-uv$(uv --version | cut -d' ' -f2)" -- uv run pytest
213
+
214
+ # Run again when the ignored .env file changes
215
+ integration:
216
+ gate-cache --name "integration-$(git hash-object .env)" -- uv run pytest tests/integration
217
+ ```
218
+
219
+ `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.
220
+
221
+ 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`.
222
+
223
+ ### Makefile
224
+
225
+ ```make
226
+ test:
227
+ gate-cache -- uv run pytest
228
+
229
+ lint:
230
+ gate-cache -- uv run ruff check .
231
+ ```
232
+
233
+ ### A hook that calls the recipe
234
+
235
+ A local hook can run the recipe instead of the gate-cache hook repository:
236
+
237
+ ```yaml
238
+ repos:
239
+ - repo: local
240
+ hooks:
241
+ - id: test
242
+ name: test
243
+ entry: just test
244
+ language: system
245
+ pass_filenames: false
246
+ stages: [pre-commit, pre-push]
247
+ ```
248
+
249
+ 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`.
250
+
251
+ ### CI
252
+
253
+ 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`.
254
+
255
+ When caching is off, gate-cache runs the command each time and writes no marker.
256
+
257
+ `GATE_CACHE_DISABLE` overrides `CI`. To keep caching on when `CI` is on, set `GATE_CACHE_DISABLE` to `0` or `false`:
258
+
259
+ ```sh
260
+ GATE_CACHE_DISABLE=0 just test
261
+ ```
262
+
263
+ To turn off caching when `CI` is not set, set `GATE_CACHE_DISABLE` to `1`:
264
+
265
+ ```sh
266
+ GATE_CACHE_DISABLE=1 just test
267
+ ```
268
+
269
+ ## See what already passed
270
+
271
+ `gate-cache status` lists the names that passed on the current content, and the names that ran on it without a pass:
272
+
273
+ ```console
274
+ $ gate-cache status
275
+ tree: aaff74984cccd156a469afa7d9ab10e4777beb24
276
+ passed: uv run pytest
277
+ missed: uv run ruff check . (exit code 1)
278
+ ```
279
+
280
+ 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.
281
+
282
+ 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:
283
+
284
+ ```console
285
+ $ gate-cache status -- uv run ruff check .
286
+ name: uv run ruff check .
287
+ tree: aaff74984cccd156a469afa7d9ab10e4777beb24
288
+ marker: /path/to/repo/.git/gate-cache/7d94ca2f57ec0a77f60d328fb405d339fb0c2a645991b97c042ac54403104e9e
289
+ result: miss
290
+ last run: exit code 1
291
+ ```
292
+
293
+ 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.
294
+
295
+ 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:
296
+
297
+ ```console
298
+ $ gate-cache status --name api-test --path api/ --path uv.lock
299
+ name: api-test
300
+ paths: api/ uv.lock
301
+ scope: paths:7c462ce94adead1b7ab99f8e4212ffac194c562e0d178151207c1f01e0073615
302
+ tree: aaff74984cccd156a469afa7d9ab10e4777beb24
303
+ marker: /path/to/repo/.git/gate-cache/4156a896efe2ed16204b6d2525acbfbd9c4dd808dbfc135571e4f631b7d7754a
304
+ result: hit
305
+ duration: 1m 34s
306
+ ```
307
+
308
+ Without `--name` or a command, `status` also lists the scoped gates that passed or missed on the current content of their paths.
309
+
310
+ `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.
311
+
312
+ With `--json`, `status` writes one JSON object to stdout instead of text. The exit codes do not change:
313
+
314
+ ```console
315
+ $ gate-cache status --json
316
+ {
317
+ "enabled": true,
318
+ "tree": "aaff74984cccd156a469afa7d9ab10e4777beb24",
319
+ "reason": null,
320
+ "passed": ["uv run pytest"],
321
+ "missed": [
322
+ {"name": "uv run ruff check .", "exit_code": 1, "reason": "exit code 1", "timestamp": "2026-10-12T12:31:55Z"}
323
+ ]
324
+ }
325
+ ```
326
+
327
+ `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.
328
+
329
+ ## Start fresh
330
+
331
+ 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.
332
+
333
+ `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:
334
+
335
+ ```console
336
+ $ gate-cache clear
337
+ gate-cache: WARNING: this permanently deletes every recorded pass for this repository.
338
+ gate-cache: markers: /path/to/repo/.git/gate-cache
339
+ gate-cache: Every gate runs again in full, even on code that already passed.
340
+ gate-cache: Recorded run stats are not affected.
341
+ gate-cache: This cannot be undone.
342
+ gate-cache: type 'yes' to clear markers: yes
343
+ gate-cache: removed 3 markers
344
+ ```
345
+
346
+ If standard input is not a terminal, as in a script, the command refuses with exit code 1 unless you give `--yes` (or `-y`):
347
+
348
+ ```sh
349
+ gate-cache clear --yes
350
+ ```
351
+
352
+ `GATE_CACHE_DISABLE=1` runs every command without the cache, for one command or for a whole session:
353
+
354
+ ```sh
355
+ GATE_CACHE_DISABLE=1 git push
356
+ ```
357
+
358
+ ## Stats dashboard
359
+
360
+ 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:
361
+
362
+ ```sh
363
+ gate-cache stats on
364
+ ```
365
+
366
+ `gate-cache stats` without an action shows whether recording is on, what decided it, and where the config file and the data live:
367
+
368
+ ```console
369
+ $ gate-cache stats
370
+ recording: on
371
+ decided by: config
372
+ config: /path/to/config/gate-cache/config.toml
373
+ data: /path/to/state/gate-cache
374
+ ```
375
+
376
+ 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.
377
+
378
+ To open the dashboard, run:
379
+
380
+ ```sh
381
+ gate-cache dashboard
382
+ ```
383
+
384
+ 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.
385
+
386
+ 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. 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.
387
+
388
+ `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`):
389
+
390
+ ```sh
391
+ gate-cache stats clear --yes
392
+ ```
393
+
394
+ It keeps the random machine ID. It refuses while the dashboard runs. It does not delete markers. Use `gate-cache clear` for those.
395
+
396
+ ### What gate-cache records
397
+
398
+ Each run of a gate adds one event with these fields:
399
+
400
+ - the time the run finished
401
+ - the path of the git directory of the repository
402
+ - the gate name and the `--path` values
403
+ - the tree key that the run used
404
+ - the outcome
405
+ - the run time of the command, and the time that a skip saved
406
+ - the exit code of the command
407
+ - the reason that caching was off, for a run without the cache
408
+ - the gate-cache version, the platform, and what started the run: CI, a git hook, a coding agent, or a terminal
409
+ - the path of the working tree, the directory in it where the gate ran, the branch, and the commit
410
+ - the URL of the `origin` remote, without user names or credentials
411
+ - the host name of the machine and a random machine ID
412
+ - 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
413
+ - the full command line, when `--name` gives a name that is not the command line
414
+ - 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
415
+
416
+ 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.
417
+
418
+ ### When recording is on
419
+
420
+ The setting comes from the first of these that applies:
421
+
422
+ 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.
423
+ 2. `CI`. When `CI` is on, recording is off.
424
+ 3. `[stats] enabled` in the config file.
425
+ 4. Off.
426
+
427
+ 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.
428
+
429
+ ### Where the data lives
430
+
431
+ The data directory comes from the first of these that applies:
432
+
433
+ 1. `GATE_CACHE_DATA_DIR`, when it is not empty. A relative path starts from the current directory.
434
+ 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.
435
+ 3. The state directory of your platform.
436
+
437
+ 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.
438
+
439
+ ```toml
440
+ [stats]
441
+ enabled = true
442
+ data_dir = "~/gate-cache-stats"
443
+ ```
444
+
445
+ To try the dashboard on test data and keep your real stats unchanged, set a separate data directory:
446
+
447
+ ```sh
448
+ GATE_CACHE_DATA_DIR=/tmp/gc-uat GATE_CACHE_STATS=1 gate-cache dashboard
449
+ ```
450
+
451
+ ## Settings
452
+
453
+ Five environment variables control gate-cache.
454
+
455
+ | Variable | Effect | Default |
456
+ | ------------------------- | ------------------------------------------------------------------------------ | ------- |
457
+ | `GATE_CACHE_DISABLE` | If on, turns off caching. If `0` or `false`, keeps caching on when `CI` is on. | not set |
458
+ | `CI` | If on, turns off caching. A value in `GATE_CACHE_DISABLE` overrides it. | not set |
459
+ | `GATE_CACHE_MAX_AGE_DAYS` | Each time gate-cache records a result, it deletes markers older than this number of days. | `30` |
460
+ | `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 |
461
+ | `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 |
462
+
463
+ A variable is on when its value is not empty, `0`, or `false`. Case and spaces around the value do not matter.
464
+
465
+ ### Waiting for a concurrent run
466
+
467
+ 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.
468
+
469
+ | Config key | Flag | Effect | Default |
470
+ | ---------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
471
+ | `timeout` | `--wait-timeout SECONDS` | The longest total wait of one run, in whole seconds. `0` turns waiting off. | `900` |
472
+ | `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` |
473
+
474
+ ```toml
475
+ [wait]
476
+ timeout = 300
477
+ failed = "report"
478
+ ```
479
+
480
+ 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.
481
+
482
+ 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.
483
+
484
+ ## Learn more
485
+
486
+ - [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.
487
+ - `gate-cache --help` gives the full command reference.
488
+ - `gate-cache --skill` gives the guide for coding agents.