You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: refresh agent guides, README flags, and troubleshooting for v2.11 (#197)
Brings AGENTS.md, CLAUDE.md, README and the docs/ pages in line with what shipped in v2.9 through v2.11.
Fixes two errors: AGENTS.md pointed at a nonexistent adapters/ai/Codex.sh, and docs/troubleshooting.md told users to run 'bash -x git gtr', which cannot work because git is a binary. The architecture diagram there also had bin/git-gtr and bin/gtr the wrong way round.
Adds --sparse/--no-sparse to the README, the missing GTR_* fallback variables and the direct-read variables to docs/configuration.md, and a side-effect section to docs/agent-usage.md. AGENTS.md and CLAUDE.md now cover pr, trust, clean --closed, sparse inheritance, postCd dispatch and the current test layout.
Copy file name to clipboardExpand all lines: AGENTS.md
+41-29Lines changed: 41 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# AGENTS.md
2
2
3
-
This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
3
+
This file provides guidance to AI coding agents (Codex, Copilot, and similar tools) when working with code in this repository.
4
4
5
5
## Project Overview
6
6
@@ -32,7 +32,7 @@ This project uses **BATS tests** for core functions and **manual smoke tests** f
32
32
33
33
For exhaustive manual testing (hooks, copy patterns, adapters, `--force`, `--from-current`, etc.), see the full checklist in CONTRIBUTING.md or `.github/instructions/testing.instructions.md`.
34
34
35
-
**Test files**: `adapters`, `config`, `copy_safety`, `integration_lifecycle`, `parse_args`, `provider`, `resolve_base_dir`, `sanitize_branch_name` (all in `tests/`). Shared fixtures in `tests/test_helper.bash`.
35
+
**Test files** (all in `tests/`): one `cmd_*.bats` file per command (`cmd_clean`, `cmd_config`, `cmd_copy`, `cmd_create_integration`, `cmd_go`, `cmd_help`, `cmd_list`, `cmd_pr`, `cmd_remove`, `cmd_rename`, `cmd_run`, `cmd_trust`), library tests (`adapters`, `completion`, `config`, `copy_safety`, `core_create_worktree`, `core_resolve_target`, `hooks`, `init`, `launch`, `parse_args`, `platform`, `provider`, `resolve_base_dir`, `sanitize_branch_name`, `sparse`, `ui_color`), and `integration_lifecycle` for end-to-end flows. Shared fixtures in `tests/test_helper.bash`.
36
36
37
37
**Tip**: Use a disposable repo for testing to avoid polluting your working tree:
|`lib/commands/*.sh`| One file per subcommand: `cmd_create`, `cmd_remove`, `cmd_pr`, `cmd_trust`, etc. (18 files) |
66
66
67
67
Libraries are sourced in the order listed above (ui → args → config → ... → launch → commands/\*.sh glob).
68
68
69
+
`postCd` hooks have two dispatch paths, neither of which is `run_hooks_in`: `run_hooks_export`, called inside a subshell from `lib/launch.sh` and `lib/commands/ai.sh` so that environment changes made by the hooks reach the AI tool launched in that same subshell (the editor paths run no postCd hooks), and the `gtr cd` shell functions generated by `init`, which read `gtr.hook.postCd` (plus `.gtrconfig``hooks.postCd`) and `eval` each hook directly in the user's shell.
70
+
69
71
### Adapters
70
72
71
73
Most adapters are defined declaratively in the **adapter registry** (`lib/adapters.sh`) using pipe-delimited entries. Custom adapters that need special logic remain as override files in `adapters/editor/` and `adapters/ai/`.
Key dispatch: `new`→`cmd_create`, `pr`→`cmd_pr`, `rm`→`cmd_remove`, `mv|rename`→`cmd_rename`, `go`→`cmd_go`, `run`→`cmd_run`, `editor`→`cmd_editor`, `ai`→`cmd_ai`, `copy`→`cmd_copy`, `ls|list`→`cmd_list`, `clean`→`cmd_clean`, `init`→`cmd_init`, `config`→`cmd_config`, `completion`→`cmd_completion`, `doctor`→`cmd_doctor`, `adapter|adapters`→`cmd_adapter`, `trust`→`cmd_trust`. `cd` has no `cmd_*` handler: the dispatcher prints shell-integration instructions because `gtr cd` is implemented by the shell function that `init` generates.
**`init` command**: Outputs shell functions for `gtr cd <branch>` navigation. Output is cached to `~/.cache/gtr/` and auto-invalidates on version change. Users source the cache file directly in their shell rc for fast startup (see `git gtr help init`).
116
118
117
-
**`clean --merged`**: Removes worktrees whose PRs/MRs are merged. Auto-detects GitHub (`gh`) or GitLab (`glab`) from the `origin` remote URL. Override with `gtr.provider` config for self-hosted instances.
119
+
**`clean --merged` / `clean --closed`**: Removes worktrees whose PRs/MRs are merged or closed and deletes their branches. Auto-detects GitHub (`gh`) or GitLab (`glab`) from the `origin` remote URL. Override with `gtr.provider` config for self-hosted instances. `clean` also unlocks and prunes locked registry entries whose directories no longer exist.
120
+
121
+
**`pr <number|url|branch>`** (lib/commands/pr.sh): Creates a worktree from a GitHub pull request via `gh`. Uses `gh pr checkout --worktree` when the installed `gh` supports it, otherwise fetches `refs/pull/<n>/head` through a compatibility path.
122
+
123
+
**`new --porcelain`**: Emits exactly three `key<TAB>value` records (`path`, `branch`, `hook_status`) on stdout with everything else on stderr. Contract documented in `docs/agent-usage.md`; keep it stable.
124
+
125
+
**Sparse-checkout inheritance** (`gtr.sparse.inherit`, default on): On Git 2.36+, `new` copies the base worktree's sparse-checkout patterns instead of materializing a full tree. `--sparse`/`--no-sparse` override per invocation.
118
126
119
127
## Common Development Tasks
120
128
121
129
### Adding a New Command
122
130
123
131
1. Create `lib/commands/<name>.sh` with `cmd_<name>()` function
124
-
2. Add case entry in `main()` dispatcher in `bin/gtr`
132
+
2. Add case entry in `main()` dispatcher in `bin/git-gtr`
125
133
3. Add help text in `lib/commands/help.sh`
126
-
4.Update all three completion files: `completions/gtr.bash`, `completions/_git-gtr`, `completions/git-gtr.fish`
134
+
4.Add the command and its flags to the `generate_bash`, `generate_zsh`, and `generate_fish` templates in `scripts/generate-completions.sh`, then run `./scripts/generate-completions.sh` (the files under `completions/` are generated; CI runs `--check`)
127
135
5. Update README.md
128
136
129
137
### Adding an Adapter
130
138
131
-
**Standard adapters** (just a command name + error message): Add an entry to `_EDITOR_REGISTRY` or `_AI_REGISTRY` in `lib/adapters.sh`. Then update: help text in `lib/commands/help.sh`, all three completions, README.md.
139
+
**Standard adapters** (just a command name + error message): Add an entry to `_EDITOR_REGISTRY` or `_AI_REGISTRY` in `lib/adapters.sh`. Then update help text in `lib/commands/help.sh` and README.md, and run `./scripts/generate-completions.sh` (registry names feed the completions automatically).
132
140
133
-
**Custom adapters** (special logic needed): Create `adapters/{editor,ai}/<name>.sh` implementing the two required functions (see `adapters/ai/Codex.sh` for an example). File-based adapters take priority over registry entries.
141
+
**Custom adapters** (special logic needed): Create `adapters/{editor,ai}/<name>.sh` implementing the two required functions (see `adapters/ai/claude.sh` for an example). File-based adapters take priority over registry entries.
134
142
135
143
### Updating the Version
136
144
137
145
Update `GTR_VERSION` in `bin/git-gtr`.
138
146
139
147
### Shell Completion Updates
140
148
141
-
When adding commands or flags, update all three files:
142
-
143
-
-`completions/gtr.bash` (Bash)
144
-
-`completions/_git-gtr` (Zsh)
145
-
-`completions/git-gtr.fish` (Fish)
149
+
`completions/gtr.bash`, `completions/_git-gtr`, and `completions/git-gtr.fish` are generated by `scripts/generate-completions.sh` and carry a `DO NOT EDIT MANUALLY` header. Adapter names come from `_EDITOR_REGISTRY` / `_AI_REGISTRY`, config keys from `_CFG_KEY_MAP`, and commands and flags from the three `generate_*` templates inside the script. After changing any of those, run `./scripts/generate-completions.sh` and commit the result; CI fails when `--check` finds a difference.
146
150
147
151
## Critical Gotcha: `set -e`
148
152
@@ -171,17 +175,23 @@ All config uses `gtr.*` prefix via `git config`. Key settings:
171
175
172
176
-`gtr.worktrees.dir` — Base directory (default: `<repo-name>-worktrees` sibling)
-`gtr.hook.postCreate` / `gtr.hook.preRemove` / `gtr.hook.postRemove` / `gtr.hook.postCd` — Hook commands (multi-valued; `postCd` runs in the current shell after `gtr cd`, `gtr new --cd`, or `gtr pr --cd`)
185
+
186
+
Every `cfg_default` key also has an environment-variable fallback (for example `GTR_WORKTREES_DIR`, `GTR_DEFAULT_BRANCH`); the full table is in `docs/configuration.md`.
178
187
179
188
Hook env vars: `REPO_ROOT`, `WORKTREE_PATH`, `BRANCH`. preRemove hooks run with cwd in worktree; failure aborts removal unless `--force`.
180
189
181
190
## Debugging
182
191
183
192
```bash
184
193
bash -x ./bin/gtr <command># Full trace
194
+
GTR_DEBUG=1 ./bin/gtr <command># Report file:line:function on an unguarded failure
185
195
declare -f function_name # Check function definition
Copy file name to clipboardExpand all lines: CHANGELOG.md
+11Lines changed: 11 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,9 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com), and this
6
6
7
7
## [Unreleased]
8
8
9
+
### Changed
10
+
11
+
- The README documents `--sparse`/`--no-sparse` under `git gtr new` and lists the Maintainers section in its table of contents.
12
+
-`docs/agent-usage.md` explains how to suppress hooks, file copying, and fetching for bare automation worktrees.
13
+
-`docs/configuration.md` lists the remaining `GTR_*` fallback variables and now separates them from the variables read directly (`GTR_DIR`, `GTR_EDITOR_CMD`, `GTR_AI_CMD`, `GTR_COLOR`, `NO_COLOR`), which do not follow the configuration precedence order.
14
+
-`docs/troubleshooting.md` replaces a `bash -x git gtr` instruction that cannot work with a trace of the real script, and documents `GTR_DEBUG`.
15
+
-`AGENTS.md` and `CLAUDE.md` now cover the `pr` and `trust` commands, `clean --closed`, sparse-checkout inheritance, `postCd` hooks, and the current test suite layout, and describe the completion files as generated by `scripts/generate-completions.sh`.
16
+
9
17
### Fixed
10
18
11
19
-`GTR_DEBUG=1` now reports the file, line and function of an unexpected failure. `bin/git-gtr` installed an `ERR` trap but ran under `set -e` alone, so the trap was never inherited by functions; since every command runs inside `main()` and a `cmd_*` handler, the variable had no observable effect. The script now uses `set -eE`, which changes nothing when the trap is not installed.
20
+
-`AGENTS.md` referenced a nonexistent `adapters/ai/Codex.sh`; it now points at `adapters/ai/claude.sh`.
21
+
- The architecture diagram in `docs/troubleshooting.md` described `bin/git-gtr` as a wrapper around `bin/gtr`; the roles are reversed and the remaining `lib/` modules are listed.
22
+
-`AGENTS.md` and `CLAUDE.md` attributed `postCd` hooks to `run_hooks_in`; they now describe `run_hooks_export` and the `init`-generated shell functions, and distinguish the paths: the AI launch path runs them when the tool starts, while the shell functions generated by `init` run them for `gtr cd` and the `--cd` flows.
0 commit comments