Feature request: post-cd hook support (`gtr.hook.postCd`)

[echarrod]

Summary

When using gtr cd to switch between worktrees, there's no mechanism to run commands automatically after entering the worktree directory. This is needed for projects where environment variables must be re-sourced relative to the worktree root.

Use case

Our monorepo has a vars.sh script at the root that sets up the development environment. It resolves key variables relative to the script's own location:

export MY_CUSTOM_PATH="${0:a:h}"  # resolves to the directory of vars.sh

When sourced once in ~/.zshrc, these variables permanently point to the main checkout. After gtr cd-ing into a worktree, the environment is stale — tools, paths, and hooks all reference the wrong directory.

We need a way to automatically re-source vars.sh (or run arbitrary commands) when entering a worktree via gtr cd.

Proposal

Add a gtr.hook.postCd configuration option (consistent with the existing gtr.hook.postCreate / gtr.hook.preRemove / gtr.hook.postRemove pattern):

git gtr config set gtr.hook.postCd "source ./vars.sh"

The shell integration wrapper generated by git gtr init zsh|bash|fish would then execute the configured hook(s) after the cd succeeds:

# Rough idea for the zsh wrapper
gtr() {
  if [ "$#" -gt 0 ] && [ "$1" = "cd" ]; then
    shift
    local dir
    dir="$(command git gtr go "$@")" && cd "$dir" && <run postCd hooks>
  else
    command git gtr "$@"
  fi
}

This keeps the hook configurable per-repo (via --local) and doesn't require overriding the shell wrapper.

Why not alternatives?

• direnv: Only exports environment variables — shell functions and other side-effects from sourced scripts are lost. Also requires separate tooling installation.
• Overriding the gtr wrapper: Works but fragile — breaks on upgrades and can't be shared via source control.
• gtr.hook.postCreate: Only runs at worktree creation, not on subsequent cds.

[traycerai]

Plan

Observations

The codebase has a well-established hook system (postCreate, preRemove, postRemove) with configuration mapping between gtr.hook.* (git config) and hooks.* (.gtrconfig file). Shell integration is generated via cmd_init() which creates wrapper functions that intercept gtr cd commands and convert them to git gtr go + cd. The hook execution system in file:lib/hooks.sh supports running commands with environment variables and proper error handling.

Approach

The implementation will extend the existing hook infrastructure to support postCd hooks. The shell wrapper functions (bash/zsh/fish) generated by cmd_init() will be modified to execute postCd hooks after successfully changing directories. Configuration mapping will be added to support both gtr.hook.postCd (git config) and hooks.postCd (.gtrconfig). This approach maintains consistency with the existing hook system and requires no changes to the core hook execution logic.

Implementation Steps

1. Add Configuration Mapping for postCd Hook

File: file:lib/config.sh

Add the postCd hook mapping to the cfg_map_to_file_key() function (around line 92):

• Locate the function cfg_map_to_file_key() which maps gtr.* keys to .gtrconfig equivalents
• Add a new case entry: gtr.hook.postCd) echo "hooks.postCd" ;;
• This should be placed alongside the existing hook mappings (postCreate, preRemove, postRemove)

Update the cfg_list() function's .gtrconfig mapping section (around line 309):

• Add mapping case: hooks.postCd) mapped_key="gtr.hook.postCd" ;;
• This ensures the hook appears correctly when listing configuration

2. Modify Shell Integration Wrappers

File: file:bin/gtr

Update the cmd_init() function to generate shell wrappers that execute postCd hooks after directory changes.

Bash Integration (lines 1600-1620)

Replace the current bash wrapper with an enhanced version that:

• Captures the target directory from git gtr go
• Changes to the directory using cd
• After successful cd, retrieves postCd hooks using git config --get-all gtr.hook.postCd
• Executes each hook in sequence using a while loop
• Sets environment variables: WORKTREE_PATH (the directory), REPO_ROOT (from git rev-parse --show-toplevel), and BRANCH (from git branch --show-current)
• Handles hook failures gracefully with warning messages but doesn't abort the cd operation

Zsh Integration (lines 1622-1642)

Apply the same logic as bash, using zsh-compatible syntax:

• Use local for variable declarations
• Use git config --get-all to retrieve hooks
• Execute hooks with proper environment variable exports
• Handle errors without aborting the directory change

Fish Integration (lines 1644-1661)

Adapt the logic for fish shell syntax:

