Git worktree layout

git-worktrees.md

I use git worktrees a lot, and I’ve been annoyed by the repo itself having effectively a privileged worktree that’s always there (and refuses to let any other worktree check out the branch it’s on). And then not having a good place to put my other worktrees. If I clone to $PROJECTS/this-project, where do I put my worktrees?

• If I put them in the directory, the worktree directories are scattered among all the files in the clone’s working tree (and I seem to remember git having some issues with worktrees inside a working tree), but
• if I put them next to the directory, then the worktree names need to be prefixed with the repo name (and if there are repos foo and foo-charts, it’s easy to forget that foo-charts isn’t just a worktree of foo.

So, my projects tended to look like this:

$PROJECT_DIR
├── my-project                           # a repo
│   ├── .git
│   └── ...                              # but also a working tree
├── my-project-add-some-feature          # a worktree
│   └── ...
├── my-project-charts                    # a different repo, but with a worktree-looking name
│   ├── .git
│   └── ...                              # which also has its own working tree
├── my-project-charts-refactor-something # a worktree in the different repo
│   └── ...
└── my-project-fix-this-bug              # another worktree in the first repo
    └── ...

But now I have a new script for cloning a repo (abbreviated a bit here), which does this:

CLONE_DIR=$PROJECT_DIR/$REPO/repo
git clone $DOMAIN/$ORGANIZATION/$REPO $CLONE_DIR
cd $CLONE_DIR
git checkout $(git commit-tree $(git hash-object -t tree /dev/null) < /dev/null)

which is what I wish git clone --bare did, but doesn’t quite. Basically, you end up with a repo without a working tree. So there’s no branch locked by the repo, and no privileged working tree.

So then I end up with something like this:

$PROJECT_DIR
├── my-project
│   ├── add-some-feature  # a worktree
│   │   └── ...
│   ├── fix-this-bug      # another worktree
│   │   └── ...
│   └── repo              # the “bare” repo
│       └── .git          # the only thing in the “bare” repo
└── my-project-charts     # a different project with a worktree-looking name
    ├── refactor-something
    │   └── ...
    └── repo
        └── .git

It’s annoying to have that script for cloning, so I’ll probably try to get rid of it. But after the initial clone, I really like working like this.

Hey @sellout, really nice approach!
So do you use your CLI tool to create worktrees anywhere?
I tried looking up astrolabe but couldn’t find anything, is it open source?

It’s unfortunately still private. Mostly just because of some embarrassing jankiness – it started life as a bunch of Bash scripts, but has thankfully left that behind.

It’s been on the verge of public release for a while, but I always find myself mucking about in its dependencies, thinking “it’ll be ready soon …”

Oh, no worries at all

I liked the layout you described enough that I ended up experimenting with it by writing a small CLI tool called orbit

While building it and thinking through the workflow, I remembered that I had recently started using worktrunk. It already solves a lot of the worktree management burden, but it does not really model this worktree hub + cache outside concept.

So I wrote up a feature request for the worktrunk maintainers, using orbit as a small validation prototype for the idea: max-sixty/worktrunk#2524

Thanks – I hadn’t heard of worktrunk – it looks great. I‘ll have to check it out.

I commented on your issue there – maybe helped make the case … maybe undermined it … no idea. Good luck!