Using Git Worktrees

using-git-worktrees skill for programming & development

Category: development Source: obra

Switching git branches disrupts work-in-progress, requires stashing changes, and causes context switching overhead. Git worktrees enable multiple working directories from one repository, allowing parallel work on different branches, isolated experimentation, and seamless context switching without disrupting current work.

What Is This?

Overview

Using Git Worktrees guides effective use of git worktree feature for managing multiple working directories from single repository. It covers worktree creation for different branches, directory organization and naming conventions, switching between worktrees seamlessly, cleanup and removal processes, integration with development workflows, and common patterns for feature development, bug fixes, and experimentation.

Worktrees create separate directories for different branches sharing git repository data. This enables working on feature branch while main development continues in another worktree, fixing bugs without stashing current work, experimenting in isolated environments, and maintaining separate build outputs per branch.

This eliminates branch switching overhead, enables parallel development on multiple branches, maintains separate environments for different work, and streamlines workflows requiring frequent branch changes.

Who Should Use This

Developers working on multiple features simultaneously. Engineers needing isolated testing environments. Teams with frequent hotfix requirements. Anyone frustrated with branch switching overhead. Developers wanting parallel development workflows.

Why Use It?

Problems It Solves

Branch switching disrupts work-in-progress requiring stashing. Worktrees eliminate switching by maintaining separate directories per branch.

Context switching between features wastes time. Separate worktrees maintain context for each branch without switching.

Testing changes requires clean environment. Isolated worktrees provide separate environments per branch.

Dependency conflicts between branches cause issues. Separate worktrees have independent node_modules or build artifacts.

Core Highlights

Multiple working directories from single repository. Parallel work on different branches. Isolated environments per branch. No branch switching overhead. Seamless context preservation. Independent build artifacts. Clean testing environments. Efficient hotfix workflows.

How to Use It?

Basic Usage

Create worktrees for different branches, work in separate directories, remove when done.

Create worktree for feature branch
Work in feature directory
Switch to main worktree for hotfix
Return to feature worktree
Remove worktree when complete

Specific Scenarios

For feature development:

git worktree add ../feature-auth feature-auth
cd ../feature-auth
Work on authentication feature
Meanwhile main worktree continues main development

For hotfixes:

git worktree add ../hotfix-payment hotfix-payment
cd ../hotfix-payment
Fix production issue
Push fix
Remove worktree

For experimentation:

git worktree add ../experiment-refactor experiment
Try refactoring approach
If successful, merge
If not, remove worktree

Real-World Examples

A developer works on complex authentication feature in one worktree. Production bug requires immediate hotfix. Rather than stashing feature work, they create hotfix worktree from main branch, fix bug, test in isolated environment, deploy, and return to feature work seamlessly. No context loss or branch switching overhead.

A team needs to test feature branch integration with main branch changes. They create worktree from main, another from feature, and third for integration testing. Each environment has independent node_modules avoiding dependency conflicts. Testing proceeds smoothly with clear separation.

An engineer experiments with architectural refactoring not sure if approach will work. They create experiment worktree, try refactoring, realize approach has issues, and remove worktree cleanly. Main development continues unaffected by failed experiment.

Advanced Tips

Organize worktrees in consistent directory structure (../repo-feature-name). Name worktrees clearly indicating branch and purpose. Remove worktrees promptly when done to avoid clutter. Use worktrees for long-running feature branches. Create hotfix worktrees from production branch. Maintain one main worktree for primary development. Script common worktree operations for efficiency. Configure IDE to work with multiple worktrees.

When to Use It?

Use Cases

Parallel feature development. Hotfix workflows while feature work continues. Experimental branches for trying approaches. Isolated testing environments. Review workflows needing separate environment. Build artifact separation per branch. Context switching reduction.

Important Notes

Requirements

Git version 2.5 or higher. Filesystem space for multiple working directories. Understanding of git branches and repositories. IDE support for multiple directories. Discipline to remove unused worktrees.

Usage Recommendations

Create worktrees in consistent directory structure outside main repo. Name worktrees descriptively. Remove worktrees promptly when done. Use for long-running branches not quick fixes. Maintain one primary worktree for main development. Configure IDE workspace for multiple worktrees. Script common operations. Document worktree conventions for team.

Limitations

Disk space required for multiple directories. Each worktree needs own dependencies installation. IDE support varies. Can create directory clutter if not managed. Requires git 2.5+. Some git operations affect all worktrees. Learning curve for effective usage.