• Use set -l for local variables
• Use git config --get-all gtr.hook.postCd to retrieve hooks
• Use fish's for loop to iterate over hooks
• Set environment variables using set -lx before executing each hook
• Suppress errors to prevent cd operation from failing

3. Update Documentation

File: file:docs/configuration.md

Add postCd hook documentation in the "Hooks" section (after line 294):

• Add a new row to the hook execution order table:
  • Hook: postCd
  • Timing: After changing directory via gtr cd
  • Use Case: Re-source environment variables, update shell context
• Add example configuration showing how to source a vars.sh script
• Document available environment variables: REPO_ROOT, WORKTREE_PATH, BRANCH
• Note that postCd hooks only run when using the shell integration (gtr cd), not with git gtr go
• Add a note that hook failures are logged but don't prevent the directory change

File: file:templates/.gtrconfig.example

Add postCd hook example in the [hooks] section (after line 50):

• Add commented example: # postCd = source ./vars.sh
• Add comment explaining the use case for re-sourcing environment variables
• Note that this requires shell integration setup via eval "$(git gtr init bash)"

File: file:README.md

Update the hooks example in the "Configuration" section (around line 335):

• Add a brief mention of postCd hook alongside existing hooks
• Reference the full documentation in docs/configuration.md for details

4. Implementation Considerations

Hook Execution Context:

• postCd hooks execute in the user's interactive shell (not a subshell like other hooks)
• This allows hooks to modify the current shell environment (source files, set variables, define functions)
• The shell wrapper must use eval to execute hooks in the current shell context
• Error handling should be non-fatal to prevent breaking the cd operation

Environment Variables:

• WORKTREE_PATH: The absolute path to the worktree directory (same as the cd target)
• REPO_ROOT: The repository root (from git rev-parse --show-toplevel or --git-common-dir)
• BRANCH: The current branch name (from git branch --show-current)

Error Handling:

• Hook failures should log warnings but not prevent the directory change
• Use conditional execution (||) to catch errors and display messages
• Avoid using set -e or similar strict error modes in the wrapper

Performance:

• Minimize overhead by only calling git config once to retrieve all hooks
• Avoid unnecessary subshells or command substitutions
• Keep the wrapper code concise to reduce shell startup time

5. Sequence Diagram

sequenceDiagram
    participant User
    participant Shell as Shell Wrapper (gtr)
    participant GitGTR as git gtr go
    participant GitConfig as git config
    participant Hook as postCd Hook

    User->>Shell: gtr cd my-feature
    Shell->>GitGTR: git gtr go my-feature
    GitGTR-->>Shell: /path/to/worktree
    Shell->>Shell: cd /path/to/worktree
    Shell->>GitConfig: git config --get-all gtr.hook.postCd
    GitConfig-->>Shell: source ./vars.sh
    Shell->>Hook: eval "source ./vars.sh"
    Hook-->>Shell: Environment updated
    Shell-->>User: Directory changed, hooks executed

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a well-established hook system (`postCreate`, `preRemove`, `postRemove`) with configuration mapping between `gtr.hook.*` (git config) and `hooks.*` (.gtrconfig file). Shell integration is generated via `cmd_init()` which creates wrapper functions that intercept `gtr cd` commands and convert them to `git gtr go` + `cd`. The hook execution system in `file:lib/hooks.sh` supports running commands with environment variables and proper error handling.

## Approach

The implementation will extend the existing hook infrastructure to support `postCd` hooks. The shell wrapper functions (bash/zsh/fish) generated by `cmd_init()` will be modified to execute `postCd` hooks after successfully changing directories. Configuration mapping will be added to support both `gtr.hook.postCd` (git config) and `hooks.postCd` (.gtrconfig). This approach maintains consistency with the existing hook system and requires no changes to the core hook execution logic.

## Implementation Steps

### 1. Add Configuration Mapping for postCd Hook

**File: `file:lib/config.sh`**

Add the `postCd` hook mapping to the `cfg_map_to_file_key()` function (around line 92):

- Locate the function `cfg_map_to_file_key()` which maps `gtr.*` keys to `.gtrconfig` equivalents
- Add a new case entry: `gtr.hook.postCd) echo "hooks.postCd" ;;`
- This should be placed alongside the existing hook mappings (`postCreate`, `preRemove`, `postRemove`)

Update the `cfg_list()` function's `.gtrconfig` mapping section (around line 309):

- Add mapping case: `hooks.postCd) mapped_key="gtr.hook.postCd" ;;`
- This ensures the hook appears correctly when listing configuration

