Troubleshooting

Common issues and solutions when using GWTree

Not in a Git Repository

Error: “Not in a git repository”

This error occurs when you run gwt commands outside of a git repository.

Solution:

1. Navigate to a directory inside a git repository:

   cd /path/to/your/repo
   

2. Verify you’re in a git repository:

   git status
   

3. If the directory isn’t a git repository, initialize one:

   git init
   

Directory Already Exists

Error: “Directory already exists: /path/to/worktree”

This happens when trying to create a worktree with a name that already exists in the parent directory.

Solution:

1. Choose a different worktree name:

   gwt feature-login-v2
   

2. Or remove the existing directory first:

   gwt rm  # Use interactive removal
   

3. Check existing worktrees:

   gwt ls
   

Merge Conflicts

Error: “Merge failed. Resolve conflicts manually.”

This occurs when using gwt merge and there are conflicts between branches.

Solution:

1. The merge command will fail and leave you in the main branch with conflicts:

   git status  # See conflicting files
   

2. Resolve conflicts manually in your editor

3. Stage the resolved files:

   git add .
   

4. Complete the merge:

   git commit
   

5. Manually remove the worktree:

   gwt rm
   

Uncommitted Changes

When creating a new worktree, GWTree detects uncommitted changes and prompts you to handle them.

Options:

1. Stash changes (recommended):

   • Select “Stash changes” when prompted
   • Your changes are saved and can be recovered with git stash pop

2. Ignore and continue:

   • Select “Ignore and continue”
   • Changes remain in the current worktree

3. Cancel:

   • Select “Cancel” to abort worktree creation

Pull/Rebase Failures

Error: “Pull failed” during worktree creation

This can happen when pulling latest changes from remote fails.

Common causes:

1. No network connection: Ensure you’re connected to the internet
2. Diverged branches: Local and remote have different histories
3. No remote configured: Repository doesn’t have a remote origin

Solution:

# Check remote configuration
git remote -v

# Add remote if missing
git remote add origin <url>

# Manually pull and resolve
git pull --rebase origin main

Worktree Already Registered

Error: “worktree registered but missing”

This happens when git has a worktree registered but the directory was manually deleted.

Solution:

1. Prune stale worktree references:

   git worktree prune
   

2. Try creating the worktree again:

   gwt feature-name
   

Editor Not Opening

Worktree created successfully but editor didn’t open

Possible causes:

1. Editor not installed: Ensure VS Code or Cursor is installed
2. Command not in PATH: The editor command isn’t available
3. Wrong configuration: Editor setting in config doesn’t match your setup

Solution:

1. Check your editor configuration:

   gwt config
   

2. Update editor setting to one of: code, cursor, default, or none

3. Verify the editor command works:

   code --version  # For VS Code
   cursor --version  # For Cursor
   

4. Skip editor opening with -x flag:

   gwt feature-name -x
   

Dependency Installation Failed

Error: “failed to install” after creating worktree

This happens when automatic dependency installation fails.

Solution:

1. Navigate to the worktree:

   cd ../repo-name
   

2. Manually install dependencies:

   pnpm install  # or npm/yarn/bun
   

3. Or disable automatic installation:

   gwt config
   # Set installDeps to false
   

Branch Name Conflicts

GWTree automatically handles branch name conflicts by appending -1, -2, etc.

If you want separate worktree and branch names:

1. Press ESC when prompted for “Worktree & branch name:”
2. Enter different names for worktree and branch

Cannot Merge with Uncommitted Changes

Error: “Worktree has uncommitted changes. Commit or stash them first.”

The gwt merge command requires a clean working directory.

Solution:

1. Navigate to the worktree:

   cd ../repo-feature
   

2. Commit your changes:

   git add .
   git commit -m "Your message"
   

3. Or stash them:

   git stash
   

4. Try merging again:

   gwt merge feature
   

Node Version Issues

Error: Node version compatibility issues

GWTree requires Node.js 18.0.0 or higher.

Solution:

1. Check your Node version:

   node --version
   

2. Upgrade Node.js:

   • Using nvm: nvm install 18
   • Using fnm: fnm install 18
   • Download from nodejs.org

Getting Help

If you encounter issues not covered here:

1. Check existing issues: github.com/ahmadawais/gwtree/issues
2. Create a new issue with:
   • Error message
   • Steps to reproduce
   • gwt --version output
   • Operating system