Git is the developer's trusted companion, but standard workflows come with a friction point we've all accepted as "normal": branch switching.
Imagine this scenario. You are deep in a feature branch, debugging a complex logic flow. You have ten modified files, a local dev server running, and build tasks active. Suddenly, a high-priority bug report lands for production, and it needs to be patched immediately.
Before Git worktrees, you had to perform this dance:
- Stash your changes (
git stash) or make a messy "wip" commit. - Stop your development server.
- Switch back to the main branch (
git checkout main). - Apply the hotfix, commit, and push.
- Switch back to your feature branch (
git checkout feat/some-feature). - Apply your stash (
git stash pop) or reset the wip commit. - Resolve any unexpected conflicts and restart your server.
This is a cognitive tax. It breaks your momentum and disrupts your editor state.
But what if you didn't have to switch branches at all? What if you could keep your current branch open and run a parallel, isolated workspace for the hotfix in a completely different directory, without copying or cloning your repository again?
Enter Git Worktrees.
What are Git Worktrees?
A Git worktree is a linked directory checked out from the same repository. Instead of a single directory pointing to one active branch, Git worktrees allow you to check out multiple branches to different folders on your filesystem simultaneously.
Under the hood, all these folders share the same .git directory. They share the repository's database, history, and commits. When you make a commit in one worktree, it is immediately available in all the others. But on your disk, they exist as entirely independent, isolated folders.
This workflow was brought to my attention by a fantastic article on KDnuggets: Git Worktrees for AI Development. While that article highlights how worktrees are game-changing for running autonomous AI agents in parallel, the underlying benefits apply beautifully to everyday developer workflows. I was so excited about the possibilities this presents that I had to write about it immediately!
The Essential Command Reference
Here is a reference of the key commands you need to manage your Git worktrees:
| Command | Description |
|---|---|
git worktree add <path> -b <branch> |
Create a new worktree at <path> on a new branch <branch>. |
git worktree add <path> <existing-branch> |
Check out an existing branch into a new worktree at <path>. |
git worktree list |
List all active worktrees, showing their paths, commit hashes, and branches. |
git worktree lock <path> |
Lock a worktree to prevent it from being automatically pruned. |
git worktree unlock <path> |
Release the lock on a worktree so it can be safely removed. |
git worktree remove <path> |
Remove a worktree directory and clean it up (the branch itself is preserved). |
git worktree prune |
Clean up metadata for worktrees that were manually deleted. |
A Sample Workflow: The Fast-Track Hotfix
Let's look at a practical, 4-step workflow to handle a production emergency using Git worktrees. This example shows how to patch a live site without interrupting your main feature development.
Step 1: Ensure Your Work is Checkpointed
Before creating a new worktree, make sure your current branch is in a stable, committed state. While worktrees don't strictly require a clean state, starting from a clean slate on your target branch makes the checkout process seamless.
# Verify the status of your active feature branch
git status
Step 2: Spin Up a New Worktree for the Hotfix
Now, instead of stashing or checking out, we add a linked worktree. We will place it in a sibling directory (e.g., ../exhibita-hotfix) and create a new branch called hotfix/broken-footer pointing to main.
# Create the worktree on a new branch from main
git worktree add -b hotfix/broken-footer ../exhibita-hotfix main
Step 3: Bootstrap and Configure the New Workspace
Navigate into the new directory. Because this is a fresh workspace on your filesystem, untracked files like local configuration parameters (.env files) won't copy over automatically. We need to copy them and install dependencies.
# Move into the hotfix directory
cd ../exhibita-hotfix
# Copy the local config from the main workspace
cp ../exhibita-static-site/.env .env
# Install project dependencies
npm install
Step 4: Apply the Fix and Clean Up
Now open this folder in a new window, apply your changes, verify them locally, and push the branch. Once your code is merged, you can safely remove the worktree.
# Verify the code compiles and tests pass
npm run build
npm run test
# Commit and push the changes
git add .
git commit -m "fix: restore footer links"
git push origin hotfix/broken-footer
# Return to your main feature directory and clean up the hotfix folder
cd ../exhibita-static-site
git worktree remove ../exhibita-hotfix
With this setup, your original editor window remained completely untouched. Your server continued running, your local files remained in place, and your train of thought stayed on track.
Wrap-Up
If you aren't using Git worktrees yet, you are missing out on one of Git's most powerful productivity hacks. By avoiding the stashing dance, you keep your workspace clean and your focus sharp.
Special thanks again to Shittu Olumide and KDnuggets for the inspiration!