Efficient Git Worktree Usage in VS Code

The latest Visual Studio Code release (1.103) includes support for Git worktrees, allowing developers to manage multiple branches more efficiently. If you're new to Git worktrees, this guide will help you get started and make the most of this feature in your workflow.

What are Git Worktrees?

Git worktrees allow you to have multiple working directories associated with a single Git repository. This is particularly useful for working on multiple branches simultaneously without the need to constantly switch between them. For example, you no longer need to stash your changes just to switch branches and apply a quick fix elsewhere.

Setting Up Git Worktrees in VS Code

To get started, organize your project directory to keep worktrees clear and manageable. A common pattern is:

my-awesome-app/
    main/        # main repository clone
    feature-x/   # worktree for 'feature-x' branch
    bugfix-y/    # worktree for 'bugfix-y' branch

Create a Worktree for an Existing Branch
Open a terminal in VS Code, navigate to your main repository directory, and run:

git worktree add ../feature-xxx feature/xxx

Replace feature-xxx with your branch name. This command creates a new directory for the branch and checks it out, so you can work on it independently. The worktree directory is created relative to the main worktree as a sibling directory.

Create a Worktree and New Branch Simultaneously
To quickly start a hotfix or feature without losing your current changes, create a new branch and worktree in one step:

git worktree add -b feature-xxx ../feature-xxx

This creates both the branch (feature-xxx) and its worktree. The -b flag specifies that a new branch should be created and checked out.

Open and Manage Worktrees in VS Code
Open each worktree in a separate VS Code window. You can do this from the integrated terminal or via the source control pane menu:

Each worktree has its own Git state, so you can commit, push, and pull independently. Switch between worktrees by opening the relevant folder in a new window.

Tip: Use clear, descriptive names for your worktree directories. VS Code’s window title reflects the folder name, making it easy to track multiple branches.

Remove a Worktree When Finished
To clean up, remove a worktree with:

git worktree remove ../feature-xxx

Benefits of Using Git Worktrees

• Parallel Development: Work on multiple features or bug fixes simultaneously without the overhead of switching branches.
• Reduced Context Switching: Keep your work organized by separating different tasks into their own worktrees.
• Easier Testing: Test changes in isolation by using worktrees for different branches or versions of your code.

Conclusion

Git worktrees are a powerful feature that can significantly improve your workflow in Visual Studio Code. By allowing you to work on multiple branches simultaneously, they help you stay organized and focused on your tasks. Give them a try in your next project!

Troubleshooting and Common Pitfalls

• Do not delete worktree directories manually: Always use git worktree remove <path> to clean up worktrees. Manually deleting the folder can leave your repository in an inconsistent state.
• Further reading: See the official VS Code documentation on worktree support for more details and advanced usage.