Add `git gtr copy` command for syncing files between worktrees

[b-barry]

Problem

When working with multiple worktrees, developers often need to sync configuration files (especially .env files) from the main repo to worktrees after they've been created.

Current workflow requires manual commands:

cd /path/to/main-repo && find . -name ".env*" -type f -exec sh -c \
  'mkdir -p "/path/to/worktree/$(dirname "$1")" && cp "$1" "/path/to/worktree/$1"' _ {} \;

This is verbose, error-prone, and breaks the DX that gtr provides.

Proposed Solution

Add a git gtr copy command:

git gtr copy 1 my-feature --pattern ".env*"

This would copy all matching files from the main repo to the worktree while preserving directory structure.

Use Cases

• Created a worktree with --no-copy but now need env files
• Updated .env in main and need to propagate to existing worktrees
• Selective sync without running full postCreate hooks

[aravindputrevu]

@coderabbitai plan

[coderabbitai]

Implementation Plan

Approach

Add a git gtr copy command to sync files between worktrees using pattern matching, enabling developers to selectively copy configuration files (like .env files) from one worktree to another after creation.

Observations

The gtr tool is a bash-based git worktree manager with a command dispatcher pattern in bin/gtr that routes subcommands to cmd_*() functions. Commands parse arguments using case statements, validate worktrees with resolve_target(), and handle errors via log_error(). The codebase has existing file copying infrastructure in lib/copy.sh with copy_patterns() supporting glob pattern matching, include/exclude filtering, and directory structure preservation. Shell completions exist for Bash, Fish, and Zsh, and configuration is managed through git config with support for multi-valued keys.

Assumptions

Assumption 1: Pattern Specification Approach

Options Considered:

• Require at least one --pattern flag (fail if none specified)
• Fall back to configured gtr.copy.include patterns when no flags provided
• Default to copying nothing with a warning

Chosen Option: Fall back to configured gtr.copy.include patterns when no flags provided

Rationale: This provides flexibility for both one-off operations (explicit patterns) and regular usage (leveraging existing configuration), aligning with the workflow where users may want to sync the same files that would normally copy during worktree creation. When --pattern is specified, only those patterns are used; when omitted, the command uses configured patterns, making both ad-hoc and configured workflows natural.

Assumption 2: Exclude Pattern Handling

Options Considered:

• Support --exclude <pattern> flag for command-line exclusions
• Only use configured gtr.copy.exclude patterns
• No exclude support at all

Chosen Option: Only use configured gtr.copy.exclude patterns

Rationale: Always apply configured exclude patterns from gtr.copy.exclude, with no command-line override. This provides a safety mechanism to prevent copying sensitive or unwanted files (like .env.local or backup files) regardless of include patterns specified. The configured excludes act as a protective layer rather than a preference, ensuring developers don't accidentally copy files they've intentionally excluded in their configuration.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Plan

Phase 1: Core Command Implementation

Implement the copy command handler with argument parsing, worktree resolution, and pattern handling that integrates with the existing copy infrastructure.

Task 1: Add Command Dispatcher Entry

Add the new copy subcommand to the main command dispatcher in bin/gtr.

• Locate the main case statement (around lines 62-107) that dispatches commands to handler functions
• Add a copy) case entry that routes to cmd_copy function
• Follow the existing pattern used by other two-identifier commands like cmd_go and cmd_remove

Task 2: Implement cmd_copy() Function

Create the main command handler function in bin/gtr that accepts source and target identifiers with optional pattern flags.

