path: root/posts/curing_a_case_of_git-UX.md

Git worktrees are great, but they fall behind the venerable
`git checkout` sometimes. I attempted to fix that with
[fzf](https://github.com/junegunn/fzf) and
a bit of bash. 

[![](https://asciinema.org/a/D297ztKRzpE4gAHbPTPmkqYps.svg)](https://asciinema.org/a/D297ztKRzpE4gAHbPTPmkqYps)

Fear not if you haven't heard of "worktrees", I have
included a primer here.  
[Skip the primer
->](#what-makes-them-clunky).

### Why Worktrees?

Picture this. You are whacking away on a feature branch.
Halfway there, in fact. Your friend asks you fix something
urgently. You proceed to do one of three things:

- create a temporary branch, make a WIP commit, begin
  working on the fix
- stash away your changes, begin working on the fix
- unfriend said friend for disturbing your flow

All of these options are ... subpar. With the temporary
branch, you are forced to create a partial, non-working
commit, and then reset said commit once done with the fix.
With the stash approach, you are required to now keep a
mental model of the stash, be aware of untracked files that
don't get stashed by default, etc. Why won't git just let
you work on two things at the same time without _thinking_
so much? 

That is exactly what worktrees let you do. Worktrees let you
have more than one checkout at a time, each checkout in a
separate directory. Like creating a new clone, but safer (it
disallows checking out the same branch twice) and a lot more
space efficient (the new working tree is "linked" to the
"main" worktree, and a good amount of stuff is shared). When
your friend asks you to make the fix, you proceed like so:

1. Create a new working tree with:
  ```bash
  # git worktree add -b <branch-name> <path> <from>
  git worktree add -b fix-stuff /path/to/tree master
  ```
2. `cd` into `/path/to/tree`
3. Fix, test, commit, push, party
4. Go back to your work, `cd -`

Easy as cake. You didn't have to settle for a partially
working commit, you didn't to deal with this "stash" thing,
_and_ you didn't have to unfriend your friend. Treating each
branch as a directory just _feels_ more intuitive, more
UNIX-y.

A few weeks later, you find yourself singing in praise of
worktrees, working on several things simultaneously. And at
the same time, cursing them for being a little ... clunky.

### What makes them clunky?

Worktrees are great at what they claim to do. They stay out
of the way when you need a checkout posthaste. However, as
you start using them regularly, you realize they are not as
flexible as `git checkout` or `git switch`.

#### Branch-hopping
You can `git checkout <branch>` from anywhere within a git
repository. You can't "jump" to a worktree in the same
fashion. The closest you can get, is to run `git worktree
list`, copy the path corresponding to your branch, and `cd`
into it.

Branch-hopping with the good ol' git-checkout:
```bash
# anywhere, anytime
λ git checkout feature/is-ascii-octdigit
```

Meanwhile, in worktree world:
```bash
# keeping these paths in your head is hard
λ git worktree list
~/worktrees/rustc/master                 eac6c33bc63 [master]
~/worktrees/rustc/improve-std-char-docs  94cba88553e [improve-std-char-docs]
~/worktrees/rustc/is-ascii-octdigit      bc57be3af7a [feature/is-ascii-octdigit]
~/my/other/path/oh/god                   op57or3ns7n [fix/some-error]

λ cd ~/worktrees/rustc/is-ascii-octdigit
```

#### Branch-previewing

You can "preview" branches with `git branch -v`. However, to
get an idea of what "recent activity" on a worktree looks
like, you might need some juggling. You can't glean much
info about a worktree in a jiffy.

Branch-previewing with the good ol' git-branch:
```bash
λ git branch -v
+ feature/is-ascii-octdigit bc57be3af7a introduce {char, u8}::is_ ...
+ improve-std-char-docs     94cba88553e add whitespace in assert ...
* master                    eac6c33bc63 Auto merge of #100869 - n ...
```

Meanwhile in worktree wonderland:
```
λ git worktree list
~/worktrees/rustc/master                 eac6c33bc63 [master]
~/worktrees/rustc/improve-std-char-docs  94cba88553e [improve-std-char-docs]
~/worktrees/rustc/is-ascii-octdigit      bc57be3af7a [feature/is-ascii-octdigit]

# aha, so ../is-ascii-octdigit corresponds to `feature/is-ascii-octdigit`
λ git log feature/is-ascii-octdigit
bc57be3af7a introduce {char, u8}::is_ascii_octdigit
eac6c33bc63 Auto merge of #100869 - nnethercote:repl ...
b32223fec10 Auto merge of #100707 - dzvon:fix-typo,  ...
aa857eb953e Auto merge of #100537 - petrochenkov:pic ...

# extra work to make the branch <-> worktree correspondence
```

#### Shell completions

Lastly, you can bank on shell completions to fill in your
branch whilst using `git checkout`. Worktrees have no such
conveniences.

We can mend these minor faults with fzf.

### Unclunkifying worktrees

I'd suggest looking up
[fzf](https://github.com/junegunn/fzf) (or
[skim](https://github.com/lotabout/skim) or
[fzy](https://github.com/jhawthorn/fzy)). These things make
it cake-easy to add interactivity to your shell. Onto fixing
the first minor fault, the inability to "jump" to a worktree
from anywhere within a git repository.

I have a little function called `gwj` which stands for "git
worktree jump". The idea is to list all the worktrees,
select one with fzf, and `cd` to it upon selection:

```bash
gwj () {
  local out
  out=$(git worktree list | fzf | awk '{print $1}')
  cd $out
}
```

That is all of it really. Head into a git repository:

```bash
# here, "master" is a directory, which contains my main
# worktree: a checkout of the master branch on rust-lang/rust 
λ cd ~/worktrees/rustc/master/library/core/src
λ # hack away
```

Preferably one with a few worktrees:

```bash
λ git worktree list
~/worktrees/rustc/master                 eac6c33bc63 [master]
~/worktrees/rustc/improve-std-char-docs  94cba88553e [improve-std-char-docs]
~/worktrees/rustc/is-ascii-octdigit      bc57be3af7a [feature/is-ascii-octdigit]
```

And hit `gwj` (pretend that the pipe, |, is your cursor):

```bash
λ gwj
> |
  4/4
> ~/worktrees/rustc/master                 eac6c33bc63 [master]
  ~/worktrees/rustc/improve-std-char-docs  94cba88553e [improve-std-char-docs]
  ~/worktrees/rustc/is-ascii-octdigit      bc57be3af7a [feature/is-ascii-octdigit]
```

Approximately type in your branch of choice:

```bash
λ gwj
> docs|
  4/4
> ~/worktrees/rustc/improve-std-char-docs  94cba88553e [improve-std-char-docs]
```

And hit enter. You should find yourself in the selected
worktree. 

Onward, to the next fault, lack of preview-bility. We can
utilize fzf's aptly named `--preview` flag, to, well,
preview our worktree before performing a selection:

```bash
gwj () {
  local out
  out=$(
    git worktree list |
    fzf --preview='git log --oneline -n10 {2}' |
    awk '{print $1}'
  )
  cd $out
}
```

Once again, hit `gwj` inside a git repository with linked worktrees:

```bash
λ gwj
╭─────────────────────────────────────────────────────────╮
│ eac6c33bc63 Auto merge of 100869 nnethercote:replace... │
│ b32223fec10 Auto merge of 100707 dzvon:fix-typo, r=d... │
│ aa857eb953e Auto merge of 100537 petrochenkov:picche... │
│ 3892b7074da Auto merge of 100210 mystor:proc_macro_d... │
│ db00199d999 Auto merge of 101249 matthiaskrgr:rollup... │
│ 14d216d33ba Rollup merge of 101240 JohnTitor:JohnTit... │
│ 3da66f03531 Rollup merge of 101236 thomcc:winfs-noze... │
│ 0620f6e90af Rollup merge of 101230 davidtwco:transla... │
│ c30c42ee299 Rollup merge of 101229 mgeisler:link-try... │
│ e5356712b9e Rollup merge of 101165 ldm0:drain_to_ite... │
╰─────────────────────────────────────────────────────────╯
>
  4/4
> /home/np/worktrees/compiler/master                 eac6c...
  /home/np/worktrees/compiler/improve-std-char-docs  94cba...
  /home/np/worktrees/compiler/is-ascii-octdigit      bc57b...
```

A fancy preview of the last 10 commits on the branch that
the selected worktree corresponds to. In other words, sight
for sore eyes. Our little script is already shaping up to be
useful, you hit `gwj`, browse through your worktrees,
preview each one and automatically `cd` to your selection.
But we are not done yet.

The last fault was lack shell completions. A quick review of
what a shell completion really does:

```bash
λ git checkout f<tab>
feature/is-ascii-octdigit
fix/some-error
format-doc-tests

λ git checkout feat<tab>

λ git checkout feature/is-ascii-octdigit
```

Each time you hit "tab", the shell produces a few
"completion candidates", and once you have just a single
candidate left, the shell inserts that for you directly into
your edit line. Of course, this process varies from shell to
shell.

fzf narrows down your options as you type into the prompt,
but you still have to:

1. Type `gwj`
2. Hit enter
3. Type out a query and narrow down your search
4. Hit enter

We can speed that up a bit, have fzf narrow down the
candidates on startup, just like our shell does:

```bash
gwj () {
  local out query
  query="${1:- }"
  out=$(
    git worktree list |
    fzf --preview='git log --oneline -n10 {2}' --query "$query" -1 |
    awk '{print $1}'
  )
  cd $out
}
```

The change is extremely tiny, blink-and-you'll-miss-it kinda
tiny. We added a little `--query` flag, that allows you to
prefill the prompt, and the `-1` flag, that avoids the
interactive finder if only one match exists on startup:

```bash
# skip through the fzf prompt:
λ gwj master
# cd -- ~/worktrees/rustc/master

# more than one option, we end up in the interactive finder
λ gwj improve
╭─────────────────────────────────────────────────────────╮
│ eac6c33bc63 Auto merge of 100869 nnethercote:replace... │
│ b32223fec10 Auto merge of 100707 dzvon:fix-typo, r=d... │
│ aa857eb953e Auto merge of 100537 petrochenkov:picche... │
╰─────────────────────────────────────────────────────────╯
> improve
  2/2
> /home/np/worktrees/compiler/improve-const-perf     eac6c...
  /home/np/worktrees/compiler/improve-std-char-docs  94cba...
```

Throw some error handling in there, hook up a similar script
to improve the UX of `git worktree remove`, go wild. A few
more helpers I've got:

```bash
# gwa /path/to/branch-name
# creates a new branch and "switches" to it
function gwa () {
  git worktree add "$1" && cd "$1"
}

alias gwls="git worktree list"
```