gate-cache 0.3.0__tar.gz → 0.5.0__tar.gz

{gate_cache-0.3.0 → gate_cache-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: gate-cache
-Version: 0.3.0
+Version: 0.5.0
 Summary: Skip lint and test gates that already passed on the exact same git tree.
 Author: Nate Landau
 Author-email: Nate Landau <github@natenate.org>
@@ -31,6 +31,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: cyclopts>=5.2.0,<6.0.0
 Requires-Dist: nclutils>=3.4.4,<4.0.0
+Requires-Dist: platformdirs>=4.13.0,<5.0.0
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 
@@ -40,17 +41,17 @@ Skip a command that already passed on the same code.
 
 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.
 
-gate-cache remembers which commands passed on which code. It wraps a command and gives it a name. When the command passes, gate-cache writes a marker for that name and for the exact content of the tracked files. The next time the same name runs on the same content, gate-cache finds the marker, skips the command, and exits 0 at once.
+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.
 
 ```console
-$ gate-cache --name pytest -- uv run pytest
+$ gate-cache -- uv run pytest
 ============================= 412 passed in 94.20s =============================
 
-$ gate-cache --name pytest -- uv run pytest
-gate-cache: pytest already passed on tree aaff74984ccc, skipping
+$ gate-cache -- uv run pytest
+gate-cache: uv run pytest already passed on tree aaff74984ccc, skipping
 ```
 
-A change to a tracked file changes the content, so no marker matches and the command runs again. A CI runner that starts from a fresh clone has no markers, so it runs every command.
+A change to any file that git does not ignore changes the content, so no marker matches and the command runs again. A CI runner that starts from a fresh clone has no markers, so it runs every command.
 
 ## Install
 
@@ -64,18 +65,26 @@ The prek and pre-commit hooks install gate-cache themselves, so the hooks work w
 
 ## Run a command through gate-cache
 
-The name goes after `--name`, and the command goes after `--`:
+The command goes after `--`:
+
+```sh
+gate-cache -- uv run pytest
+gate-cache -- uv run ruff check .
+```
+
+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`.
+
+To choose the name yourself, put `--name` before `--`:
 
 ```sh
 gate-cache --name pytest -- uv run pytest
-gate-cache --name ruff -- uv run ruff check .
 ```
 
-Each name has its own markers. A command run under one name never skips because of a marker for another name.
+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).
 
 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.
 
-When the working copy has uncommitted edits or files that git does not track, the content on disk is not a commit-ready snapshot. gate-cache then runs the command and writes no marker.
+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.
 
 ## Run it as a hook
 
@@ -88,18 +97,18 @@ repos:
     hooks:
       - id: gate-cache
         name: pytest
-        args: [--name, pytest, --, uv, run, pytest]
+        args: [--, uv, run, pytest]
         files: ^(src/|tests/)
       - id: gate-cache
         name: ruff
-        args: [--name, ruff, --, uv, run, ruff, check, .]
+        args: [--, uv, run, ruff, check, .]
 ```
 
 The hook runs at commit time and at push time. At commit time, gate-cache matches the content that you commit.
 
 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.
 
-Hooks, agents, and your terminal all read and write the same markers. When one of them runs `gate-cache --name pytest -- uv run pytest` and it passes, the others skip that name on the same content.
+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.
 
 ## Examples
 
@@ -109,38 +118,53 @@ These examples show gate-cache inside the task runner of a project. When a recip
 
 ```just
 test:
-    gate-cache --name test -- uv run pytest
+    gate-cache -- uv run pytest
 
 lint:
-    gate-cache --name lint -- uv run ruff check .
+    gate-cache -- uv run ruff check .
 ```
 
 After `just test` passes, the next `just test` on the same content skips pytest.
 
 ### Recipes with arguments
 
-gate-cache identifies a command by its name alone, not by its arguments. If `just test -k unit` and `just test` ran under the same name, a pass of the unit tests would also skip the full suite. Giving each set of arguments its own name, or caching only the bare form, keeps the two apart.
-
-This recipe caches `just test` and runs `just test -k unit` without the cache:
+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:
 
 ```just
 test *args:
-    #!/usr/bin/env bash
-    set -euo pipefail
-    if [[ -z "{{ args }}" ]]; then
-        exec gate-cache --name test -- uv run pytest
-    fi
-    exec uv run pytest {{ args }}
+    gate-cache -- uv run pytest {{ args }}
 ```
 
+`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.
+
+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`.
+
+### Inputs that git does not track
+
+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:
+
+```just
+# Run again when the uv version changes
+test:
+    gate-cache --name "test-uv$(uv --version | cut -d' ' -f2)" -- uv run pytest
+
+# Run again when the ignored .env file changes
+integration:
+    gate-cache --name "integration-$(git hash-object .env)" -- uv run pytest tests/integration
+```
+
+`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.
+
+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`.
+
 ### Makefile
 
 ```make
 test:
-	gate-cache --name test -- uv run pytest
+	gate-cache -- uv run pytest
 
 lint:
-	gate-cache --name lint -- uv run ruff check .
+	gate-cache -- uv run ruff check .
 ```
 
 ### A hook that calls the recipe
@@ -186,17 +210,17 @@ GATE_CACHE_DISABLE=1 just test
 ```console
 $ gate-cache status
   tree:   aaff74984cccd156a469afa7d9ab10e4777beb24
-  passed: pytest
-  missed: ruff (exit code 1)
+  passed: uv run pytest
+  missed: uv run ruff check . (exit code 1)
 ```
 
 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.
 
-With `--name`, it reports on one name:
+With `--name`, it reports on one name. For a gate that ran without `--name`, give the command line as the name:
 
 ```console
-$ gate-cache status --name ruff
-  name:     ruff
+$ gate-cache status --name "uv run ruff check ."
+  name:     uv run ruff check .
   tree:     aaff74984cccd156a469afa7d9ab10e4777beb24
   marker:   /path/to/repo/.git/gate-cache/7d94ca2f57ec0a77f60d328fb405d339fb0c2a645991b97c042ac54403104e9e
   result:   miss
@@ -205,7 +229,7 @@ $ gate-cache status --name ruff
 
 The `last run` line shows only when the name ran on this content without a pass.
 
-`status` runs nothing. With `--name`, it exits 0 when a marker matches and 1 when none does. Without `--name`, it exits 0 when at least one name passed. When gate-cache cannot match the content, for example because of uncommitted edits, the `tree` line gives the reason.
+`status` runs nothing. With `--name`, it exits 0 when a marker matches and 1 when none does. Without `--name`, it exits 0 when at least one name passed. When gate-cache cannot match the content, for example during a merge conflict, the `tree` line gives the reason.
 
 With `--json`, `status` writes one JSON object to stdout instead of text. The exit codes do not change:
 
@@ -215,18 +239,18 @@ $ gate-cache status --json
   "enabled": true,
   "tree": "aaff74984cccd156a469afa7d9ab10e4777beb24",
   "reason": null,
-  "passed": ["pytest"],
+  "passed": ["uv run pytest"],
   "missed": [
-    {"name": "ruff", "exit_code": 1, "reason": "exit code 1", "timestamp": "2026-10-12T12:31:55Z"}
+    {"name": "uv run ruff check .", "exit_code": 1, "reason": "exit code 1", "timestamp": "2026-10-12T12:31:55Z"}
   ]
 }
 ```
 
-`reason` tells why gate-cache cannot match the content, and is `null` when it can. When caching is off, `enabled` is `false` and `reason` names the variable. With `--name`, the object has the `name`, `marker`, `result`, and `last_run` keys in place of `passed` and `missed`.
+`reason` tells why gate-cache cannot match the content, and is `null` when it can. When caching is off, `enabled` is `false`, `reason` names the variable, and the other keys are empty or `null`. With `--name`, the object has the `name`, `marker`, `result`, and `last_run` keys in place of `passed` and `missed`.
 
 ## Start fresh
 
-A marker records only the content of the tracked files. 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.
+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.
 
 `gate-cache clear` deletes every marker for the repository, and the records of missed runs:
 

{gate_cache-0.3.0 → gate_cache-0.5.0}/README.md

@@ -4,17 +4,17 @@ Skip a command that already passed on the same code.
 
 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.
 
-gate-cache remembers which commands passed on which code. It wraps a command and gives it a name. When the command passes, gate-cache writes a marker for that name and for the exact content of the tracked files. The next time the same name runs on the same content, gate-cache finds the marker, skips the command, and exits 0 at once.
+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.
 
 ```console
-$ gate-cache --name pytest -- uv run pytest
+$ gate-cache -- uv run pytest
 ============================= 412 passed in 94.20s =============================
 
-$ gate-cache --name pytest -- uv run pytest
-gate-cache: pytest already passed on tree aaff74984ccc, skipping
+$ gate-cache -- uv run pytest
+gate-cache: uv run pytest already passed on tree aaff74984ccc, skipping
 ```
 
-A change to a tracked file changes the content, so no marker matches and the command runs again. A CI runner that starts from a fresh clone has no markers, so it runs every command.
+A change to any file that git does not ignore changes the content, so no marker matches and the command runs again. A CI runner that starts from a fresh clone has no markers, so it runs every command.
 
 ## Install
 
@@ -28,18 +28,26 @@ The prek and pre-commit hooks install gate-cache themselves, so the hooks work w
 
 ## Run a command through gate-cache
 
-The name goes after `--name`, and the command goes after `--`:
+The command goes after `--`:
+
+```sh
+gate-cache -- uv run pytest
+gate-cache -- uv run ruff check .
+```
+
+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`.
+
+To choose the name yourself, put `--name` before `--`:
 
 ```sh
 gate-cache --name pytest -- uv run pytest
-gate-cache --name ruff -- uv run ruff check .
 ```
 
-Each name has its own markers. A command run under one name never skips because of a marker for another name.
+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).
 
 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.
 
-When the working copy has uncommitted edits or files that git does not track, the content on disk is not a commit-ready snapshot. gate-cache then runs the command and writes no marker.
+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.
 
 ## Run it as a hook
 
@@ -52,18 +60,18 @@ repos:
     hooks:
       - id: gate-cache
         name: pytest
-        args: [--name, pytest, --, uv, run, pytest]
+        args: [--, uv, run, pytest]
         files: ^(src/|tests/)
       - id: gate-cache
         name: ruff
-        args: [--name, ruff, --, uv, run, ruff, check, .]
+        args: [--, uv, run, ruff, check, .]
 ```
 
 The hook runs at commit time and at push time. At commit time, gate-cache matches the content that you commit.
 
 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.
 
-Hooks, agents, and your terminal all read and write the same markers. When one of them runs `gate-cache --name pytest -- uv run pytest` and it passes, the others skip that name on the same content.
+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.
 
 ## Examples
 
@@ -73,38 +81,53 @@ These examples show gate-cache inside the task runner of a project. When a recip
 
 ```just
 test:
-    gate-cache --name test -- uv run pytest
+    gate-cache -- uv run pytest
 
 lint:
-    gate-cache --name lint -- uv run ruff check .
+    gate-cache -- uv run ruff check .
 ```
 
 After `just test` passes, the next `just test` on the same content skips pytest.
 
 ### Recipes with arguments
 
-gate-cache identifies a command by its name alone, not by its arguments. If `just test -k unit` and `just test` ran under the same name, a pass of the unit tests would also skip the full suite. Giving each set of arguments its own name, or caching only the bare form, keeps the two apart.
-
-This recipe caches `just test` and runs `just test -k unit` without the cache:
+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:
 
 ```just
 test *args:
-    #!/usr/bin/env bash
-    set -euo pipefail
-    if [[ -z "{{ args }}" ]]; then
-        exec gate-cache --name test -- uv run pytest
-    fi
-    exec uv run pytest {{ args }}
+    gate-cache -- uv run pytest {{ args }}
 ```
 
+`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.
+
+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`.
+
+### Inputs that git does not track
+
+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:
+
+```just
+# Run again when the uv version changes
+test:
+    gate-cache --name "test-uv$(uv --version | cut -d' ' -f2)" -- uv run pytest
+
+# Run again when the ignored .env file changes
+integration:
+    gate-cache --name "integration-$(git hash-object .env)" -- uv run pytest tests/integration
+```
+
+`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.
+
+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`.
+
 ### Makefile
 
 ```make
 test:
-	gate-cache --name test -- uv run pytest
+	gate-cache -- uv run pytest
 
 lint:
-	gate-cache --name lint -- uv run ruff check .
+	gate-cache -- uv run ruff check .
 ```
 
 ### A hook that calls the recipe
@@ -150,17 +173,17 @@ GATE_CACHE_DISABLE=1 just test
 ```console
 $ gate-cache status
   tree:   aaff74984cccd156a469afa7d9ab10e4777beb24
-  passed: pytest
-  missed: ruff (exit code 1)
+  passed: uv run pytest
+  missed: uv run ruff check . (exit code 1)
 ```
 
 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.
 
-With `--name`, it reports on one name:
+With `--name`, it reports on one name. For a gate that ran without `--name`, give the command line as the name:
 
 ```console
-$ gate-cache status --name ruff
-  name:     ruff
+$ gate-cache status --name "uv run ruff check ."
+  name:     uv run ruff check .
   tree:     aaff74984cccd156a469afa7d9ab10e4777beb24
   marker:   /path/to/repo/.git/gate-cache/7d94ca2f57ec0a77f60d328fb405d339fb0c2a645991b97c042ac54403104e9e
   result:   miss
@@ -169,7 +192,7 @@ $ gate-cache status --name ruff
 
 The `last run` line shows only when the name ran on this content without a pass.
 
-`status` runs nothing. With `--name`, it exits 0 when a marker matches and 1 when none does. Without `--name`, it exits 0 when at least one name passed. When gate-cache cannot match the content, for example because of uncommitted edits, the `tree` line gives the reason.
+`status` runs nothing. With `--name`, it exits 0 when a marker matches and 1 when none does. Without `--name`, it exits 0 when at least one name passed. When gate-cache cannot match the content, for example during a merge conflict, the `tree` line gives the reason.
 
 With `--json`, `status` writes one JSON object to stdout instead of text. The exit codes do not change:
 
@@ -179,18 +202,18 @@ $ gate-cache status --json
   "enabled": true,
   "tree": "aaff74984cccd156a469afa7d9ab10e4777beb24",
   "reason": null,
-  "passed": ["pytest"],
+  "passed": ["uv run pytest"],
   "missed": [
-    {"name": "ruff", "exit_code": 1, "reason": "exit code 1", "timestamp": "2026-10-12T12:31:55Z"}
+    {"name": "uv run ruff check .", "exit_code": 1, "reason": "exit code 1", "timestamp": "2026-10-12T12:31:55Z"}
   ]
 }
 ```
 
-`reason` tells why gate-cache cannot match the content, and is `null` when it can. When caching is off, `enabled` is `false` and `reason` names the variable. With `--name`, the object has the `name`, `marker`, `result`, and `last_run` keys in place of `passed` and `missed`.
+`reason` tells why gate-cache cannot match the content, and is `null` when it can. When caching is off, `enabled` is `false`, `reason` names the variable, and the other keys are empty or `null`. With `--name`, the object has the `name`, `marker`, `result`, and `last_run` keys in place of `passed` and `missed`.
 
 ## Start fresh
 
-A marker records only the content of the tracked files. 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.
+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.
 
 `gate-cache clear` deletes every marker for the repository, and the records of missed runs:
 

{gate_cache-0.3.0 → gate_cache-0.5.0}/pyproject.toml

@@ -8,12 +8,13 @@ classifiers = [
 dependencies = [
     "cyclopts>=5.2.0,<6.0.0",
     "nclutils>=3.4.4,<4.0.0",
+    "platformdirs>=4.13.0,<5.0.0",
 ]
 description = "Skip lint and test gates that already passed on the exact same git tree."
 name = "gate-cache"
 readme = "README.md"
 requires-python = ">=3.11"
-version = "0.3.0"
+version = "0.5.0"
 
 [[project.authors]]
 name = "Nate Landau"

{gate_cache-0.3.0 → gate_cache-0.5.0}/pyproject.toml.orig

@@ -6,13 +6,17 @@
         "Programming Language :: Python :: 3.13",
         "Programming Language :: Python :: 3.14",
     ]
-    dependencies = ["cyclopts>=5.2.0,<6.0.0", "nclutils>=3.4.4,<4.0.0"]
+    dependencies = [
+        "cyclopts>=5.2.0,<6.0.0",
+        "nclutils>=3.4.4,<4.0.0",
+        "platformdirs>=4.13.0,<5.0.0",
+    ]
     description = "Skip lint and test gates that already passed on the exact same git tree."
     license = { file = "LICENSE" }
     name = "gate-cache"
     readme = "README.md"
     requires-python = ">=3.11"
-    version = "0.3.0"
+    version = "0.5.0"
 
     [project.scripts]
         gate-cache = "gate_cache.cli:main"

{gate_cache-0.3.0 → gate_cache-0.5.0}/src/gate_cache/__init__.py

@@ -1,3 +1,3 @@
 """Skip lint and test gates that already passed on the exact same git tree."""
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"

{gate_cache-0.3.0 → gate_cache-0.5.0}/src/gate_cache/cli.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import shlex
 import sys
 from typing import Annotated
 
@@ -17,14 +18,17 @@ _SUBCOMMANDS = {"status", "clear"}
 _INFO_FLAGS = {"-h", "--help", "--version"}
 
 _HELP = """\
-Skip a lint or test command that already passed on the same git tree. gate-cache runs
-the command, records a pass keyed on the git tree of the tracked files (the index, when
-the working copy matches it), and skips the command next time the tree is identical.
-With unstaged changes or untracked files the command runs without caching and nothing
-is recorded.
-
-Both --name and -- are required, and only --name may come before --. Everything after
--- is the command, verbatim.
+Skip a lint or test command that already passed on the same git tree. gate-cache
+runs the command, records a pass keyed on the git tree of the working copy
+(tracked and untracked, non-ignored files), and skips the command next time the
+tree is identical. A pass on uncommitted work therefore skips when the same
+content is committed.
+
+-- is required, and only --name may come before it. Everything after -- is the
+command, verbatim. Without --name, the gate name is the command itself, so each
+set of arguments has its own records. Give --name to share records between
+commands that check the same thing, or to key on inputs that the tree does not
+cover.
 
 Exit codes:
   run     the command's own exit code, or 0 when a recorded pass lets it skip.
@@ -40,11 +44,19 @@ same way.
 Set GATE_CACHE_MAX_AGE_DAYS to a positive whole number to change how many days a
 recorded pass lasts (default 30).
 
-Only file content is keyed. Never wrap checks that depend on anything else,
-such as commit-message or branch-name checks.
+Only the name and the file content are keyed. The working directory is not, so
+a command whose meaning depends on it needs a distinct --name. To also key on an
+ignored file, an environment variable, or a tool version, put its value in
+--name. A changed value gives a new name, so the command runs again. Never put a
+secret in a name, because markers and status store it as plain text. Without
+--name the command line is the name, so give --name to a command that takes a
+secret argument. Never wrap checks that depend on the commit message or the
+branch name.
 
 Typical use:
+  gate-cache -- uv run pytest -x
   gate-cache --name pytest -- uv run pytest -x
+  gate-cache --name "test-$(git hash-object .env)" -- uv run pytest
 """
 
 app = App(
@@ -53,7 +65,7 @@ app = App(
     help=_HELP,
     help_format="plaintext",
     usage=(
-        "Usage: gate-cache --name NAME -- COMMAND [ARGS...]\n"
+        "Usage: gate-cache [--name NAME] -- COMMAND [ARGS...]\n"
         "       gate-cache status [--name NAME] [--json]\n"
         "       gate-cache clear"
     ),
@@ -68,14 +80,14 @@ def run(
     ],
     /,
     *,
-    name: str,
+    name: str | None = None,
 ) -> int:
     """Run COMMAND unless it already passed on the current git tree.
 
     On a skip, prints one line to stderr and exits 0 without running anything. Otherwise
     runs the command and exits with its exit code. The command runs without caching
     (and nothing is recorded) when GATE_CACHE_DISABLE or CI turns caching off, the tree
-    has unstaged changes or untracked files, or this is not a git repository. A pass is recorded only
+    is unknown (for example an unmerged index), or this is not a git repository. A pass is recorded only
     when the command exits 0 and the run leaves the tree unchanged.
 
     Parameters
@@ -84,11 +96,15 @@ def run(
         The command and its arguments, given after `--`. Example: -- uv run pytest -x
     name
         Gate name. Records match only when the name and the tree both match.
+        Defaults to the command and its arguments, quoted as a shell would.
     """
     if not command:
         say("no command given after --")
         return _USAGE_ERROR
-    return run_gate(name, command)
+    if name == "":
+        say("--name needs a value, e.g. gate-cache --name pytest -- uv run pytest")
+        return _USAGE_ERROR
+    return run_gate(shlex.join(command) if name is None else name, command)
 
 
 @app.command
@@ -147,7 +163,7 @@ def _usage_error(tokens: list[str]) -> str | None:
             index += 1
         else:
             break
-    return "put -- before the command, e.g. gate-cache --name pytest -- uv run pytest"
+    return "put -- before the command, e.g. gate-cache -- uv run pytest"
 
 
 def main() -> None: