Skip to content

Working with Git Worktrees

Home › Tutorials › Core Workflows › Working With Worktrees

Status: Placeholder - Content coming soon

Prerequisites: Building and Testing Changes, Git fundamentals

Planned Content

This tutorial teaches you how to use git worktrees for parallel development, enabling you to work on multiple features simultaneously without context switching or branch management overhead.

What You'll Learn

  • Understand git worktrees and their benefits
  • Create isolated feature workspaces with r2r work create
  • Work independently in separate worktrees
  • Make commits with AI-generated messages
  • Sync with main branch using r2r work pull
  • Merge changes back with squash
  • Clean up worktrees when done

Tutorial Structure

  1. Understanding worktrees
  2. What are git worktrees?
  3. Benefits: parallel work, no context switching, independent state

  4. Use cases: multiple features, experimentation, code review

  5. Create a feature workspace

  6. Create worktree: r2r work create my-feature
  7. Understand directory structure
  8. Navigate to worktree: cd ../worktrees/my-feature

  9. List all workspaces: r2r show workspaces

  10. Work independently

  11. Make changes in your worktree
  12. Build and test as usual
  13. No impact on main working directory

  14. Switch between worktrees freely

  15. Making commits

  16. Stage changes: git add .
  17. AI-generated commit: r2r work commit
  18. Or manual commit: git commit -m "..."

  19. View commit history

  20. Syncing with main

  21. Pull latest changes: r2r work pull (rebase on main)
  22. Resolve conflicts if any

  23. Keep your topic branch up to date

  24. Merging back to main

  25. Create PR: r2r create pr (AI-generated description)
  26. After approval, merge: r2r work merge (squash by default)

  27. Understand squash vs. merge strategies

  28. Cleanup

  29. Remove worktree: r2r work remove my-feature
  30. Option to delete branch: r2r work remove my-feature --delete-branch
  31. Clean up stale worktrees

Example Workflow

The tutorial will demonstrate a realistic parallel development scenario:

Main working directory: - Working on feature A (dashboard improvements)

Worktree 1 (../worktrees/api-auth): - Working on feature B (API authentication)

Worktree 2 (../worktrees/fix-bug-123): - Working on urgent bugfix

You can: - Switch between workspaces instantly (just cd) - Build and test independently - Commit to different branches simultaneously - No stashing or branch switching required

Key Commands

# Create workspace
r2r work create my-feature

# Navigate to workspace
cd ../worktrees/my-feature

# Work as usual
# ... make changes ...

# Commit with AI
r2r work commit

# Sync with main
r2r work pull

# Go back to main directory
cd ../../cli

# Create PR
cd ../worktrees/my-feature
r2r create pr

# After merge, clean up
r2r work remove my-feature --delete-branch

Key Concepts Covered

  • Git worktrees and their advantages
  • Parallel feature development
  • AI-generated commit messages
  • Keeping topic branches synchronized
  • Pull request workflow
  • Workspace lifecycle management

Multi-Worktree Awareness

Important considerations when using worktrees:

  • Each worktree is independent (files, branches, index)
  • Claude Code sessions can run in parallel (one per worktree)
  • User coordinates git operations across worktrees
  • .git/worktrees/ contains worktree metadata
  • Some git operations affect all worktrees (tags, config)

Best Practices

  • Use worktrees for features that take multiple sessions
  • Keep worktree names descriptive and short
  • Clean up merged worktrees promptly
  • Use r2r show workspaces to track active workspaces
  • Sync with main regularly to avoid large conflicts

Troubleshooting

Common issues and solutions:

  • Worktree already exists: Use unique names or remove old worktree
  • Branch conflicts: Use r2r work pull to sync with main
  • Stale worktrees: Clean up with r2r work remove

Next Steps

After completing this tutorial, you'll be able to work on multiple features in parallel. Continue to Making Your First Release to learn how to prepare and release modules.

Tutorials | How-to Guides | Explanation | Reference

You are here: Tutorials — learning-oriented guides that take you through steps to complete a project.