magit-insert-worktrees improves status buffers

The Magit package for Emacs is my Git UI of choice, and git worktrees are very convenient. They mesh up particularly well by adding the built-in magit-insert-worktrees to magit-status-sections-hook. With this, the magit status buffer shows a summary of the branch/HEAD/path of all worktrees, and allow jumping between them in a flash.

1
2
;; Show all worktrees at the end of the status buffer (if more than one)
(add-hook 'magit-status-sections-hook #'magit-insert-worktrees t)

Worktrees

Git has a feature called worktrees, which are a nifty way to do work in parallel: different branches checked out in different directories, but all sharing a single .git directory. This means less disk space used on duplicate .git clones, but, more usefully, data like branches & stashes is shared.

There’s lots of ways to use worktrees, and they’re especially handy in the age of AI agents. At the most basic level, they’re useful for working concurrently, like reducing context switching when balancing deep projects, code reviewing, and small fixes.

I know some people like to create a new worktree for each branch they work on, and then remove them once finished (or get their agents to do so). I personally generally have fixed long-lived worktrees⁰ that I cycle branches through as required: for my main work repo, I’m up to name, name2, …, name5 at the moment… and if I ever need a 6th one, I’ll just create it.

Finding the worktrees

In either case, I find it annoying to keep track of what worktrees are ‘live’. There’s workable solutions, but they’re a bit of friction:

• CLI: run git worktree list or some alias.
• Magit: hit keybinding Z g in magit buffers to see a switcher.

The magit status buffer is the entry-point to a Git repo, and surfaces a lot of information that’s handy to have immediately available, in collapsible sections, things like diffs of any uncommitted and branch summaries. It reduces friction by making git status/git diff/… automatic and interactive, and is customisable.

I wanted to apply that mindset to worktrees too, and so, recently, started writing my own worktree section inserter… but then thought to double check the Magit source code for anything similar, and found exactly what I wanted¹!

Magit has a builtin magit-insert-worktrees function that inserts a section summarising all worktrees (or nothing, if there’s only one worktree). It’s interactive: hitting RET on any worktree shows the magit status buffer for it.

It’s not used by default, so it needs to be explicitly enabled by adding to the hook that the status buffer executes to show all the sections. My init files now include:

1
2
;; Show all worktrees at the end of the status buffer (if more than one)
(add-hook 'magit-status-sections-hook #'magit-insert-worktrees t)

My status buffers now look like the screenshot above. Yay!