feat: add gtr.nextStep for custom next steps

[damianlewis]

Pull Request

Description

Add gtr.nextStep configuration for displaying custom project-specific next steps after worktree creation. Steps appear alongside built-in next steps and support variable substitution ($BRANCH, $WORKTREE_PATH, $REPO_ROOT) with both $VAR and ${VAR} syntax.

Motivation

While postCreate hooks can run commands, their output appears before the "Next steps" section. Users need a way to display project-specific guidance (like npm install or cp .env.example .env) in the logical place alongside other next steps.

Fixes #49

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring (no functional changes)
• Other (please describe):

Testing

Manual Testing Checklist

Tested on:

• macOS
• Linux (specify distro: _______)
• Windows (Git Bash)

Core functionality tested:

• git gtr new <branch> - Create worktree
• git gtr go <branch> - Navigate to worktree
• git gtr editor <branch> - Open in editor (if applicable)
• git gtr ai <branch> - Start AI tool (if applicable)
• git gtr rm <branch> - Remove worktree
• git gtr list - List worktrees
• git gtr config - Configuration commands (if applicable)
• Other commands affected by this change: N/A

Test Steps

1. Add multiple custom next steps:

   git gtr config add gtr.nextStep "npm install  # Install dependencies"
   git gtr config add gtr.nextStep "cp .env.example .env  # Setup environment"
   git gtr config add gtr.nextStep 'Branch: $BRANCH'

2. Create a worktree:

   git gtr new test-feature

3. Verify output shows all custom steps with variable substitution:

   Next steps:
     git gtr editor test-feature  # Open in editor
     git gtr ai test-feature      # Start AI tool
     cd "$(git gtr go test-feature)"  # Navigate to worktree
     npm install  # Install dependencies
     cp .env.example .env  # Setup environment
     Branch: test-feature
   

Expected behavior: Custom next steps appear after built-in steps with variables substituted.

Actual behavior: Custom next steps appear after built-in steps with variables substituted.

Breaking Changes

• This PR introduces breaking changes
• I have discussed this in an issue first
• Migration guide is included in documentation

Checklist

Before submitting this PR, please check:

• I have read CONTRIBUTING.md
• My code follows the project's style guidelines
• I have performed manual testing on at least one platform
• I have updated documentation (README.md, CLAUDE.md, etc.) if needed
• My changes work on multiple platforms (or I've noted platform-specific behavior)
• I have added/updated shell completions (if adding new commands or flags)
• I have tested with both git gtr (production) and ./bin/gtr (development)
• No new external dependencies are introduced (Bash + git only)
• All existing functionality still works

Additional Context

Example output after worktree creation:

Next steps:
  git gtr editor feature-branch  # Open in editor
  git gtr ai feature-branch      # Start AI tool
  cd "$(git gtr go feature-branch)"  # Navigate to worktree
  npm install  # Install dependencies
  cp .env.example .env  # Setup environment

---

License Acknowledgment

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache License 2.0.

Summary by CodeRabbit

Release Notes

• New Features

  • Added support for custom next steps after worktree creation via the gtr.nextStep configuration option.
  • Support for variable substitution ($BRANCH, $WORKTREE_PATH, $REPO_ROOT) within custom steps.

• Documentation

  • Updated configuration documentation and examples with guidance for multi-valued next steps.
  • Enhanced shell completion support for the new configuration option.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This change introduces support for custom next steps after worktree creation via a new gtr.nextStep multi-valued configuration option. The feature reads configured steps, performs variable substitution, and displays them alongside built-in next steps. Implementation spans documentation, shell completion support, configuration templates, and the main script.

Changes

Cohort / File(s)	Summary
Documentation CLAUDE.md, README.md	Added configuration documentation for gtr.nextStep and two "Custom Next Steps" sections explaining how to configure and use multi-valued next steps with supported variable substitutions ($BRANCH, $WORKTREE_PATH, $REPO_ROOT)
Runtime Implementation bin/gtr	Implemented custom next steps display: reads multiple lines from gtr.nextStep configuration, substitutes variables, and echoes customized steps after worktree creation
Shell Completions completions/_git-gtr, completions/gtr.bash, completions/gtr.fish	Extended configuration completers to expose gtr.nextStep as a valid config key with appropriate descriptions
Configuration Templates templates/.gtrconfig.example, templates/gtr.config.example	Added new [nextSteps] and "Custom Next Steps" sections to configuration examples with documented variable substitutions and sample step entries

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

• bin/gtr: Review the variable substitution logic and config reading mechanism to ensure correct parsing and output formatting
• Completion files: Verify consistency of gtr.nextStep option name across all three completion systems
• Documentation accuracy: Confirm that documented variable substitutions and examples align with implementation in bin/gtr

Poem

🐰 A rabbit hops through config files so neat,
With custom steps that make the workflow sweet!
Variables dance: $BRANCH, $PATH, $ROOT,
Next steps bloom where users set the boot.
Completions click, templates smile—so fleet! ✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly and concisely describes the main feature: adding gtr.nextStep for custom next steps. It aligns with the primary objective of implementing multi-valued configuration for custom next steps after worktree creation.
Linked Issues check	✅ Passed	The PR implements all key requirements from issue #49: adds gtr.nextStep multi-valued configuration option, supports variable substitution ($BRANCH, $WORKTREE_PATH, $REPO_ROOT), displays custom steps alongside built-ins after worktree creation, and enables team sharing via .gtrconfig.
Out of Scope Changes check	✅ Passed	All changes are in-scope: configuration implementation (bin/gtr), documentation (README, CLAUDE.md), completion scripts (bash, zsh, fish), and example templates. No unrelated modifications detected; all align with the #49 requirements.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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