From 366df8852f503523cc4f9046d82ba9a99dd51d7f Mon Sep 17 00:00:00 2001 From: Akshay Date: Sun, 12 Feb 2023 12:13:49 +0530 Subject: new art: lapse --- docs/posts/curing_a_case_of_git-UX/index.html | 180 ++++++++++++++++++-------- 1 file changed, 128 insertions(+), 52 deletions(-) (limited to 'docs/posts/curing_a_case_of_git-UX') diff --git a/docs/posts/curing_a_case_of_git-UX/index.html b/docs/posts/curing_a_case_of_git-UX/index.html index 9c4761c..140436a 100644 --- a/docs/posts/curing_a_case_of_git-UX/index.html +++ b/docs/posts/curing_a_case_of_git-UX/index.html @@ -33,7 +33,7 @@ cm   - 9.5 + 9.6 min @@ -42,51 +42,86 @@ Curing A Case Of Git-UX
-

Git worktrees are great, but they fall behind the venerable git checkout sometimes. I attempted to fix that with fzf and a bit of bash.

-

-

Fear not if you haven’t heard of “worktrees”, I have included a primer here.
+

Git worktrees are great, but they fall behind the venerable +git checkout sometimes. I attempted to fix that with fzf and a bit of bash.

+

+

Fear not if you haven’t heard of “worktrees”, I have included a +primer here.
Skip the primer ->.

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:

+

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:

-

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:

+

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:
-
# git worktree add -b <branch-name> <path> <from>
+
# git worktree add -b <branch-name> <path> <from>
 git worktree add -b fix-stuff /path/to/tree master

 
    
 
  1. cd into /path/to/tree
    2. 
 
  2. Fix, test, commit, push, party
    3. 
 
  3. Go back to your work, cd -
    4. 
 

-
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.

+
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.

+
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.

+
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:

-
# anywhere, anytime
+
# anywhere, anytime
 λ git checkout feature/is-ascii-octdigit

 
Meanwhile, in worktree world:

-
# keeping these paths in your head is hard
+
# 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]
+~/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.

+
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:

-
λ git branch -v
+
λ 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 ...

@@ -105,41 +140,60 @@ 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.

+
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 (or skim or 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:

-
gwj () {
+
I’d suggest looking up fzf (or skim or 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:

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

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

-
# here, "master" is a directory, which contains my main
+
# 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:

-
λ 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):

-
λ gwj
+
λ 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):

+
λ 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]

+> ~/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:

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

+> ~/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:

-
gwj () {
+
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:

+
gwj () {
   local out
   out=$(
     git worktree list |
@@ -148,8 +202,10 @@ aa857eb953e Auto merge of #100537 - petrochenkov:pic ...
   )
   cd $out
 }

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

-
λ gwj
+
Once again, hit gwj inside a git repository with linked
+worktrees:

+
λ gwj
 ╭─────────────────────────────────────────────────────────╮
 │ eac6c33bc63 Auto merge of 100869 nnethercote:replace... │
 │ b32223fec10 Auto merge of 100707 dzvon:fix-typo, r=d... │
@@ -167,9 +223,16 @@ aa857eb953e Auto merge of #100537 - petrochenkov:pic ...
 > /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:

-
λ git checkout f<tab>
+
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:

+
λ git checkout f<tab>
 feature/is-ascii-octdigit
 fix/some-error
 format-doc-tests
@@ -177,16 +240,22 @@ aa857eb953e Auto merge of #100537 - petrochenkov:pic ...
 λ 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:

+
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. 
 
  2. Hit enter
    3. 
 
  3. Type out a query and narrow down your search
    4. 
 
  4. Hit enter
    5. 
 

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

-
gwj () {
+
We can speed that up a bit, have fzf narrow down the candidates on
+startup, just like our shell does:

+
gwj () {
   local out query
   query="${1:- }"
   out=$(
@@ -196,8 +265,12 @@ aa857eb953e Auto merge of #100537 - petrochenkov:pic ...
   )
   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:

-
# skip through the fzf prompt:
+
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:

+
# skip through the fzf prompt:
 λ gwj master
 # cd -- ~/worktrees/rustc/master
 
@@ -212,8 +285,11 @@ aa857eb953e Auto merge of #100537 - petrochenkov:pic ...
   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:

-
# gwa /path/to/branch-name
+
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:

+
# gwa /path/to/branch-name
 # creates a new branch and "switches" to it
 function gwa () {
   git worktree add "$1" && cd "$1"
-- 
cgit v1.2.3