/git-worktree

name: git-worktree
description: Manage Git worktrees in project-level ../.zcf/project-name/ directory with smart defaults, IDE integration and content migration
disable-model-invocation: true
allowed-tools: Read(**), Exec(git worktree add, git worktree list, git worktree remove, git worktree prune, git branch, git checkout, git rev-parse, git stash, git cp, detect-ide, open-ide, which, command, basename, dirname)

Claude Command: Git Worktree

Manage Git worktrees with smart defaults, IDE integration and content migration in structured `../.zcf/project-name/` paths.

Execute commands directly and provide concise results.

---

Usage

# Basic operations
/git-worktree add <path>                           # create new branch named <path> from main/master
/git-worktree add <path> -b <branch>               # create new branch with specified name
/git-worktree add <path> -o                        # create and open directly in IDE
/git-worktree list                                 # show all worktree status
/git-worktree remove <path>                        # remove specified worktree
/git-worktree prune                                # clean invalid worktree references

# Content migration
/git-worktree migrate <target> --from <source>     # migrate uncommitted content
/git-worktree migrate <target> --stash             # migrate stash content

Options

| Option | Description | | ------------------ | ------------------------------------------------------ | | `add [<path>]` | Add new worktree in `../.zcf/project-name/<path>` | | `migrate <target>` | Migrate content to specified worktree | | `list` | List all worktrees and their status | | `remove <path>` | Remove worktree at specified path | | `prune` | Clean invalid worktree references | | `-b <branch>` | Create new branch and checkout to worktree | | `-o, --open` | Open directly in IDE after creation (skip prompt) | | `--from <source>` | Specify migration source path (migrate only) | | `--stash` | Migrate current stash content (migrate only) | | `--track` | Set new branch to track corresponding remote branch | | `--guess-remote` | Auto guess remote branch for tracking | | `--detach` | Create detached HEAD worktree | | `--checkout` | Checkout immediately after creation (default behavior) | | `--lock` | Lock worktree after creation |

---

What This Command Does

1. **Environment Check**

• Verify Git repository using `git rev-parse --is-inside-work-tree`
• Detect whether in main repo or existing worktree for smart path calculation

2. **Smart Path Management**

• Auto-calculate project name from main repository path using worktree detection
• Create worktrees in structured `../.zcf/project-name/<path>` directory
• Handle both main repo and worktree execution contexts correctly

# Core path calculation logic for worktree detection
get_main_repo_path() {
  local git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)
  local current_toplevel=$(git rev-parse --show-toplevel 2>/dev/null)

  # Check if in worktree
  if [[ "$git_common_dir" != "$current_toplevel/.git" ]]; then
    # In worktree, derive main repo path from git-common-dir
    dirname "$git_common_dir"
  else
    # In main repository
    echo "$current_toplevel"
  fi
}

MAIN_REPO_PATH=$(get_main_repo_path)
PROJECT_NAME=$(basename "$MAIN_REPO_PATH")
WORKTREE_BASE="$MAIN_REPO_PATH/../.zcf/$PROJECT_NAME"

# Always use absolute path to prevent nesting issues
ABSOLUTE_WORKTREE_PATH="$WORKTREE_BASE/<path>"

**Critical Fix**: Always use absolute paths when creating worktrees from within existing worktrees to prevent path nesting issues like `../.zcf/project/.zcf/project/path`.

3. **Worktree Operations**

• **add**: Create new worktree with smart branch/path defaults
• **list**: Display all worktrees with branches and status
• **remove**: Safely remove worktree and clean references
• **prune**: Clean orphaned worktree records

4. **Smart Defaults**

• **Branch creation**: When no `-b` specified, create new branch using path name
• **Base branch**: New branches created from main/master branch
• **Path resolution**: Use branch name as path when unspecified
• **IDE integration**: Auto-detect and prompt for IDE opening

5. **Content Migration**

• Migrate uncommitted changes between worktrees
• Apply stash content to target worktree
• Safety checks to prevent conflicts

6. **Safety Features**

• **Path conflict prevention**: Check for existing directories before creation
• **Branch checkout validation**: Ensure branches aren't already in use
• **Absolute path enforcement**: Prevent nested `.zcf` directories when in worktree
• **Auto-cleanup on removal**: Clean both directory and git references
• **Clear status reporting**: Display worktree locations and branch status

7. **Environment File Handling**

• **Auto-detection**: Scan `.gitignore` for environment variable file patterns
• **Smart copying**: Copy `.env` and `.env.*` files that are listed in `.gitignore`
• **Exclusion logic**: Skip `.env.example` and other template files
• **Permission preservation**: Maintain original file permissions and timestamps
• **User feedback**: Provide clear status on copied environment files

# Environment file copying implementation
copy_environment_files() {
    local main_repo="$MAIN_REPO_PATH"
    local target_worktree="$ABSOLUTE_WORKTREE_PATH"
    local gitignore_file="$main_repo/.gitignore"
    
    # Check if .gitignore exists
    if [[ ! -f "$gitignore_file" ]]; then
        return 0
    fi
    
    local copied_count=0
    
    # Detect .env file
    if