feat: add --editor and --ai flags to new command #72
Conversation
…tation - Enhanced README with new sections including Table of Contents, Shell Completions, and License. - Introduced new documentation files for advanced usage, configuration reference, and troubleshooting to provide comprehensive guidance for users.
WalkthroughAdds Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant CLI as gtr CLI
participant Worktree as Worktree Creator
participant EditorAdapter as Editor Adapter
participant AIAdapter as AI Adapter
participant Tool as External Tool
User->>CLI: gtr create [args] (--editor / --ai / none)
CLI->>Worktree: create worktree at path
Worktree-->>CLI: created
alt --editor flag present
rect rgb(240,248,255)
note over CLI,EditorAdapter: Load editor adapter (configured or fallback)
CLI->>EditorAdapter: load & open path
EditorAdapter->>Tool: launch editor with worktree path
Tool-->>User: editor opened
end
else --ai flag present
rect rgb(255,240,245)
note over CLI,AIAdapter: Load AI adapter (configured or warn)
CLI->>AIAdapter: load & start in path
AIAdapter->>Tool: start AI tool for worktree
Tool-->>User: AI tool started
end
else neither flag
rect rgb(245,245,220)
CLI-->>User: print "Next steps" guidance
end
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Disabled knowledge base sources:
📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (1)
🧰 Additional context used📓 Path-based instructions (1)README.md📄 CodeRabbit inference engine (CLAUDE.md)
Files:
🔇 Additional comments (9)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI Agents
In @docs/configuration.md:
- Around line 122-136: The table is missing the Copilot adapter; add a row for
"Copilot" matching the other entries using the adapter name/key "copilot" and
reference the adapter script "copilot.sh" from adapters/ai; include an Install
hint (e.g., how to obtain or run copilot.sh or a short install command if
applicable), a concise Use Case (e.g., GitHub Copilot CLI integration / AI
coding assistant), and the Set as Default example `git gtr config set
gtr.ai.default copilot` so the docs list all eight adapters consistently.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (8)
README.mdbin/gtrcompletions/_git-gtrcompletions/git-gtr.fishcompletions/gtr.bashdocs/advanced-usage.mddocs/configuration.mddocs/troubleshooting.md
🧰 Additional context used
📓 Path-based instructions (10)
completions/*
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Shell completion files must be updated for bash, zsh, and fish when commands or adapters are added
Files:
completions/gtr.bashcompletions/_git-gtrcompletions/git-gtr.fish
completions/{gtr.bash,_git-gtr,gtr.fish}
📄 CodeRabbit inference engine (.github/instructions/completions.instructions.md)
completions/{gtr.bash,_git-gtr,gtr.fish}: Always update all three completion files (gtr.bash, _git-gtr, gtr.fish) when adding new commands, flags, editors, or AI adapters
Implement command completion in all three completion files to support top-level commands (new, rm, editor, ai, list, etc.) with appropriate tab-completion
Implement flag completion in all three completion files to support command-specific flags (e.g., --from, --force, --editor) with appropriate tab-completion
Implement adapter name completion in all three completion files, listing available editor names (cursor, vscode, zed) and AI tool names (aider, claude, codex) for --editor and --ai flags
Files:
completions/gtr.bashcompletions/_git-gtr
completions/gtr.bash
📄 CodeRabbit inference engine (.github/instructions/completions.instructions.md)
completions/gtr.bash: In completions/gtr.bash, implement command completion using COMPREPLY array and compgen filtering for the current word ($cur)
In completions/gtr.bash, support dynamic branch completion using 'git branch --format='%(refname:short)' and include special ID '1' for main repoUpdate shell completion files when adding new commands or flags:
completions/gtr.bash,completions/_git-gtr, andcompletions/git-gtr.fish
Files:
completions/gtr.bash
**/*.{bash,fish,sh}
📄 CodeRabbit inference engine (.github/instructions/sh.instructions.md)
**/*.{bash,fish,sh}: Bash 3.2+ compatible (macOS default), but 4.0+ features allowed where appropriate
Always quote variables: use"$var"not$var
Use function-scoped variables:local var="value"
Check return codes; functions return 1 on failure
Usesnake_casefor functions and variables,UPPER_CASEfor constants
Prefer[ ]over[[ ]]for POSIX portability; use[[only when needed
Always quote glob inputs; disable unintended globbing withset -ftemporarily if required
Avoid associative arrays in shell scripts; use simple string/loop constructs for Bash 3.2+ compatibility
Avoidreadarrayand process substitution unsupported in older Bash
Debug withbash -x ./bin/gtr <cmd>or wrap suspicious blocks withset -x/set +x
Check function presence withdeclare -f create_worktreeordeclare -f resolve_target
Use stderr for variable inspection:echo "DEBUG var=$var" >&2to keep stdout clean for command substitution
Keep dependencies minimal: only usegit,sed,awk,find,grep; avoid jq/curl unless justified
Check availability of external commands before use when adding new tools
Use"${var}"for variable expansion; for line loops usewhile IFS= read -r line; do ... doneto preserve spaces
Sanitize branch names viasanitize_branch_namefunction; do NOT duplicate logic elsewhere
Everything is sourced at startup withset -eenabled; functions call each other directly; no subshells except for hooks and AI tools
Files:
completions/gtr.bashcompletions/git-gtr.fish
completions/{gtr.bash,_git-gtr,git-gtr.fish}
📄 CodeRabbit inference engine (CLAUDE.md)
completions/{gtr.bash,_git-gtr,git-gtr.fish}: Update completion files (bash, zsh, fish) to include new editor adapter names when adding a new editor adapter
Update completion files (bash, zsh, fish) to include new AI tool names when adding a new AI tool adapter
Files:
completions/gtr.bashcompletions/_git-gtrcompletions/git-gtr.fish
bin/gtr
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
bin/gtr: Dispatch commands throughcmd_*functions inbin/gtr(case block lines 36‑77)
UpdateGTR_VERSIONon line 8 ofbin/gtrwhen releasing; this affectsgtr version/--versionoutputGlobal
set -einbin/gtr: guard non-critical commands with|| true
list --porcelainoutput must remain stable for scripting purposes
bin/gtr: Updatebin/gtrversion constant (GTR_VERSION) when releasing a new version
Update help text inbin/gtrby searching for 'Available editors:' incmd_helpfunction andload_editor_adapterfunction when adding a new editor adapter
Update help text inbin/gtrby searching for 'Available AI tools:' incmd_helpfunction andload_ai_adapterfunction when adding a new AI tool adapter
Files:
bin/gtr
{bin/gtr,lib/**/*.sh,adapters/**/*.sh}
📄 CodeRabbit inference engine (.github/instructions/testing.instructions.md)
{bin/gtr,lib/**/*.sh,adapters/**/*.sh}: All commands must exit 0 (except intentional failures) and produce expected side-effects
No unquoted path errors; spaces must be handled in file paths
Hooks must run only once per creation/removal event
Files:
bin/gtr
completions/_git-gtr
📄 CodeRabbit inference engine (.github/instructions/completions.instructions.md)
completions/_git-gtr: In completions/_git-gtr, use Zsh completion framework with _arguments and _describe/_values for sophisticated completion logic with descriptions and grouping
In completions/_git-gtr, support dynamic branch completion using 'git branch --format='%(refname:short)' and include special ID '1' for main repoUpdate shell completion files when adding new commands or flags:
completions/gtr.bash,completions/_git-gtr, andcompletions/git-gtr.fish
Files:
completions/_git-gtr
completions/git-gtr.fish
📄 CodeRabbit inference engine (CLAUDE.md)
Update shell completion files when adding new commands or flags:
completions/gtr.bash,completions/_git-gtr, andcompletions/git-gtr.fish
Files:
completions/git-gtr.fish
README.md
📄 CodeRabbit inference engine (CLAUDE.md)
README.md: Update README.md with installation/setup instructions when adding a new editor adapter
Update README.md with installation instructions and use cases when adding a new AI tool adapter
Files:
README.md
🧠 Learnings (1)
📚 Learning: 2025-12-29T18:46:36.983Z
Learnt from: helizaga
Repo: coderabbitai/git-worktree-runner PR: 64
File: bin/gtr:746-750
Timestamp: 2025-12-29T18:46:36.983Z
Learning: When error messages reference missing CLI tools (such as gh for GitHub CLI), use platform-agnostic installation guidance by directing users to the official website (e.g., https://cli.github.com/) instead of platform-specific package managers (brew, apt, choco) to ensure the guidance works across all operating systems. Apply this messaging to the bin/gtr script where applicable.
Applied to files:
bin/gtr
🪛 Shellcheck (0.11.0)
completions/gtr.bash
[warning] 62-62: Prefer mapfile or read -a to split command output (or quote to avoid splitting).
(SC2207)
🔇 Additional comments (27)
docs/configuration.md (2)
1-401: Excellent comprehensive documentation!This configuration reference is well-structured, thorough, and provides clear examples for each setting. The organization with a table of contents, cross-references, and practical examples makes it very user-friendly.
66-66: Template file reference is valid.The referenced
templates/.gtrconfig.examplefile exists and contains proper configuration examples for users to reference.docs/troubleshooting.md (2)
1-242: Great troubleshooting resource!This guide provides practical, command-based solutions for common issues. The platform-specific notes, architecture overview, and transparent discussion of limitations are particularly helpful.
231-231: Thegit gtr doctorcommand is properly implemented inbin/gtrwith acmd_doctor()function that performs health checks for git, repository status, editors, and AI tools. The command is registered in all shell completions and documented consistently across the codebase.completions/_git-gtr (1)
53-57: LGTM! Zsh completion updated correctly.The new
--editor/-eand--ai/-aflags are properly added to thenewcommand completion. The implementation is consistent with the other completion files.completions/gtr.bash (1)
62-62: LGTM! Bash completion updated correctly.The new
--editor/-eand--ai/-aflags are properly added to thenewcommand completion.Note: The shellcheck SC2207 warning about using
mapfileinstead of command substitution is a false positive for this use case. Thecompgen | COMPREPLYpattern is the standard idiomatic way to implement bash completions and is used consistently throughout this file.completions/git-gtr.fish (1)
59-60: LGTM! Fish completion updated correctly.The new
--editor/-eand--ai/-aflags are properly added to thenewcommand completion with clear descriptions. All three completion files (bash, zsh, fish) have been updated consistently as required by the coding guidelines.docs/advanced-usage.md (3)
1-7: LGTM!Well-structured documentation with clear navigation links and a comprehensive table of contents. The structure aligns with the new features introduced in this PR.
110-130: LGTM!The CI/CD integration section accurately documents the automation flags available in the CLI, which is helpful for scripting and pipeline integration.
174-200: LGTM!The Parallel AI Development section provides practical guidance for running multiple AI agents on the same feature branch. The workflow tips for avoiding conflicts are valuable.
bin/gtr (6)
124-125: LGTM!Variable initialization follows the existing pattern for boolean flags in the function.
162-169: LGTM!Flag parsing for
--editor/-eand--ai/-afollows the existing patterns in the function. The short flags are intuitive and consistent.
299-311: LGTM!The auto-launch editor logic properly handles the case when no editor is configured by falling back to the file browser. The implementation reuses existing infrastructure (
cfg_default,load_editor_adapter,editor_open).
313-324: LGTM!The auto-launch AI logic appropriately warns when no AI tool is configured (rather than failing hard), providing guidance on how to configure one. This is a sensible UX decision for the shortcut flag.
326-333: LGTM!The conditional "Next steps" block correctly suppresses the manual workflow hints when auto-launch flags are used, keeping the output clean and relevant.
1402-1403: LGTM!Help text accurately documents the new flags with appropriate descriptions. The format is consistent with other options in the help output.
README.md (11)
3-6: LGTM!Badges provide quick visual indicators for license, requirements, and platform support. The version numbers are consistent with the Requirements section.
12-26: LGTM!Table of Contents provides clear navigation and all linked sections are present in the document.
92-94: LGTM!New usage examples clearly demonstrate the
--editorand--aiflags, including the ability to combine them with short flags-e -a.
118-118: LGTM!The comparison table effectively highlights the DX improvement of the new
--editorflag over the manual multi-command approach.
172-173: LGTM!Options documentation for
--editor/-eand--ai/-ais accurate and consistent with the implementation.
270-312: LGTM!The configuration section provides a good balance of quick-start examples while deferring comprehensive documentation to the external reference. The
.gtrconfigexample demonstrates common use cases.
314-339: LGTM!Shell completion setup instructions are practical and cover the three major shells. The reference to external documentation for detailed setup and troubleshooting is appropriate.
341-351: LGTM!Platform support table is clear and informative. The Windows notes appropriately set expectations about Git Bash/WSL requirements.
353-363: LGTM!The advanced usage section appropriately summarizes the available advanced topics and directs readers to the detailed documentation.
365-374: LGTM!Contributing section clearly identifies areas where help is appreciated and appropriately references the project's contribution guidelines and code of conduct.
382-390: LGTM!Clean footer with appropriate license reference and issue link for user support.
- Expanded the list of supported AI tools in README and configuration documentation to include GitHub Copilot. - Updated default AI tool settings to reflect the new options available for users.
1 participant
Pull Request
Description
Motivation
Fixes # (issue)
Type of Change
Testing
Manual Testing Checklist
Tested on:
Core functionality tested:
git gtr new <branch>- Create worktreegit gtr go <branch>- Navigate to worktreegit gtr editor <branch>- Open in editor (if applicable)git gtr ai <branch>- Start AI tool (if applicable)git gtr rm <branch>- Remove worktreegit gtr list- List worktreesgit gtr config- Configuration commands (if applicable)Test Steps
Expected behavior:
Actual behavior:
Breaking Changes
Checklist
Before submitting this PR, please check:
git gtr(production) and./bin/gtr(development)Additional Context
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
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.