gate-cache 0.7.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.
- {gate_cache-0.7.0 → gate_cache-0.8.0}/PKG-INFO +178 -13
- gate_cache-0.8.0/README.md +452 -0
- {gate_cache-0.7.0 → gate_cache-0.8.0}/pyproject.toml +6 -2
- {gate_cache-0.7.0 → gate_cache-0.8.0}/pyproject.toml.orig +3 -2
- {gate_cache-0.7.0 → gate_cache-0.8.0}/src/gate_cache/__init__.py +1 -1
- gate_cache-0.8.0/src/gate_cache/agent/prompt.md +11 -0
- gate_cache-0.8.0/src/gate_cache/agent/skill.md +177 -0
- gate_cache-0.8.0/src/gate_cache/cli.py +636 -0
- gate_cache-0.8.0/src/gate_cache/config.py +51 -0
- gate_cache-0.8.0/src/gate_cache/console.py +115 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/__init__.py +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/app.py +136 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/server.py +484 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Arc.svelte-BJ8loEOb.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Bar-DQUfE5ZY.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Bar-DcuSsIRy.css +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/BrushContext.svelte-C-wFbghj.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/ChartAnnotations.svelte-B2_NW2WT.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/DefaultTooltip-C53ir0g7.css +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/DefaultTooltip-S6pJdSim.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Labels-OE4x1xdX.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Labels-sEaJtb97.css +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Legend-CwKDgmED.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Legend-DeowBKKb.css +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Path-MiPiAzgz.css +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Path.canvas-BJu5Zu14.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Path.svg-CMpSs27p.js +2 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Points-CaIpnL4S.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Points.html-6PBuO4Yr.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Spline-CheNKKUI.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/TransformContext.svelte-CJ1x6IlJ.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/Voronoi.svelte-C4J_TVhL.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/d3-quadtree-DlddCuIi.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/d3-scale-DJX62D6g.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/index-3jI0ZFKA.js +18 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/index-BFVfitfh.css +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/index-client-y1DkY4QG.js +2 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/key.svelte-x8TjJ5F6.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/scales.svelte-D57BD9dU.js +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/assets/transition-C58PZtCD.js +4 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/favicon.svg +1 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/index.html +23 -0
- gate_cache-0.8.0/src/gate_cache/dashboard/static/theme.js +11 -0
- gate_cache-0.8.0/src/gate_cache/env.py +17 -0
- gate_cache-0.8.0/src/gate_cache/gate.py +1015 -0
- gate_cache-0.8.0/src/gate_cache/gate_lock.py +284 -0
- {gate_cache-0.7.0 → gate_cache-0.8.0}/src/gate_cache/markers.py +16 -8
- {gate_cache-0.7.0 → gate_cache-0.8.0}/src/gate_cache/runner.py +51 -9
- {gate_cache-0.7.0 → gate_cache-0.8.0}/src/gate_cache/snapshot.py +188 -56
- gate_cache-0.8.0/src/gate_cache/stats/__init__.py +1 -0
- gate_cache-0.8.0/src/gate_cache/stats/archive.py +424 -0
- gate_cache-0.8.0/src/gate_cache/stats/clear.py +58 -0
- gate_cache-0.8.0/src/gate_cache/stats/config.py +197 -0
- gate_cache-0.8.0/src/gate_cache/stats/context.py +521 -0
- gate_cache-0.8.0/src/gate_cache/stats/lock.py +74 -0
- gate_cache-0.8.0/src/gate_cache/stats/queries.py +1040 -0
- gate_cache-0.8.0/src/gate_cache/stats/recorder.py +255 -0
- gate_cache-0.8.0/src/gate_cache/wait_settings.py +110 -0
- 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.8.0}/LICENSE +0 -0
- {gate_cache-0.7.0 → gate_cache-0.8.0}/src/gate_cache/git.py +0 -0
- {gate_cache-0.7.0 → gate_cache-0.8.0}/src/gate_cache/scratch.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.3
|
|
2
2
|
Name: gate-cache
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.8.0
|
|
4
4
|
Summary: Skip lint and test gates that already passed on the exact same git tree.
|
|
5
5
|
Author: Nate Landau
|
|
6
6
|
Author-email: Nate Landau <github@natenate.org>
|
|
@@ -62,7 +62,29 @@ gate-cache requires Python 3.11 or later, on macOS or Linux.
|
|
|
62
62
|
uv tool install gate-cache
|
|
63
63
|
```
|
|
64
64
|
|
|
65
|
-
The prek and pre-commit hooks install gate-cache themselves, so the hooks work without this step.
|
|
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.
|
|
66
88
|
|
|
67
89
|
## Run a command through gate-cache
|
|
68
90
|
|
|
@@ -87,6 +109,20 @@ gate-cache exits with the exit code of the command, or with 0 when it skips the
|
|
|
87
109
|
|
|
88
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.
|
|
89
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
|
+
|
|
90
126
|
## Scope a gate to its paths
|
|
91
127
|
|
|
92
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:
|
|
@@ -116,7 +152,7 @@ gate-cache works with [prek](https://github.com/j178/prek) and with [pre-commit]
|
|
|
116
152
|
```yaml
|
|
117
153
|
repos:
|
|
118
154
|
- repo: https://github.com/natelandau/gate-cache
|
|
119
|
-
rev: v0.
|
|
155
|
+
rev: v0.8.0
|
|
120
156
|
hooks:
|
|
121
157
|
- id: gate-cache
|
|
122
158
|
name: pytest
|
|
@@ -131,6 +167,8 @@ The hook runs at commit time and at push time. At commit time, gate-cache matche
|
|
|
131
167
|
|
|
132
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.
|
|
133
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
|
+
|
|
134
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.
|
|
135
173
|
|
|
136
174
|
## Examples
|
|
@@ -162,6 +200,8 @@ test *args:
|
|
|
162
200
|
|
|
163
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`.
|
|
164
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
|
+
|
|
165
205
|
### Inputs that git does not track
|
|
166
206
|
|
|
167
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:
|
|
@@ -239,10 +279,10 @@ $ gate-cache status
|
|
|
239
279
|
|
|
240
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.
|
|
241
281
|
|
|
242
|
-
With `--name`, it reports on one name. For a gate that ran without `--name`, give the command line as the name:
|
|
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:
|
|
243
283
|
|
|
244
284
|
```console
|
|
245
|
-
$ gate-cache status --
|
|
285
|
+
$ gate-cache status -- uv run ruff check .
|
|
246
286
|
name: uv run ruff check .
|
|
247
287
|
tree: aaff74984cccd156a469afa7d9ab10e4777beb24
|
|
248
288
|
marker: /path/to/repo/.git/gate-cache/7d94ca2f57ec0a77f60d328fb405d339fb0c2a645991b97c042ac54403104e9e
|
|
@@ -252,7 +292,7 @@ $ gate-cache status --name "uv run ruff check ."
|
|
|
252
292
|
|
|
253
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.
|
|
254
294
|
|
|
255
|
-
For a scoped gate, give the same `--path` options with `--name
|
|
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:
|
|
256
296
|
|
|
257
297
|
```console
|
|
258
298
|
$ gate-cache status --name api-test --path api/ --path uv.lock
|
|
@@ -265,9 +305,9 @@ $ gate-cache status --name api-test --path api/ --path uv.lock
|
|
|
265
305
|
duration: 1m 34s
|
|
266
306
|
```
|
|
267
307
|
|
|
268
|
-
Without `--name
|
|
308
|
+
Without `--name` or a command, `status` also lists the scoped gates that passed or missed on the current content of their paths.
|
|
269
309
|
|
|
270
|
-
`status` runs nothing. With `--name
|
|
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.
|
|
271
311
|
|
|
272
312
|
With `--json`, `status` writes one JSON object to stdout instead of text. The exit codes do not change:
|
|
273
313
|
|
|
@@ -290,34 +330,159 @@ $ gate-cache status --json
|
|
|
290
330
|
|
|
291
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.
|
|
292
332
|
|
|
293
|
-
`gate-cache clear` deletes every marker for the repository, and the records of missed runs:
|
|
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:
|
|
294
334
|
|
|
295
335
|
```console
|
|
296
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
|
|
297
343
|
gate-cache: removed 3 markers
|
|
298
344
|
```
|
|
299
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
|
+
|
|
300
352
|
`GATE_CACHE_DISABLE=1` runs every command without the cache, for one command or for a whole session:
|
|
301
353
|
|
|
302
354
|
```sh
|
|
303
355
|
GATE_CACHE_DISABLE=1 git push
|
|
304
356
|
```
|
|
305
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
|
+
|
|
306
451
|
## Settings
|
|
307
452
|
|
|
308
|
-
|
|
453
|
+
Five environment variables control gate-cache.
|
|
309
454
|
|
|
310
455
|
| Variable | Effect | Default |
|
|
311
456
|
| ------------------------- | ------------------------------------------------------------------------------ | ------- |
|
|
312
457
|
| `GATE_CACHE_DISABLE` | If on, turns off caching. If `0` or `false`, keeps caching on when `CI` is on. | not set |
|
|
313
458
|
| `CI` | If on, turns off caching. A value in `GATE_CACHE_DISABLE` overrides it. | not set |
|
|
314
|
-
| `GATE_CACHE_MAX_AGE_DAYS` | gate-cache deletes markers older than this number of days.
|
|
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 |
|
|
315
462
|
|
|
316
463
|
A variable is on when its value is not empty, `0`, or `false`. Case and spaces around the value do not matter.
|
|
317
464
|
|
|
318
|
-
|
|
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.
|
|
319
483
|
|
|
320
484
|
## Learn more
|
|
321
485
|
|
|
322
|
-
- [How gate-cache works](docs/how-it-works.md) describes the exact rules for a skip, what a marker covers,
|
|
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.
|
|
323
487
|
- `gate-cache --help` gives the full command reference.
|
|
488
|
+
- `gate-cache --skill` gives the guide for coding agents.
|