Barnum

Barnum is a command-line companion for Git designed to reduce the ceremony required to use the patch workflow pioneered by Gerrit and adopted by Gitblit. It simplifies the syntax required to retrieve, review, revise, and integrate a patch.

Barnum only requires an installed Java 6 (or newer) Runtime Environment and it runs fine on Windows, Linux, and Mac OS X.

Barnum is similar to git-review by OpenStack and repo by Google.

Download

The current version is 0.7.1, released 2013-12-13.

Windows | Linux/OSX

License

Barnum is licensed under the Apache 2.0 Software License.

What can I do with it?

clone a repository and configure it for patch workflow

pt clone --gerrit https://git.eclipse.org/r/jgit/jgit
pt clone --gitblit https://next-gitblit.rhcloud.com/git/gitblit.git

fetch & checkout a patch as a detached HEAD

pt checkout 9379
pt checkout 9379/10 -b symlinks

push a new or revised patch back to your patch server

pt push

merge a patch revision into your current branch

pt merge 9379
pt merge 9379/10

cherry-pick a patch revision onto your current branch

pt pick 9379
pt pick 9379/10

show a patch revision and it's unmerged, dependent patches

pt show 9379
pt show 9379/10

display the revision history of a patch

pt log 9379

remove local refs for a patch and GC your repository

pt prune 9379
pt prune

How does it work?

Barnum is built on top of the very awesome JGit library.

Patch Index

At it's core, Barnum maintains a patch index built from the advertised refs/changes/xx/id/rev served by your Gerrit or Gitblit server. It uses this index to decorate patch commits with rich information about revisions, dependencies, and their history. Of course, this information is all just branches, Git commits, and Git notes so similar reports could be generated with many, many Git commands, but that's just too much work.

Fetches All Revisions

When you fetch, show, checkout, or log a patch, Barnum will retrieve the complete revision history of that patch, not just one specific revision. When Barnum refreshes it's patch index, it will also determine and cache the merge state of each patch. This allows Barnum to indicate if a patch dependency is obsolete and also if an obsolete dependency has a newer, merged revision.

Offline Tickets

Additionally, if your patch server is Gitblit, then the complete Ticket history is automatically fetched during the clone or init process and subsequently updated on each refresh. This gives you a complete, read-only copy of the Gitblit Ticket data in your repository.

Cool Tricks

Once you have checked-out a patch, you can use relative shortcuts to jump between revisions:

pt checkout /-- (jump back one revision)
pt checkout /-5 (jump back 5 revisions)
pt checkout /++ (jump ahead one revision)
pt checkout /+5 (jump ahead 5 revisions)
pt checkout /10 (review revision 10)

These same trick works for the show command.

Limitations

Barnum is not a general purpose Git client. It only has the commands and options it needs to work with patches and view Gitblit Tickets.
Barnum does not support the SSH transport. Barnum is currently an https/http tool.
Barnum assumes that the Gerrit integration branch for pushing (*refs/for/branch*) is the default branch cloned from the origin. There is partial support for a .gitreview file, but this support is incomplete and untested.
Barnum may incorrectly determine the merge state of a Gerrit patch since it assumes that all patches are targeting one branch, the origin default branch. While this is most often the case, there may be scenarios where this assumption is incorrect.
Gitblit Tickets may not be modified locally and pushed back to the server.

Why the name Barnum?

The name is derived from it's executable name, pt, which is short for patch tool. There may be others, but one famous PT that comes to mind is P.T. Barnum.

Attributions

The tophat icon was designed by Liz Aragon.

It is available for non-commercial use under the CreativeCommons NonCommercial-ShareAlike 3.0 Unported license.