feat: add postCd hook for shell integration (#108)

[helizaga]

Summary

Adds a new gtr.hook.postCd hook that runs commands in the user's current shell after gtr cd changes directory. Closes #108.

• Hooks execute inline in the shell wrapper (not a subshell), so they can source files, set env vars, and modify shell state
• Reads from both git config (gtr.hook.postCd) and .gtrconfig (hooks.postCd), with deduplication
• Exports REPO_ROOT, WORKTREE_PATH, and BRANCH env vars (consistent with other hooks)
• Implemented for all three shell wrappers: bash, zsh, and fish
• Failures warn to stderr but don't undo the cd

Example use cases:

# Re-source environment after navigating to a worktree
git gtr config add gtr.hook.postCd "source ./vars.sh"

# Activate Python venv
git gtr config add gtr.hook.postCd "source .venv/bin/activate"

# Switch Node version
git gtr config add gtr.hook.postCd "nvm use"

Changes

• bin/gtr — postCd hook logic in bash/zsh/fish shell wrappers + help text
• lib/config.sh — forward and reverse key mapping for gtr.hook.postCd ↔ hooks.postCd
• completions/ — all three completion files updated with gtr.hook.postCd
• docs/configuration.md — hook table and notes updated
• README.md — quick-start example added
• templates/.gtrconfig.example — commented example added

Test plan

• eval "$(./bin/gtr init bash)" then gtr cd <branch> — verify postCd hooks fire
• Configure gtr.hook.postCd via git config --add — verify it runs after cd
• Configure hooks.postCd in .gtrconfig — verify it runs after cd
• Configure both — verify deduplication (same command runs once)
• Verify REPO_ROOT, WORKTREE_PATH, BRANCH env vars are set during hook execution
• Verify env vars are unset after hooks complete (bash/zsh) or scoped (fish)
• Test hook failure — verify warning printed, cd still succeeds
• Test fish shell wrapper separately
• Verify git gtr config list shows postCd hooks
• Verify tab completion includes gtr.hook.postCd in all three shells

Summary by CodeRabbit

• New Features
  • Added post-cd hooks that execute in the current shell after gtr cd completes, enabling environment setup and variable sourcing. Configure via gtr.hook.postCd globally or per-repo. Hooks receive environment context and failures warn without affecting the directory change.

[coderabbitai]

Walkthrough

A new post-cd hook feature executes user-defined commands after gtr cd. Hooks are read from git config (gtr.hook.postCd) and per-repo .gtrconfig (hooks.postCd), merged and deduplicated, run with WORKTREE_PATH, REPO_ROOT, and BRANCH set, and then the env vars are unset. Shell integrations (bash, zsh, fish) and completions updated.

Changes

Cohort / File(s)	Summary
Core Hook Execution bin/gtr	Implements loading/execution of post-cd hooks: reads from git config and .gtrconfig, merges/deduplicates while preserving order, sets WORKTREE_PATH/REPO_ROOT/BRANCH, executes hooks (via eval), surfaces errors to stderr, and unsets env vars. Updates shell integration wrappers for bash/zsh/fish to run hooks after cd.
Config Mapping & Templates lib/config.sh, templates/.gtrconfig.example, README.md	Adds mapping for gtr.hook.postCd ⇄ hooks.postCd, and documents/example entry in .gtrconfig/README.
Completions completions/_git-gtr, completions/gtr.bash, completions/git-gtr.fish	Adds gtr.hook.postCd to completions and replaces obsolete gtr.hook.postRemove references where applicable.
Documentation docs/configuration.md	Documents the new postCd hook in the hooks execution order, explains that it runs in the current shell only for gtr cd, and lists the hook environment variables (REPO_ROOT, WORKTREE_PATH, BRANCH).

Sequence Diagram

sequenceDiagram
    participant Shell as Shell Integration
    participant GitConfig as Git Config
    participant RepoConfig as .gtrconfig File
    participant HookMgr as Hook Manager
    participant Eval as Eval Executor

    Shell->>GitConfig: Read gtr.hook.postCd
    Shell->>RepoConfig: Read hooks.postCd
    HookMgr->>HookMgr: Merge & Deduplicate hooks
    HookMgr->>HookMgr: Export WORKTREE_PATH, REPO_ROOT, BRANCH
    HookMgr->>Eval: Eval each hook command
    Eval-->>Shell: Return exit status / errors
    HookMgr->>HookMgr: Unset WORKTREE_PATH, REPO_ROOT, BRANCH

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 A soft hop into a new tree's shade,
I source the vars the devs have laid,
With WORKTREE_PATH and branch in view,
I run the hooks and bid adieu,
A rabbit's tweak — the shell's parade. 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: add postCd hook for shell integration (#108)' clearly and concisely describes the main change—adding a new postCd hook feature for shell integration.
Linked Issues check	✅ Passed	The PR successfully implements all key requirements from issue #108: adds gtr.hook.postCd configuration option, executes hooks after gtr cd in shell wrappers (bash, zsh, fish), supports both git config and .gtrconfig sources, runs inline in current shell for sourcing/env vars, and preserves compatibility.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the postCd hook feature: core functionality in bin/gtr and lib/config.sh, shell completions, documentation, examples, and README updates—no unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/postCd-hook

---

No actionable comments were generated in the recent review. 🎉

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/configuration.md`:
- Around line 309-312: MD028 is triggered by a blank line inside a single
blockquote; remove the empty line between the two Note blockquote lines so they
remain in the same contiguous blockquote (i.e., merge the two quoted Note lines
into one continuous blockquote without blank lines) so the two lines: "**Note:**
Pre-remove hooks..." and "**Note:** `postCd` hooks..." are part of the same
blockquote and comply with markdownlint.