Unlocking Productivity with Git Worktree: A Guide to Parallel Development

Photo by Yancy Min on Unsplash

What is git work tree?

Git work tree is a feature of Git, which allows you to have multiple working trees associated with a single Git repository. A working tree is a directory on your file system that contains a checkout of a specific branch or commit from a Git repository. By using work trees, you can have multiple instances of your repository’s working directory, each pointing to different branches or commits, without needing to clone the entire repository multiple times.

What does it mean? It means that if you are working on a Git branch of a project, and you have uncommitted changes, and suddenly you need to fix a bug 🐞, let’s say a production bug 🤯, what should you do? You could stash all your changes, switch to the other branch where you need to fix the bug, and then switch back to the previous branch and apply the stash. Alternatively, you could make a commit with incomplete work and hope that someone, or even yourself, will squash all the commits during the merge.

What if I tell you there is a better way

Here comes the Git Work Tree

Work trees are useful in various scenarios, such as:

1. Working on multiple branches simultaneously: You can create multiple work trees, each associated with a different branch, allowing you to switch between branches quickly and easily. This can be helpful when you need to work on different features or bug fixes concurrently.
2. Isolating experimental changes: Work trees provide a convenient way to isolate experimental changes or work in progress without affecting the main working tree. You can create a separate work tree, make changes, test them, and discard the work tree when you no longer need it.
3. Building and testing different versions: If you need to build and test different versions or releases of your project, you can create work trees for each version and easily switch between them.

Let’s get started

git clone --bare <repo url without the .git part>

remember to use the --bare

once you clone the repo, change the directory

cd <your-repo-name>.git

now create a work tree: remember, the work tree name here is similar to branch name

git worktree add main

Preparing worktree (new branch ‘main’)
HEAD is now at 7e767c1 <commit message>

to check the status of this work tree branch

git status @

Now let’s create another work tree

git worktree add non-main

Preparing worktree (new branch ‘non-main’)
HEAD is now at 7e767c1 <commit-message>

now change directory to which ever work tree you want to work on

cd main

That’s it, you are done: whenever you want to change to non-main branch even if you have uncommitted files, it will not complain.

Just change the directory

cd non-main

and Voilà! , you are in the non-main branch

To see the list of git work trees

/Users/chayan/<repo>.git            (bare)
/Users/chayan/<repo>.git/dev        7e767c1 [dev]
/Users/chayan/<repo>.git/main       7e767c1 [main]
/Users/chayan/<repo>.git/non-main   1f80297 [non-main]

To remove one git work tree

git worktree remove <branch>

If you use Neovim, then there’s a great plugin available it which will make your life super easy, here’s the link.

Here’s how to install the plugin.

If you use Packer, then add this in your packer.lua

    use {
        "ThePrimeagen/git-worktree.nvim",
        config = function()
            require("git-worktree").setup({})
            require("telescope").load_extension("git_worktree")
        end
    }

and install the plugin using :PackerSync

and remap the plugin using these 2 lines

vim.keymap.set('n', '<leader>gws', ':Telescope git_worktree git_worktrees<CR>')
vim.keymap.set('n', '<leader>gwc', ':Telescope git_worktree create_git_worktree<CR>')

After installing, once you use the shortcut, it’ll show the work trees like this

change into whichever work tree you want to switch by selecting that.

It’s important to note that work trees share the same Git repository, so operations like commits, merges, and pulls will affect the repository as a whole, regardless of which work tree you’re using. However, changes to files in a specific work tree won’t affect the other work trees unless you explicitly synchronize them.

Git work tree is a powerful feature that provides flexibility and convenience when working on multiple branches or versions of a Git repository simultaneously, making it easier to manage complex development workflows.