Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/agent-usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,12 @@ applies without it: `.gtrconfig` hooks the user has not approved never run.
report its branch, changes, and validation results.
5. Remove the worktree only when the user explicitly asks for cleanup.

List output uses `(detached)` as a display label for detached HEAD; it can also
be a real branch name. Use `git gtr list --ids` and pass the first field's escaped
`path:` identity to target an exact checkout, including detached or duplicate
branch worktrees. Removing a detached checkout never deletes a branch; `mv`
requires an attached branch.

Agents should not run `git gtr trust`. Trusting committed `.gtrconfig` commands
authorizes code execution and requires human review. Agents should also avoid
`git gtr rm --force`, `--delete-branch`, and `git gtr clean` unless the user has
Expand Down
5 changes: 5 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -472,6 +472,11 @@ git gtr config add gtr.hook.postCd "source ./vars.sh"
- `WORKTREE_PATH` - Worktree path
- `BRANCH` - Branch name

For `rm` hooks and `ai` postCd hooks, `BRANCH` is empty when the target has
detached HEAD. The `(detached)` label shown by `list` is display text, not a
branch identity. Shell integration's `gtr cd` hooks retain Git's `HEAD` label
for detached HEAD.

**Examples for different build tools:**

```bash
Expand Down
6 changes: 3 additions & 3 deletions lib/commands/ai.sh
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,9 @@ cmd_ai() {

worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"

log_step "Starting $ai_tool for: $branch"
log_step "Starting $ai_tool for: ${branch:-(detached)}"
log_info "Directory: $worktree_path"
log_info "Branch: $branch"
log_info "Branch: ${branch:-(detached)}"

# Run postCd hooks + AI in a subshell so hook env vars propagate to AI
(
Expand All @@ -48,4 +48,4 @@ cmd_ai() {
BRANCH="$branch"
ai_start "$worktree_path" "${ai_args[@]}"
)
}
}
9 changes: 6 additions & 3 deletions lib/commands/clean.sh
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ _clean_should_skip() {
return 0
fi

if [ -z "$branch" ] || [ "$branch" = "(detached)" ]; then
if [ -z "$branch" ]; then
log_warn "Skipping $dir (detached HEAD)"
return 0
fi
Expand Down Expand Up @@ -228,7 +228,10 @@ _clean_prs() {

local removed=0 skipped=0
local main_branch
main_branch=$(current_branch "$repo_root")
# Older Git cannot resolve an unborn HEAD. This optional skip hint must not
# prevent cleanup of linked worktrees, or retain output from a failed lookup.
main_branch=$(get_current_branch "$repo_root") || main_branch=""
[ "$main_branch" = "HEAD" ] && main_branch=""
local records
records=$(list_worktree_records "$repo_root")

Expand All @@ -238,7 +241,7 @@ _clean_prs() {
"")
if [ -n "$dir" ] && [ "$is_main" != "1" ]; then
# Skip main repo branch silently (not counted)
[ "$branch" = "$main_branch" ] && continue
[ -n "$main_branch" ] && [ "$branch" = "$main_branch" ] && continue

if _clean_should_skip "$dir" "$branch" "$force" "$active_worktree_path"; then
skipped=$((skipped + 1))
Expand Down
2 changes: 1 addition & 1 deletion lib/commands/copy.sh
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ cmd_copy() {
local dst_path dst_branch
resolve_worktree "$target_id" "$repo_root" "$base_dir" "$prefix" || continue

dst_path="$_ctx_worktree_path" dst_branch="$_ctx_branch"
dst_path="$_ctx_worktree_path" dst_branch="${_ctx_branch:-(detached)}"

# Count resolved non-main targets before excluding the source so a
# source-only --all remains a valid no-op.
Expand Down
4 changes: 2 additions & 2 deletions lib/commands/go.sh
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ cmd_go() {
local is_main worktree_path branch
resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1

is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch="${_ctx_branch:-(detached)}"

# Human messages to stderr so stdout can be used in command substitution
if [ "$is_main" = "1" ]; then
Expand All @@ -27,4 +27,4 @@ cmd_go() {

# Print path to stdout for shell integration: cd "$(gtr go my-feature)"
printf "%s\n" "$worktree_path"
}
}
3 changes: 3 additions & 0 deletions lib/commands/list.sh
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,8 @@ cmd_list() {
;;
"branch "*)
branch=$(_tsv_unescape_field "${line#branch }")
# Preserve the public list format; this label is never an identity.
branch="${branch:-(detached)}"
;;
"status "*)
status="${line#status }"
Expand Down Expand Up @@ -113,6 +115,7 @@ EOF
;;
"branch "*)
branch=$(_tsv_unescape_field "${line#branch }")
branch="${branch:-(detached)}"
;;
"status "*)
status="${line#status }"
Expand Down
6 changes: 3 additions & 3 deletions lib/commands/remove.sh
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ cmd_remove() {
WORKTREE_PATH="$worktree_path" \
BRANCH="$branch_name"; then
if [ "$force" -eq 0 ]; then
log_error "Pre-remove hook failed for $branch_name. Use --force to skip hooks."
log_error "Pre-remove hook failed for ${branch_name:-(detached)}. Use --force to skip hooks."
had_failure=1
continue
else
Expand All @@ -59,7 +59,7 @@ cmd_remove() {
continue
fi

# Handle branch deletion
# Detached targets have no branch identity; never delete a display label.
if [ -n "$branch_name" ]; then
if [ "$delete_branch" -eq 1 ]; then
if [ "$yes_mode" -eq 1 ] || prompt_yes_no "Also delete branch '$branch_name'?"; then
Expand All @@ -77,7 +77,7 @@ cmd_remove() {
REPO_ROOT="$repo_root" \
WORKTREE_PATH="$worktree_path" \
BRANCH="$branch_name"; then
log_warn "Post-remove hook failed for $branch_name"
log_warn "Post-remove hook failed for ${branch_name:-(detached)}"
fi
done

Expand Down
5 changes: 5 additions & 0 deletions lib/commands/rename.sh
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,11 @@ cmd_rename() {
exit 1
fi

if [ "$_ctx_detached" -eq 1 ]; then
log_error "Cannot rename a detached worktree; check out a branch first"
exit 1
fi

# Sanitize new name and construct new path
local new_sanitized new_path
new_sanitized=$(sanitize_branch_name "$new_name")
Expand Down
4 changes: 2 additions & 2 deletions lib/commands/run.sh
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ cmd_run() {
local is_main worktree_path branch
resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1

is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
is_main="$_ctx_is_main" worktree_path="$_ctx_worktree_path" branch="${_ctx_branch:-(detached)}"

# Human messages to stderr (like cmd_go)
if [ "$is_main" = "1" ]; then
Expand All @@ -74,4 +74,4 @@ cmd_run() {

# Execute command in worktree directory (exit code propagates)
(cd "$worktree_path" && "${run_args[@]}")
}
}
27 changes: 18 additions & 9 deletions lib/core.sh
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@
# Callers should copy into locals immediately after calling the resolver.
#
# resolve_repo_context() -> _ctx_repo_root _ctx_base_dir _ctx_prefix
# resolve_worktree() -> _ctx_is_main _ctx_worktree_path _ctx_branch
# resolve_worktree() -> _ctx_is_main _ctx_worktree_path _ctx_branch _ctx_detached
declare _ctx_repo_root _ctx_base_dir _ctx_prefix
declare _ctx_is_main _ctx_worktree_path _ctx_branch
declare _ctx_is_main _ctx_worktree_path _ctx_branch _ctx_detached

# Discover the root of the main git repository
# Works correctly from both the main repo and from inside worktrees.
Expand Down Expand Up @@ -191,7 +191,7 @@ get_current_branch() {
fi
}

# Get the current branch of a worktree (with detached HEAD normalization)
# Get the current branch label for display only (never use as branch identity).
# Usage: current_branch worktree_path
current_branch() {
local worktree_path="$1"
Expand Down Expand Up @@ -240,7 +240,8 @@ _emit_worktree_record() {
if [ "$wt_path" = "$repo_root" ] || [ "$wt_path_canonical" = "$repo_root" ]; then
is_main=1
fi
[ -z "$branch" ] && branch="(detached)"
# An empty branch means no attached branch, even when status is locked or
# prunable. Display labels such as '(detached)' are valid Git branch names.
status=$(_worktree_record_status "$wt_detached" "$wt_locked" "$wt_prunable")

printf "is_main %s\n" "$is_main"
Expand Down Expand Up @@ -298,7 +299,8 @@ _parse_worktree_records() {

# List registered git worktrees for a repository.
# Usage: list_worktree_records repo_root
# Output: blank-line-delimited records with is_main/path/branch/status fields
# Output: blank-line-delimited records with is_main/path/branch/status fields.
# The branch field is empty for detached worktrees; status may also be locked.
list_worktree_records() {
local repo_root="$1"
local repo_root_canonical
Expand Down Expand Up @@ -480,6 +482,7 @@ EOF
# Resolve a registered path identity, branch, literal folder alias, or main ID '1'.
# Usage: resolve_target identifier repo_root base_dir prefix
# Returns: tab-separated "is_main\tpath\tbranch" with escaped fields on success (is_main: 1 for main repo, 0 for worktrees)
# An empty final field represents detached HEAD, never a display label.
# Exit code: 0 on success, 1 if not found
resolve_target() {
local identifier="$1"
Expand Down Expand Up @@ -509,6 +512,8 @@ resolve_target() {
# Special case: ID 1 is always the repo root
if [ "$identifier" = "1" ]; then
branch=$(get_current_branch "$repo_root") || return 1
# Older Git's rev-parse fallback reports HEAD instead of an empty branch.
[ "$branch" = "HEAD" ] && branch=""
_print_resolved_target "1" "$repo_root" "$branch"
return 0
fi
Expand Down Expand Up @@ -582,7 +587,7 @@ EOF
}

# Unpack TSV output from resolve_target into globals.
# Sets: _ctx_is_main, _ctx_worktree_path, _ctx_branch
# Sets: _ctx_is_main, _ctx_worktree_path, _ctx_branch, _ctx_detached (0 or 1)
# Usage: unpack_target "$target_string"
unpack_target() {
local escaped_path escaped_branch
Expand All @@ -592,11 +597,15 @@ unpack_target() {
_ctx_worktree_path=$(_tsv_unescape_field "$escaped_path" && printf '.') || return 1
_ctx_worktree_path="${_ctx_worktree_path%.}"
_ctx_branch=$(_tsv_unescape_field "$escaped_branch")
_ctx_detached=0
if [ -z "$_ctx_branch" ]; then
_ctx_detached=1
fi
}

# Resolve an identifier to a worktree and set _ctx_* variables in one step
# Usage: resolve_worktree <identifier> <repo_root> <base_dir> <prefix>
# Sets: _ctx_is_main, _ctx_worktree_path, _ctx_branch
# Sets: _ctx_is_main, _ctx_worktree_path, _ctx_branch, _ctx_detached
resolve_worktree() {
local target
# Guard the subshell too: a handled miss must not fire Bash 3.2's ERR trap.
Expand Down Expand Up @@ -1111,7 +1120,7 @@ list_worktree_branches() {
while IFS= read -r line; do
case "$line" in
"")
if [ "$is_main" != "1" ] && [ -n "$branch" ] && [ "$branch" != "(detached)" ]; then
if [ "$is_main" != "1" ] && [ -n "$branch" ]; then
printf "%s\n" "$branch"
fi
is_main=""
Expand All @@ -1133,7 +1142,7 @@ list_worktree_branches() {
$records
EOF

if [ "$is_main" != "1" ] && [ -n "$branch" ] && [ "$branch" != "(detached)" ]; then
if [ "$is_main" != "1" ] && [ -n "$branch" ]; then
printf "%s\n" "$branch"
fi
}
14 changes: 8 additions & 6 deletions tests/cmd_clean.bats
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,10 @@ teardown() {

# ── _clean_should_skip ──────────────────────────────────────────────────────

@test "_clean_should_skip skips detached HEAD" {
run _clean_should_skip "/some/dir" "(detached)"
[ "$status" -eq 0 ]
@test "_clean_should_skip accepts a real branch named detached" {
create_test_worktree '(detached)'
run _clean_should_skip "$TEST_WT_PATH" '(detached)'
[ "$status" -eq 1 ]
}

@test "_clean_should_skip skips empty branch" {
Expand Down Expand Up @@ -92,9 +93,10 @@ teardown() {
[ "$status" -eq 1 ] # 1 = don't skip
}

@test "_clean_should_skip with force=1 still skips detached HEAD" {
run _clean_should_skip "/some/dir" "(detached)" 1
[ "$status" -eq 0 ] # 0 = skip (protection maintained)
@test "_clean_should_skip with force=1 accepts a real branch named detached" {
create_test_worktree '(detached)'
run _clean_should_skip "$TEST_WT_PATH" '(detached)' 1
[ "$status" -eq 1 ]
}

@test "_clean_should_skip with force=1 still skips empty branch" {
Expand Down
8 changes: 5 additions & 3 deletions tests/core_resolve_target.bats
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,8 @@ teardown() {

resolve_worktree "review" "$TEST_REPO" "$TEST_WORKTREES_DIR" ""
[ "$_ctx_worktree_path" = "$TEST_WORKTREES_DIR/review" ]
[ "$_ctx_branch" = "(detached)" ]
[ -z "$_ctx_branch" ]
[ "$_ctx_detached" -eq 1 ]
}

@test "resolve_target rejects stray directories and dot targets" {
Expand Down Expand Up @@ -376,7 +377,7 @@ teardown() {

[[ "$records" == *"is_main 1"$'\n'"path $repo_root"$'\n'*"status ok"* ]]
[[ "$records" == *"is_main 0"$'\n'"path $normal_path"$'\n'"branch records-normal"$'\n'"status ok"* ]]
[[ "$records" == *"is_main 0"$'\n'"path $detached_path"$'\n'"branch (detached)"$'\n'"status detached"* ]]
[[ "$records" == *"is_main 0"$'\n'"path $detached_path"$'\n'"branch "$'\n'"status detached"* ]]
[[ "$records" == *"is_main 0"$'\n'"path $locked_path"$'\n'"branch records-locked"$'\n'"status locked"* ]]

git -C "$TEST_REPO" worktree unlock "$TEST_WORKTREES_DIR/records-locked"
Expand Down Expand Up @@ -510,6 +511,7 @@ teardown() {
}
resolve_worktree "path:$(_tsv_escape_field "$path")" "$TEST_REPO" "$TEST_WORKTREES_DIR" ""
[ "$_ctx_worktree_path" = "$path" ]
[ "$_ctx_branch" = '(detached)' ]
[ -z "$_ctx_branch" ]
[ "$_ctx_detached" -eq 1 ]
[ ! -e should-not-exist ]
}
Loading
Loading