Add shell-integration support for new --cd

[helizaga]

Description

Add --cd to the shell integration generated by git gtr init, so gtr new <branch> --cd creates a worktree and lands in it.

Motivation

Fixes #150.

The raw git gtr new command cannot change the caller shell's current directory, so this keeps --cd out of the core CLI surface and implements it only in the shell wrapper.

Type of Change

• New feature (non-breaking change that adds functionality)
• Documentation update

Testing

• bats tests/
• Manual smoke tests in disposable repos:
  • gtr new plain --from HEAD --no-fetch --yes keeps cwd unchanged
  • gtr new demo --cd --from HEAD --no-fetch --yes cds into the new worktree and runs postCd
  • gtr new demo --cd --force --name backend --from HEAD --no-fetch --yes
  • gtr new folder-branch --cd --folder alt --from HEAD --no-fetch --yes
  • GTR_EDITOR_DEFAULT=true gtr new editor-demo --cd -e --from HEAD --no-fetch --yes
  • GTR_AI_DEFAULT=true gtr new ai-demo --cd -a --from HEAD --no-fetch --yes

Notes

• postCd hooks now run after gtr new --cd
• git gtr new flag surface is unchanged

Summary by CodeRabbit

• New Features

  • Added --cd flag to gtr new command, enabling creation and navigation to a new worktree in one step
  • Post-cd hooks now execute after both gtr cd and gtr new --cd operations

• Documentation

  • Updated help text and README with examples demonstrating the new create-and-navigate workflow
  • Enhanced configuration documentation to clarify post-cd hook behavior

• Tests

  • Added comprehensive test coverage for the new --cd functionality across supported shells

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: cf15a309-c595-4ea2-a644-1e9fca3feeab

📥 Commits

Reviewing files that changed from the base of the PR and between 99368b0 and 7b225b9.

📒 Files selected for processing (6)

• README.md
• docs/configuration.md
• lib/commands/help.sh
• lib/commands/init.sh
• tests/cmd_help.bats
• tests/init.bats

---

Walkthrough

The PR implements the --cd flag for gtr new command that creates a worktree and automatically navigates into it. It centralizes post-cd hook execution across Bash, Zsh, and Fish shells and updates documentation accordingly.

Changes

Cohort / File(s)	Summary
Documentation README.md, docs/configuration.md	Updated workflow examples and post-cd hook descriptions to document the new gtr new <branch> --cd pattern and clarify hook applicability.
Help & Command References lib/commands/help.sh	Updated help text to document the new --cd flag for shell integration, with explicit examples of the create-and-navigate workflow.
Core Implementation lib/commands/init.sh	Introduced __FUNC___run_post_cd_hooks() function for centralized post-cd hook execution across Bash, Zsh, and Fish. Extended new subcommand to support --cd flag, detect new worktree directory via diff, and run hooks. Replaced inline hook execution with centralized function calls.
Tests tests/cmd_help.bats, tests/init.bats	Added test case verifying help text includes gtr new my-feature --cd suggestion, and comprehensive test suite for --cd wrapper support across all shells including flag stripping, worktree detection, and completion behavior.

Sequence Diagram

sequenceDiagram
    actor User
    participant Wrapper as gtr Wrapper<br/>(Bash/Zsh/Fish)
    participant Git as git gtr
    participant FS as Filesystem
    participant Hooks as Post-cd Hooks

    User->>Wrapper: gtr new my-feature --cd
    Wrapper->>Wrapper: Strip --cd flag
    Wrapper->>Git: git gtr new my-feature
    Git->>FS: Create worktree
    Git-->>Wrapper: Return success
    Wrapper->>FS: Detect new directory<br/>(via worktree diff)
    Wrapper->>Wrapper: Set env vars<br/>(WORKTREE_PATH, REPO_ROOT, BRANCH)
    Wrapper->>Hooks: Load hooks from git config<br/>& .gtrconfig
    Wrapper->>Hooks: Run post-cd hooks
    Hooks-->>Wrapper: Hook results
    Wrapper->>FS: Change to new directory
    Wrapper-->>User: Ready in new worktree

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 A worktree born, a hop, a skip,
With --cd flag, we make the trip!
New branch and home in just one leap,
Hooks dance as we settle deep. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main feature added: shell-integration support for a --cd flag on the new command.
Linked Issues check	✅ Passed	The PR implements the requested --cd flag for the new command to automatically navigate into newly created worktrees, with postCd hooks execution, fully meeting issue #150 requirements.
Out of Scope Changes check	✅ Passed	All changes are scoped to implementing the --cd feature: documentation updates, help text, shell wrapper logic, and related tests. No unrelated changes detected.

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

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch tommy/issue-150-shell-new-cd

---

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