Use `git worktree` for Hotfixes: A Better Alternative to Stash
We have all been there: you are deep in the zone, half-way through building a complex new feature, and your terminal is full of uncommitted changes. Suddenly, you get a message from your team: "Critical bug in production! We need a hotfix right now!"
The traditional response is to use git stash, switch to main, fix the bug, and then try to un-stash your messy feature branch later. But if you have complex dependencies (like node_modules or .venv) or untracked files, stashing can lead to absolute chaos.
This is where git worktree comes in. It is the professional's secret weapon for parallel development.
🌳 Why Worktrees Beat Stashing
Normally, a Git repository has one working directory and one .git folder. If you change branches, the files in your folder physically change.
A worktree allows you to check out multiple branches at the exact same time by creating new physical folders on your computer. All these folders share the exact same .git history under the hood, but they operate completely independently.
- You don't have to touch your current uncommitted work.
- Your development server running on your feature branch doesn't break.
- You can open the hotfix in a brand-new code editor window.
💻 The Hotfix Workflow
Here is the exact step-by-step process for handling an emergency fix without touching your current branch. I have placed the entire workflow in a single code block for easy reference.
# 🚨 THE SCENARIO:
# You are currently working inside '~/projects/my-app' on branch 'feature-ui'
# Your boss asks for an immediate fix on the 'main' branch.
# 1. Create a new worktree folder OUTSIDE your current project folder
# Syntax: git worktree add <path-to-new-folder> <branch-to-checkout>
# The '-b' flag creates a brand new branch for the hotfix
git worktree add -b hotfix-login ../my-app-hotfix main
# 2. Navigate to your new folder
cd ../my-app-hotfix
# --> You are now in a completely clean directory! <--
# You can open this folder in a new VS Code window, install dependencies,
# and write your fix without affecting your original 'feature-ui' folder.
# 3. Commit and push your fix
git add .
git commit -m "fix: resolve critical login bug"
git push origin hotfix-login
# 4. Go back to your original, untouched workspace
cd ../my-app
# 5. Clean up: Tell Git you are done with the worktree
git worktree remove ../my-app-hotfix
# 6. Delete the local hotfix branch (optional, once merged)
git branch -d hotfix-login
📊 Feature Comparison: Stash vs. Worktree
| Feature | git stash | git worktree |
|---|---|---|
| Setup Time | Instant | Takes a few seconds (creates folder) |
| Dependency Safety | Low (swapping branches breaks node_modules) | High (completely isolated folders) |
| IDE Experience | Confusing (files suddenly change) | Excellent (open a separate IDE window) |
| Best Used For... | Quick branch switches to look at code | Running tests or building isolated hotfixes |
📚 Sources & Technical Refs
- [1.1] Git SCM Docs: git-worktree - Official manual on managing linked working trees.
- [2.1] Atlassian Git Tutorial: Advanced Git Workflows - Best practices for handling hotfixes in continuous integration environments.
- [3.1] StackOverflow: How to use git worktree for hotfixes - Community discussion on using worktrees for emergency fixes.
- [4.1] GitHub Blog: Mastering Git Worktrees - Real-world examples of worktree usage in large projects.
- [5.1] YouTube: Git Worktree Explained - A visual walkthrough of using git worktrees for parallel development.
- [6.1] Dev.to: Worktrees vs Stash: A Developer's Guide - A detailed comparison of the two approaches for managing uncommitted changes.
