Managing multiple branches and external dependencies in Git can sometimes feel like juggling flaming torches 🔥. Fortunately, Git offers powerful tools like worktree and subtree that simplify your workflow, improve collaboration, and reduce the risk of messy merges. In this post, we’ll explore both Git worktree and Git subtree, compare them to more common approaches (including submodules and stashing), and show you why they can transform your development process.

Git Worktree — Efficient Multi-Branch Development without the Hassle

The Challenge: The “Normie” Approach 🥴

When an urgent hotfix is needed, many developers default to a process like this:

  1. Stash Your Work:
git stash save "WIP on feature-A"

You stash uncommitted changes, risking messy conflict resolutions later if the stash isn’t applied cleanly. 😬

  1. Switch Branches:
git checkout main
git checkout -b hotfix

You work on the hotfix in the same directory, then merge back into main and later into your feature branch.

  1. Reapply the Stash:
git checkout feature-A
git merge main
git stash pop

This process can be error-prone and cumbersome.

The Git Worktree Approach: A Better Way 😎

With Git worktree, you can create multiple working directories from a single repository. This means you can work on multiple branches simultaneously without the need for stashing or constant branch switching.

How It Works:

Separate Worktrees for Each Branch:

Imagine you have two feature branches—feature-A and feature-B—and then a hotfix is needed.

# In your main directory, you're on feature-A:
git checkout feature-A

# Worktree for feature-B (created previously):
git worktree add ../feature-B feature-B

# When a hotfix is needed, create a new worktree directly from main (no new clone required):
git worktree add ../hotfix hotfix -b hotfix
Parallel Development Without Clones:

Each branch gets its own directory:

  • Directory 1: feature-A (main worktree)
  • Directory 2: feature-B (existing worktree)
  • Directory 3: hotfix (new worktree created from main)
Work Independently:

In the hotfix directory, copy over essential changes from feature-A and feature-B if needed, then commit and push:

# In the ../hotfix directory:
git add .
git commit -m "Hotfix: Apply critical fix with enhancements from feature-A & feature-B"
git push origin hotfix
Merge and Update:

After merging the hotfix into main, update your feature branches in their respective worktrees:

# For feature-A:
git checkout feature-A
git merge main
git push origin feature-A

# For feature-B:
cd ../feature-B
git checkout feature-B
git merge main
git push origin feature-B

Benefits:

  • No need for multiple clones: Avoids the cumbersome process of re-cloning the repository.
  • Reduced risk: No stashing means less risk of losing uncommitted work.
  • Parallel workflows: Seamless branch updates without interrupting ongoing development.

Git Subtree — Unified Dependency Management Made Easy 📂

The Traditional Alternative: Git Submodules

Many projects use submodules to manage external dependencies. However, submodules can be tricky:

  • Extra Commands: After cloning, you need to run additional commands (git submodule update --init --recursive).
  • Separate Repositories: They require managing multiple repositories and can lead to version mismatches.
  • Configuration Overhead: More setup is needed for team members and CI/CD pipelines.

Why Git Subtree is Superior ✨

Git subtree integrates an external repository directly into a subdirectory of your main repo. Here’s why it’s often preferred:

Unified Codebase 📂🤝:

  • The entire project, including the external dependency, lives in one repository.
  • Benefit: Cloning and building the project is simpler—no extra steps required.

Simplified Dependency Management 🔄✅:

  • External code is merged into your main repo’s history, so you can update it with straightforward subtree commands.
  • Benefit: Changes are part of your regular commit history, making tracking and merging easier.
  # Add an external library:
  git subtree add --prefix=lib/external-library https://github.com/example/external-library.git main --squash

  # Update it later:
  git subtree pull --prefix=lib/external-library https://github.com/example/external-library.git main --squash

Trade-Off: Repository Size 📈💾

  • Yes, integrating external repos this way can significantly increase your main repo’s size. However, for many teams, the simplicity and unified workflow outweigh the extra disk space used.
  • Benefit: Easier onboarding, fewer configuration headaches, and a more maintainable history.

Conclusion 🎉

By leveraging Git worktree and Git subtree, you can simplify multi-branch development and manage external dependencies more efficiently:

  • Git Worktree enables parallel branch development without the need for stashing or multiple clones, keeping your work organized and reducing the risk of lost code.
  • Git Subtree offers a unified approach to dependency management, avoiding the complexity of submodules—even if it means a larger repository.

Together, these tools help you maintain a clean, agile, and highly collaborative Git workflow. Whether you’re addressing urgent hotfixes or integrating external libraries, these strategies keep you in control and your codebase in top shape.