In a previous blog post, I wrote about dumpster diving through dotfiles to get better git logging. I wanted to dive once again into those depths to pull out another very useful pearl.
Do you ever want to know which remote branches you have in your repo? I
frequently use git branches — a git alias from thoughtbot’s dotfiles
— to do just that. It’s something like git branch but for remote
branches. It’s a superpower, and it comes as courtesy of the wonderful Ian
Zabel.
Let’s take a look at what it does in FactoryBot’s repo.
$ git branches
Wow! There are some very old branches out there. But aside from that, pretty good, right?
Diving in
If you look at the gitconfig in thoughtbot’s dotfiles, you’ll find this alias:
branches = for-each-ref --sort=-committerdate --format=\"%(color:blue)%(authordate:relative)\t%(color:red)%(authorname)\t%(color:white)%(color:bold)%(refname:short)\" refs/remotes
It looks long and intimidating. So let’s walk through it, piece by piece.
git for-each-ref
The command we are running is git for-each-ref. The rest are options we are
passing to it. Let’s first run it without options:
$ git for-each-ref
It looks like git for-each-ref is listing all the refs that we have.
Since we have not provided any options, it’s listing all the branches
(refs/heads) that I have locally, all the remote ones (refs/remotes), and
any tags that the repo has (refs/tags).
Now that we have the basics, we can look at the options we’re passing.
The description found in git for-each-ref --help says the following:
Iterate over all refs that match
<pattern>and show them according to the given<format>, after sorting them according to the given set of<key>.
So we can pass a <pattern> to filter the list, a <format> to make the output
more intelligible, and a <key> to sort the results. Let’s look at each of
those in turn.
Filter with a <pattern>
Let’s trim down our list of results to only show remote branches
(refs/remotes), since that’s what our git branches alias does:
$ git for-each-ref refs/remotes
Excellent. Now we’re only listing refs/remotes. Let’s add some formatting so
we can more easily understand what we’re reading.
Setting a <format>
The formatting option seems the most daunting when looking at the git branches
alias. But when we look at it more closely, it turns out it’s not so bad. This
is the option in full.
--format=\"%(color:blue)%(authordate:relative)\t%(color:red)%(authorname)\t%(color:white)%(color:bold)%(refname:short)\"
It can be broken down into three main components:
%(color:blue)%(authordate:relative)%(color:red)%(authorname)%(color:white)%(color:bold)%(refname:short)
So we want the relative date in blue, the author’s name in red, and the branch’s
name (the short version, without refs/remotes/) in bold white. We also
separate those three components with tabs (\t).
The --format option takes a string as an argument and interpolates the values we
saw above. So when running from the command line, we will not escape the opening
and closing quotes, and we will replace the tabs from \t to %09 so they are
interpolated correctly. Let’s run the following command:
$ git for-each-ref --format="%(color:blue)%(authordate:relative)%09%(color:red)%(authorname)%09%(color:white)%(color:bold)%(refname:short)" refs/remotes
Nice formatting!
Sorting with a <key>
Now for the last part. Let’s sort them in descending order to see the most
recent first. We’ll sort by -committerdate (note the - in front to denote
descending order).
$ git for-each-ref --sort=-committerdate --format="%(color:blue)%(authordate:relative)%09%(color:red)%(authorname)%09%(color:white)%(color:bold)%(refname:short)" refs/remotes
Excellent. We did it!
Alias it
That is a long command to type. Before you go, make sure to alias it as git
branches or git remote-branches or something else to your liking.
git config --global alias.branches 'for-each-ref --sort=-committerdate --format="%(color:blue)%(authordate:relative)%09%(color:red)%(authorname)%09%(color:white)%(color:bold)%(refname:short)" refs/remotes'
Dumpster Dive through Dotfiles
If you enjoyed this, I encourage you to do some dumpster diving on your own to find more treasure. The thoughtbot dotfiles repo is a great place to start. There are more pearls to be found.
