Git Worktree is one of those functions in Git that I couldn’t find in any course dedicated to this program. I also wondered why that was… Nobody knows about it? Doesn’t anyone use it? Or maybe it’s some niche feature, used only by experts?
Since I started using worktree myself, I know that it should be part of every Git user’s arsenal.
What is Git Worktree?
Git worktree is a function that allows working on multiple branches within a single Git repository without the need for constant stashing changes and switching branches or repeatedly cloning the same repository. Another important feature: each “sub-tree” is directly connected to the original clone of the repository, so all changes are immediately visible in all worktrees. For example, making a pull from a folder where you have the main branch checked out will be immediately visible in the feature branch (if there are no conflicts).
What is also important is that each worktree is a separate directory containing the current revision, just like the original repository. For example, if you have a repository called app-backend (and main branch checked out), you can create a parallel worktree named app-backend-feature, in which you check out the feature branch.
How to use it?
To create a new worktree (assuming you already have a repository on your computer)
git worktree add <path_to_new_directory> <name_of_branch_to_checkout>
For example:
git worktree add ../app-backend-feature feature
If you run the code above in the root directory of your repo, a parallel directory containing the worktree (assuming the feature branch already exists) will be created.
To view a list of existing branches:
git worktree list
To remove a worktree, use the remove command:
git worktree remove <path_to_worktree_directory>
Multi Checkout If you are using the worktree mechanism, remember that you cannot have the same branch checked out on more than one branch. When trying to checkout, Git throws an error similar to the following:
fatal: 'branch-name' is already checked out at '/path/to/other/worktree'
If you want to switch to that branch despite this error, you must first remove the worktree mentioned in the error or change the branch used on it.
Quick Optimization
Since I started using this mechanism, I needed to optimize it quickly. In other words, by default it lists all currently existing branches, and other behavior directs you to other subcommands. So enters the following shell function:
gwtr() {
if [ -z "$1" ]; then
git worktree list
else
git worktree "$@"
fi
}
The variable $@ refers to the current parameters being called on the function, with whitespace and quotes preserved. In other words, standard passthrough.
Summary
Worktree is a great feature, about which (it seems to me) few people know. I recommend using it, as it greatly simplifies working with multiple branches in one repository (in my work this is the norm). Of course, this is not the full spectrum of functionality that this tool offers, but honestly - so far I haven’t needed more. Although of course I encourage you to familiarize yourself with the manual: man git-worktree.