• Create cmd_copy() function following the structure of cmd_create() and cmd_go()
• Parse arguments using while [ $# -gt 0 ]; case "$1" pattern to handle:
  • Two positional arguments: source identifier and target identifier
  • --pattern <glob> flag (can be specified multiple times, accumulate into newline-separated list)
  • Unknown flags should log error and exit
• Validate that both source and target identifiers are provided; log usage error if missing
• Collect patterns into a variable (newline-separated if multiple --pattern flags)
• If no --pattern flags provided, retrieve patterns from config using cfg_get_all "gtr.copy.include"
• If neither patterns nor config exists, log error with helpful message suggesting user specify patterns or configure defaults
• Include inline usage message: log_error "Usage: git gtr copy <source-id> <target-id> [--pattern <glob>]..."

Task 3: Resolve Worktree Paths

Validate and resolve both source and target identifiers to worktree paths using existing resolution functions.

• Call discover_repo_root to get repository root
• Call resolve_base_dir to get worktree base directory and prefix
• Call resolve_target() for source identifier, extract path from tab-separated output
• Call resolve_target() for target identifier, extract path from tab-separated output
• Both resolve_target() calls should use || exit 1 pattern to fail fast if resolution fails
• Extract worktree_path from the tab-separated output (field 2) for both source and target

Task 4: Execute Copy Operation

Invoke the existing copy_patterns() function with resolved paths and pattern configurations.

• Retrieve exclude patterns from config using cfg_get_all "gtr.copy.exclude"
• Call copy_patterns() from lib/copy.sh with:
  • Source root: resolved source worktree path
  • Destination root: resolved target worktree path
  • Include patterns: accumulated patterns from flags or config
  • Exclude patterns: retrieved from config
  • Preserve paths: "true" to maintain directory structure
• Log informational message before copying (e.g., "Copying files from to ...")
• Note that copy_patterns() always returns 0 even on partial failures; it logs warnings for individual failures
• Log success message after completion (e.g., "Copy complete")

🤖 Prompt for AI agents

Implement the `git gtr copy` command to sync files between worktrees using
pattern matching.

In `bin/gtr`:
- Add `copy)` case entry in the main dispatcher that routes to `cmd_copy`
- Create `cmd_copy()` function that:
- Parses arguments: two positional identifiers (source, target) and optional
`--pattern <glob>` flags (can repeat)
  - Validates both identifiers are provided
  - Accumulates patterns from `--pattern` flags into newline-separated list
  - Falls back to `cfg_get_all "gtr.copy.include"` if no patterns specified
  - Errors if neither patterns nor config exists
- Resolves source and target identifiers to worktree paths using
`resolve_target()`
  - Retrieves exclude patterns from `cfg_get_all "gtr.copy.exclude"`
- Calls `copy_patterns()` with source path, target path, include patterns,
exclude patterns, and preserve=true
  - Logs informational messages before and after copy operation

Phase 2: Shell Integration and Documentation

Update shell completions and help documentation to expose the new command to users across different shell environments.

Task 1: Update Bash Completion

Add copy command completion support in completions/gtr.bash.

• Add copy to the subcommand list (around line 25 in the completion function)
• Add case handler for copy command in the position-based completion logic
• At position 3 (first identifier after "copy"), enable worktree identifier completion
• At position 4 (second identifier after source), enable worktree identifier completion
• Follow the pattern used by go|run|editor|ai|rm commands for branch/identifier completion
• Add --pattern to available flags for the copy command

Task 2: Update Fish Completion

Add copy command completion support in completions/gtr.fish.

• Add a new complete command registration for the copy subcommand
• Use format: complete -f -c git -n '__fish_git_gtr_needs_command' -a copy -d 'Copy files between worktrees'
• Add completion for --pattern flag using complete -f -c git -n '__fish_git_gtr_using_command copy' -l pattern -d 'Pattern to match files'
• Add worktree identifier completions for positions 3 and 4 using helper function __gtr_worktree_branches
• Follow existing patterns for other commands with similar argument structures

Task 3: Update Zsh Completion

Add copy command completion support in completions/_git-gtr.

• Add 'copy:Copy files between worktrees' to the commands array (around lines 18-33)
• Add case handler for copy in the CURRENT >= 4 section
• Use _arguments to specify argument structure and flag options
• Enable identifier completion for both source and target positions
• Add --pattern flag with appropriate description
• Follow the pattern used by other two-identifier commands in the completion script

🤖 Prompt for AI agents

Update shell completions for the new `copy` command across Bash, Fish, and Zsh.

In `completions/gtr.bash`:
- Add `copy` to subcommand list
- Add case handler for `copy` with worktree identifier completion at positions 3
and 4
- Add `--pattern` flag completion

In `completions/gtr.fish`:
- Add `complete` registration for `copy` subcommand with description
- Add `--pattern` flag completion
- Add worktree identifier completions using `__gtr_worktree_branches`

In `completions/_git-gtr`:
- Add `'copy:Copy files between worktrees'` to commands array
- Add case handler with `_arguments` for source/target identifiers and
`--pattern` flag

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the `git gtr copy` command to sync files between worktrees using
pattern matching.

In `bin/gtr`:
- Add `copy)` case entry in the main dispatcher that routes to `cmd_copy`
- Create `cmd_copy()` function that:
- Parses arguments: two positional identifiers (source, target) and optional
`--pattern <glob>` flags (can repeat)
  - Validates both identifiers are provided
  - Accumulates patterns from `--pattern` flags into newline-separated list
  - Falls back to `cfg_get_all "gtr.copy.include"` if no patterns specified
  - Errors if neither patterns nor config exists
- Resolves source and target identifiers to worktree paths using
`resolve_target()`
  - Retrieves exclude patterns from `cfg_get_all "gtr.copy.exclude"`
- Calls `copy_patterns()` with source path, target path, include patterns,
exclude patterns, and preserve=true
  - Logs informational messages before and after copy operation
===============================================================================

Task: 2

Update shell completions for the new `copy` command across Bash, Fish, and Zsh.

In `completions/gtr.bash`:
- Add `copy` to subcommand list
- Add case handler for `copy` with worktree identifier completion at positions 3
and 4
- Add `--pattern` flag completion

In `completions/gtr.fish`:
- Add `complete` registration for `copy` subcommand with description
- Add `--pattern` flag completion
- Add worktree identifier completions using `__gtr_worktree_branches`

In `completions/_git-gtr`:
- Add `'copy:Copy files between worktrees'` to commands array
- Add case handler with `_arguments` for source/target identifiers and
`--pattern` flag

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.