Skip to main content

Git worktree - guide to flexible folder structure

As always, let's start with a story why I have written this one down. I have been using git for almost 5 years now and in one of my work places I had to work on the same project but different features in parallel. 

Switching between branches back and forth was a costly operation given that I didn't discover commit amend until recently. Even though I'd have discovered commit amend, I'd still have did this.

Still did what?

I can sense that question deep from your throats. So, whenever I am in a situation to work on multiple features or a feature and a bug fix, I'd have two clones of my repo each with different branches,

Whenever a feature is merged or the fixes are merged, I'll delete the clone in my machine and branch in my origin (Gitlab / Github etc.,)

Recently when I started writing these git articles, my manager suggested me to learn about Git Worktree and it'll be useful. And when I got free and good understanding of git commit, rebase and stuff, I decided to explore worktree and to my surprise, Git can bring in the above kind of folder structure using worktree.


  1. Clone your repository
  2. Create a new branch either in remote or local
  3. Once done, we are ready to get started with worktree.

Getting started

Creating a worktree

So, you have a branch created and now you need that branch to be checked out but in a different folder. This is when you create a worktree like below command, 

Assuming you are already in the following folder structure and inside the directory "master",

Let's try and create a work tree with the following command,

 * The commit hash and messages used are not real and wrote for demo purposes

Now, a new folder gets created under ProjectA with name "create-action" and when you navigate into that folder, you'll see that the branch that is checked out there is feature/create-action and the folder structure will look like,

What are the benefits?

  1. Quickest & easiest command to create a new folder and clone a different branch.
  2. Uses less memory compared to the former way of cloning each branch. This is because, all these worktrees use the same ".git" folder which holds remote and local git configurations. 
  3. Once again, quick command to remove the folder once done.

Caution - If you want to backup a worktree

As it uses the same .git folder, after creating a work tree, if you copy that folder as a backup, git changes made in the original folder will affect the copied backup folder as well. If you check the file type of master/.git it would be directory and it would be so for any cloned repo folder.

However for worktree, it's just like a symlink. If you check the file type for create-action/.git here, it will be an ASCII text file with the content as below,

gitdir: ~/Repos/Project A/master/.git/worktrees/feature/create-action

Therefore, if you are backing up a worktree folder, ensure you remove the .git file inside the copy. This way, the changes made in the original directory wouldn't affect the copied backup.

Listing all the worktrees

Now, while the command is simple, you will just have to be in the folder that has .git directory. In this case, the master branch folder.

This will list all the worktrees created. 

Removing a worktree

We shall remove a worktree folder by simply deleting the folder. However the information file that will be available in ~/Repos/Project A/master/.git/worktrees will continue to exist. 

To avoid this, git has introduced the remove command like below,

This will remove the folder in .git/worktrees as well as in the Repos/Project A

This documentation about worktree from git explains a lot more in detail but above are the basics with which a developer can lead a more peaceful folder structure.

Have a good time re-structuring your local repo with worktrees if not already 💪


Popular posts from this blog

Git - Removing a file from a commit

Once again, another git magic that might be of help to some of you. This research came up when I accidentally added a couple of unwanted files and wanted to remove them from a commit. We all know that to update an existing commit, we shall follow this git magic to amend commits . However, how do we drop changes to a particular file in a commit? While that is easy, it is also tricky. This blog post covers scenarios and respective commands that help you understand what should be done. /**  *  @disclaimer  * Please read this post fully before executing any command. My scenario might not be the same as yours. */ There are two scenarios to be handled here, Remove a newly added file Remove changes to an existing file Let's look at them separately, Remove a newly added file This is the scenario where an unwanted file added to the commit. This file might be some config.json that got generated while doing a research on a new testing tool or a bundling tool. Such scenarios are easier. 1. Re

Confluence: 5 quick things that you need

As part of my work experiments, this week I would like to write down the things that one needs to know in confluence that can up-skill their documentation works. I will cover the following 5 things, How to Anchor link a title? How to Anchor link to a section? How to create a dashing dashboard? Panel - Confluence Macro Layouts - Confluence Tools Content by Label - Confluence Macro 1. How to Anchor link a title? This is the most required thing. Most useful when one has to refer to a section internally on the same confluence page. Let's consider you have a page with three different sections and titles as shown below, In this, if you want to add an internal anchor from a text in paragraph 3 to a title in paragraph 1, you can add it as follows, Choose the word that needs Anchor Click on the link icon from the Toolbar above In the link box, enter #Page Title 1 Click Insert That is it. Your anchor from the selected text to Page Title 1 is ready. This can be tested out in the preview itsel