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

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

npm-link | What NPM won't tell you!

Hello readers. So back with another easy yet unexplored feature of npm/yarn packages. We as frontend developers / SDK developers, have to deal with more than one repositories where we actually code contribute. Most SDK developers would know this already or they use the not-so-well documented 'npm link' command . /**  *  @disclaimer  * Please read this post fully before executing any command. My scenario might not be the same as yours.  * This article below uses a repo from my current workplace as an example which is open-source and does not violate the Cisco Confidentiality Policies */ To make this article easier to understand, some representations, Host - Package that needs another local package as part of its node modules. Let's assume the path to this package is  ~/Documents/Repos/demo-app Adhoc - Local package that is added into another package as a dependency. Let's assume the path to this package is  ~/Documents/Repos/semver-monorepo What is npm link? This is a co

Git magic - Squash commits

Back with another git magic. When it comes to merging a pull request on Github, there are two options Rebase and Merge Squash and Merge What is Rebase and Merge? When one chooses Rebase and Merge, all the commits in the PR are added to the target branch. For example, if the PR has 5 commits, all of those commits will be visible in the PR history of the target branch. What is Squash and Merge? When a PR is merged by choosing Squash and Merge, all the commits in the PR are combined into one PR and then added to the target branch. Once again, if the PR has 5 commits or any number of commits, they are combined and added to the target branch. Therefore, this is what Squash means. Combining 'n' different commits into one single commit is called squashing. In this blog post, we will go through the commands that can squash commits.  Advantages of Squashing commits No more redundant commits In a pull request, one may have 'n' different commits for one change. They might have bee