Feature Development Workflow

Complete workflow for developing features with git worktrees

Git worktrees revolutionize feature development by giving each feature its own isolated directory. Work on multiple features simultaneously without branch switching, stashing, or context loss.

The Problem with Traditional Workflow

Traditional git workflow forces you to:

• Switch branches constantly
• Stash uncommitted changes
• Lose IDE context and open files
• Reinstall dependencies after switching
• Close and reopen terminals

Worktrees solve all of this.

Feature Development Flow

1. Start a new feature

   Create a worktree for your feature:

   gwt feature-login
   

   This creates:

   • A new branch: feature-login
   • A new directory: repo-feature-login/
   • Pulls latest from main automatically

   Your editor opens automatically (VS Code or Cursor based on your config).

2. Develop in isolation

   Work normally in the worktree:

   cd repo-feature-login
   npm install  # Dependencies specific to this worktree
   npm run dev  # Run dev server
   

   Make changes, commit as you go:

   git add .
   git commit -m "Add login form validation"
   
3. Switch to another feature

   Need to work on something else? Just create another worktree:

   gwt hotfix-payment-bug -x
   

   The -x flag skips opening an editor. Your first feature stays untouched:

   • All files exactly as you left them
   • Dev server still running
   • No stashing needed
4. Check status across features

   View progress on all your features:

   gwt status
   

   Output shows:

   • Uncommitted changes in each worktree
   • Commits ahead/behind main
   • Merge status
5. Complete and merge

   When your feature is ready:

   # Push your branch
   cd repo-feature-login
   git push origin feature-login
   
   # Create a PR (optional)
   gh pr create --fill
   
   # After PR is approved, merge and cleanup
   gwt merge feature-login
   

   The merge command handles everything:

   • Switches to main
   • Merges the branch
   • Removes the worktree
   • Deletes the local branch

Common Scenarios

Multiple Related Features

Work on related features in parallel:

gwt user-auth user-profile user-settings -x

Develop all three simultaneously, test interactions between them.

Feature + Hotfix

Feature work interrupted by urgent bug:

# Already working in repo-feature-login
# Create hotfix without disrupting feature
gwt hotfix-critical -x
cd repo-hotfix-critical
# Fix bug, test, commit
git push origin hotfix-critical
gwt merge hotfix-critical
# Return to feature work
cd repo-feature-login

Your feature work remains untouched.

Long-Running Features

Keep long-running feature branches fresh:

cd repo-big-feature
git fetch origin
git rebase origin/main
npm install  # Update dependencies
npm test     # Ensure tests still pass

Experimental Work

Try risky changes without fear:

gwt experiment-new-architecture -x
cd repo-experiment-new-architecture
# Make experimental changes
# If it works, keep it
# If not, just delete the worktree
gwt rm

Fast Creation Modes

Quick Mode

Create worktree with a single name:

GWT feature-login  # Creates repo-feature-login with feature-login branch

Fast Mode (Skip Prompts)

Use -y to skip all prompts and use saved defaults:

gwt feature-dashboard -y

Batch Mode

Create multiple worktrees at once:

gwt auth api dashboard tests -x

Ultra-Fast Mode

Combine flags for instant creation:

GWT_EDITOR=none gwt auth api dashboard -y

Configuration Tips

Set your preferred editor globally:

gwt config

Options:

• code - VS Code
• cursor - Cursor
• none - Don’t open editor
• default - System default

Config stored in ~/.config/gwtree/config.json:

{
  "editor": "cursor",
  "installDeps": true,
  "lastPm": "npm"
}

Cleaning Up

Remove merged features

Clean up features that have been merged to main:

gwt clean

Safely removes only merged worktrees.

Remove all worktrees

Start fresh by removing all worktrees:

gwt clean --all

Use with caution - removes all worktrees including unmerged work.

Remove specific worktree

Interactive search and remove:

gwt rm

Select the worktree to remove from a list.

List all worktrees

See all your worktrees:

gwt ls

Best Practices

Keep main worktree clean - Use the main repository directory for quick checks and worktree management only.

Name worktrees descriptively - Use clear names like feature-user-auth or fix-payment-bug so you know what each worktree contains.

Don’t nest worktrees - Create all worktrees as siblings to your main repository, not inside it.

Troubleshooting

Port already in use

Each worktree can run its own dev server on a different port:

# Worktree 1
cd repo-feature-a
PORT=3000 npm run dev

# Worktree 2  
cd repo-feature-b
PORT=3001 npm run dev

Dependencies out of sync

Each worktree has its own node_modules:

cd repo-feature-login
rm -rf node_modules
npm install

Merge conflicts

If you encounter conflicts when merging:

cd repo-feature-login
git fetch origin
git rebase origin/main
# Resolve conflicts
git add .
git rebase --continue

Next Steps

Parallel Agents

Run multiple AI agents simultaneously on different features.

Code Review

Review PRs without disrupting your current work.