### 2. Modify Shell Integration Wrappers

**File: `file:bin/gtr`**

Update the `cmd_init()` function to generate shell wrappers that execute `postCd` hooks after directory changes.

#### Bash Integration (lines 1600-1620)

Replace the current bash wrapper with an enhanced version that:

- Captures the target directory from `git gtr go`
- Changes to the directory using `cd`
- After successful `cd`, retrieves `postCd` hooks using `git config --get-all gtr.hook.postCd`
- Executes each hook in sequence using a while loop
- Sets environment variables: `WORKTREE_PATH` (the directory), `REPO_ROOT` (from `git rev-parse --show-toplevel`), and `BRANCH` (from `git branch --show-current`)
- Handles hook failures gracefully with warning messages but doesn't abort the cd operation

#### Zsh Integration (lines 1622-1642)

Apply the same logic as bash, using zsh-compatible syntax:

- Use `local` for variable declarations
- Use `git config --get-all` to retrieve hooks
- Execute hooks with proper environment variable exports
- Handle errors without aborting the directory change

#### Fish Integration (lines 1644-1661)

Adapt the logic for fish shell syntax:

- Use `set -l` for local variables
- Use `git config --get-all gtr.hook.postCd` to retrieve hooks
- Use fish's `for` loop to iterate over hooks
- Set environment variables using `set -lx` before executing each hook
- Suppress errors to prevent cd operation from failing

### 3. Update Documentation

**File: `file:docs/configuration.md`**

Add `postCd` hook documentation in the "Hooks" section (after line 294):

- Add a new row to the hook execution order table:
  - Hook: `postCd`
  - Timing: After changing directory via `gtr cd`
  - Use Case: Re-source environment variables, update shell context
- Add example configuration showing how to source a `vars.sh` script
- Document available environment variables: `REPO_ROOT`, `WORKTREE_PATH`, `BRANCH`
- Note that `postCd` hooks only run when using the shell integration (`gtr cd`), not with `git gtr go`
- Add a note that hook failures are logged but don't prevent the directory change

**File: `file:templates/.gtrconfig.example`**

Add `postCd` hook example in the `[hooks]` section (after line 50):

- Add commented example: `# postCd = source ./vars.sh`
- Add comment explaining the use case for re-sourcing environment variables
- Note that this requires shell integration setup via `eval "$(git gtr init bash)"`

**File: `file:README.md`**

Update the hooks example in the "Configuration" section (around line 335):

- Add a brief mention of `postCd` hook alongside existing hooks
- Reference the full documentation in `docs/configuration.md` for details

### 4. Implementation Considerations

**Hook Execution Context:**

- `postCd` hooks execute in the user's interactive shell (not a subshell like other hooks)
- This allows hooks to modify the current shell environment (source files, set variables, define functions)
- The shell wrapper must use `eval` to execute hooks in the current shell context
- Error handling should be non-fatal to prevent breaking the cd operation

**Environment Variables:**

- `WORKTREE_PATH`: The absolute path to the worktree directory (same as the cd target)
- `REPO_ROOT`: The repository root (from `git rev-parse --show-toplevel` or `--git-common-dir`)
- `BRANCH`: The current branch name (from `git branch --show-current`)

**Error Handling:**

- Hook failures should log warnings but not prevent the directory change
- Use conditional execution (`||`) to catch errors and display messages
- Avoid using `set -e` or similar strict error modes in the wrapper

**Performance:**

- Minimize overhead by only calling `git config` once to retrieve all hooks
- Avoid unnecessary subshells or command substitutions
- Keep the wrapper code concise to reduce shell startup time

### 5. Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant Shell as Shell Wrapper (gtr)
    participant GitGTR as git gtr go
    participant GitConfig as git config
    participant Hook as postCd Hook

    User->>Shell: gtr cd my-feature
    Shell->>GitGTR: git gtr go my-feature
    GitGTR-->>Shell: /path/to/worktree
    Shell->>Shell: cd /path/to/worktree
    Shell->>GitConfig: git config --get-all gtr.hook.postCd
    GitConfig-->>Shell: source ./vars.sh
    Shell->>Hook: eval "source ./vars.sh"
    Hook-->>Shell: Environment updated
    Shell-->>User: Directory changed, hooks executed
```

---

Execution Information

Branch: main
Commit: c564728

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[echarrod]

Thanks for the quick turnaround @helizaga! 🥳 🚀