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.
- gate_cache-0.9.0/PKG-INFO +503 -0
- gate_cache-0.9.0/README.md +467 -0
- {gate_cache-0.7.0 → gate_cache-0.9.0}/pyproject.toml +6 -2
- {gate_cache-0.7.0 → gate_cache-0.9.0}/pyproject.toml.orig +3 -2
- {gate_cache-0.7.0 → gate_cache-0.9.0}/src/gate_cache/__init__.py +1 -1
- gate_cache-0.9.0/src/gate_cache/agent/prompt.md +24 -0
- gate_cache-0.9.0/src/gate_cache/agent/skill.md +181 -0
- gate_cache-0.9.0/src/gate_cache/cli.py +637 -0
- gate_cache-0.9.0/src/gate_cache/config.py +51 -0
- gate_cache-0.9.0/src/gate_cache/console.py +115 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/__init__.py +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/app.py +136 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/server.py +533 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Arc.svelte-CNpcs8X3.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Bar-0aBK7UpN.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Bar-DcuSsIRy.css +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/BrushContext.svelte-CCZcZhce.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/ChartAnnotations.svelte-rQYciYRB.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/DefaultTooltip-B5CAhh2Q.css +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/DefaultTooltip-CY_C86gN.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Labels-DR5FYZws.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Labels-sEaJtb97.css +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Legend-DeowBKKb.css +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Legend-d30gUpuK.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Path-MiPiAzgz.css +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Path.canvas-DOOOEuJg.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Path.svg-BEFmR18I.js +2 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Points-Boe_SZ9_.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Points.html-DjDCSC2I.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Spline-1ZDp-X2F.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/TransformContext.svelte-BICq8-YE.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/Voronoi.svelte-UEy6r0as.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/d3-quadtree-DlddCuIi.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/d3-scale-BZIMHxO8.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/index-Bp9x91ei.css +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/index-CYgojWsw.js +21 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/index-client-B3yOqiGu.js +2 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/key.svelte-B7SM1zzp.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/scales.svelte-CzvR6oHT.js +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/assets/transition-7dBkedGA.js +6 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/favicon.svg +1 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/index.html +23 -0
- gate_cache-0.9.0/src/gate_cache/dashboard/static/theme.js +11 -0
- gate_cache-0.9.0/src/gate_cache/env.py +17 -0
- gate_cache-0.9.0/src/gate_cache/gate.py +1015 -0
- gate_cache-0.9.0/src/gate_cache/gate_lock.py +284 -0
- {gate_cache-0.7.0 → gate_cache-0.9.0}/src/gate_cache/markers.py +16 -8
- {gate_cache-0.7.0 → gate_cache-0.9.0}/src/gate_cache/runner.py +51 -9
- {gate_cache-0.7.0 → gate_cache-0.9.0}/src/gate_cache/snapshot.py +188 -56
- gate_cache-0.9.0/src/gate_cache/stats/__init__.py +1 -0
- gate_cache-0.9.0/src/gate_cache/stats/archive.py +442 -0
- gate_cache-0.9.0/src/gate_cache/stats/clear.py +58 -0
- gate_cache-0.9.0/src/gate_cache/stats/config.py +197 -0
- gate_cache-0.9.0/src/gate_cache/stats/context.py +521 -0
- gate_cache-0.9.0/src/gate_cache/stats/lock.py +74 -0
- gate_cache-0.9.0/src/gate_cache/stats/queries.py +1309 -0
- gate_cache-0.9.0/src/gate_cache/stats/recorder.py +255 -0
- gate_cache-0.9.0/src/gate_cache/wait_settings.py +110 -0
- gate_cache-0.7.0/PKG-INFO +0 -323
- gate_cache-0.7.0/README.md +0 -287
- gate_cache-0.7.0/src/gate_cache/cli.py +0 -308
- gate_cache-0.7.0/src/gate_cache/console.py +0 -66
- gate_cache-0.7.0/src/gate_cache/gate.py +0 -427
- {gate_cache-0.7.0 → gate_cache-0.9.0}/LICENSE +0 -0
- {gate_cache-0.7.0 → gate_cache-0.9.0}/src/gate_cache/git.py +0 -0
- {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.
|