Using Git Worktrees

· 866 words · 5 minute read

TL;DR:

mkdir project
cd project
git clone --bare <repository> .bare
echo "gitdir: ./.bare" > .git
git worktree add main
git worktree add work

I came across this article from matklad about using git worktrees. I have had several occasions of needing to stash work and switch branches, and it really can be a good bit of mental gymnastics to context switch like that, and then come back to what I had stashed and pick up where I left off. I appreciate their idea of being able to work concurrently on multiple aspects of a project at once using git woktrees.

I have a directory structure that I really like, modeled on how Go structures directories. Each project goes into ~/Work/src/<upstream>/<repository>, which makes it very easy to find projects on the fly. For example, I was recently working with koxudaxi/datamodel-code-generator. While I was exploring the project, I kept a copy at ~/Work/src/github.com/koxudaxi/datamodel-code-generator. But later I forked the project in order to make some contributions. My fork goes into ~/Work/src/github.com/andrew-womeldorf/datamodel-code-generator.

So I wanted to come up with the workflow that would work best with my preferred directory structure. I came across a few different workflows that each had their own quirks that I didn’t really like, until I finally found one I liked.

Neighboring directories 🔗

The most common advice I found when reading about worktrees was to just make neighboring directories for each worktree:

git worktree add ../myfeature

However, if I did that, my github directory structure would now contain:

.
└── andrew-womeldorf
    ├── datamodel-code-generator
    │   ├── .git
    │   │   ├── branches
    │   │   ├── COMMIT_EDITMSG
    │   │   ├── config
    │   │   ├── description
    │   │   ├── HEAD
    │   │   ├── hooks
    │   │   ├── index
    │   │   ├── info
    │   │   ├── logs
    │   │   ├── objects
    │   │   ├── refs
    │   │   └── worktrees
    │   └── README.md
    └── myfeature
        ├── .git
        └── README.md

That doesn’t work well for me, because if I was looking through my directories, and saw myfeature, my initial assumption would be that I have a project at github.com/andrew-womeldorf/myfeature.

Nested directories 🔗

For my structure, it’s better if myfeature was contained in ~/Work/src/github.com/andrew-womeldorf/datamodel-code-generator. The problem with that is that I’d be nesting a duplicate of all project files inside the project files.

git worktree add myfeature

.
└── andrew-womeldorf
    └── datamodel-code-generator
        ├── .git
        │   ├── branches
        │   ├── COMMIT_EDITMSG
        │   ├── config
        │   ├── description
        │   ├── HEAD
        │   ├── hooks
        │   ├── index
        │   ├── info
        │   ├── logs
        │   ├── objects
        │   ├── refs
        │   └── worktrees
        ├── myfeature
        │   ├── .git
        │   └── README.md
        └── README.md

That leaves too much opportunity to really screw up and add a ton of unnecessary files.

Neighboring directories nested in a non-git directory 🔗

This is getting closer to what I want to see, at least visually. However, being in andrew-womeldorf/datamodel-code-generator doesn’t allow me to do anything with worktrees. I need to go down into the worktrees to do anything, which can be confusing.

.
└── andrew-womeldorf
    └── datamodel-code-generator
        ├── main
        │   ├── .git
        │   │   ├── branches
        │   │   ├── COMMIT_EDITMSG
        │   │   ├── config
        │   │   ├── description
        │   │   ├── HEAD
        │   │   ├── hooks
        │   │   ├── index
        │   │   ├── info
        │   │   ├── logs
        │   │   ├── objects
        │   │   ├── refs
        │   │   └── worktrees
        │   └── README.md
        └── myfeature
            ├── .git
            └── README.md

Bare Repository 🔗

Another option is to use a bare git repo.

git clone --bare git@github.com:andrew-womeldorf/datamodel-code-generator
cd datamodel-code-generator
git worktree add main
git worktree add myfeature

.
└── andrew-womeldorf
    └── datamodel-code-generator
        ├── branches
        ├── config
        ├── description
        ├── HEAD
        ├── hooks
        │   ├── applypatch-msg.sample
        │   ├── commit-msg.sample
        │   ├── fsmonitor-watchman.sample
        │   ├── post-update.sample
        │   ├── pre-applypatch.sample
        │   ├── pre-commit.sample
        │   ├── pre-merge-commit.sample
        │   ├── prepare-commit-msg.sample
        │   ├── pre-push.sample
        │   ├── pre-rebase.sample
        │   ├── pre-receive.sample
        │   ├── push-to-checkout.sample
        │   └── update.sample
        ├── info
        │   └── exclude
        ├── main
        │   ├── .git
        │   └── README.md
        ├── myfeature
        │   ├── .git
        │   └── README.md
        ├── objects
        │   ├── 10
        │   ├── 4b
        │   ├── fa
        │   ├── info
        │   └── pack
        ├── packed-refs
        ├── refs
        │   ├── heads
        │   └── tags
        └── worktrees
            ├── main
            └── myfeature

Ugly.

Bare repository with a reference file 🔗

Finally, I found a post by tomups that had my answer, which is to use a bare repository in a hidden directory with a text file for .git that points to the bare repository. I didn’t know you could do this with git, but it’s pretty cool.

mkdir datamodel-code-generator
cd datamodel-code-generator
git clone --bare git@github.com:andrew-womeldorf/datamodel-code-generator .bare
echo "gitdir: ./.bare" > .git
git worktree add main
git worktree add myfeature

.
└── andrew-womeldorf
    └── datamodel-code-generator
        ├── .bare
        │   ├── branches
        │   ├── config
        │   ├── description
        │   ├── HEAD
        │   ├── hooks
        │   ├── info
        │   ├── objects
        │   ├── packed-refs
        │   ├── refs
        │   └── worktrees
        ├── .git
        ├── main
        │   ├── .git
        │   └── README.md
        └── myfeature
            ├── .git
            └── README.md

So now each non-hidden directory in the andrew-womeldorf/datamodel-code-generator directory is a separate worktree. I can run git worktree commands from andrew-womeldorf/datamodel-code-generator. My preferred directory structure is minimlally impacted. And I don’t have files nested oddly inside of worktrees just to make worktrees work.

git