Gerrymander tips & tricks – defining default command options and adding custom commands

I recently announced gerrymander, a python client tool and API for extracting information from Gerrit, intended to replace my use of various other ad-hoc tools that people have developed. One of the things I observed with using the previous qgerrit command line tool was that there were a couple of different sets of command line arguments that I used all the time. This was tedious so I ended up creating a number of shell wrapper scripts / aliases to invoke qgerrit with different sets of arguments. With gerrymander though, I wanted to do things a little better by defining this stuff as data rather than code. ie using configuration files, instead of wrapper scripts/aliases.

Taking the ‘changes’ command as an example, it is a generic command for displaying lists of changes in gerrit for a given query. The default behaviour is to output 7 columns: status, url, owner, subject, creation date, last updated date and approvals.

$ gerrymander changes -p openstack/nova-specs 
Changes
-------

+-----------+------------------------------------+-----------------------------+-----------------------------------+----------+----------+-------------------------------+
| Status    | URL                                | Owner                       | Subject                           | Created  | Updated  | Approvals                     |
+-----------+------------------------------------+-----------------------------+-----------------------------------+----------+----------+-------------------------------+
| MERGED    | https://review.openstack.org/80785 | russellb                    | Add README and base directory ... | 68 days  | 66 days  | w=1 v=2 s=1 c=2,2             |
| NEW       | https://review.openstack.org/80865 | mikalstill                  | Proposed blueprint for libvirt... | 67 days  | 1 days   | v=-1 c=1,1,-1,-1,-1,-1        |
| ABANDONED | https://review.openstack.org/80866 | mikalstill                  | Proposed blueprint for live mi... | 67 days  | 55 days  | v=1 c=-1,-1                   |
| MERGED    | https://review.openstack.org/81381 | jogo                        | Add Apache 2 License              | 65 days  | 63 days  | w=1 v=2 s=1 c=2,1,2           |
...snip....

Personally I’m not too interested in the last updated date, status or owner most of the time, and want things sorted by last updated date. I want to give lots of space for the subject, have approvals to be displayed in colour and only display changes that are open and in the master branch. This can be done using command line arguments but it gets very tedious:

$ gerrymander changes -p openstack/nova-specs \
     --field url --field subject:80 --field createdOn --field approvals \
     --color --branch master --status open --sort createdOn
Changes
-------

+------------------------------------+-------------------------------------------------------------------------------------+----------+--------------------------+
| URL                                | Subject                                                                             | Created  | Approvals                |
+------------------------------------+-------------------------------------------------------------------------------------+----------+--------------------------+
| https://review.openstack.org/80865 | Proposed blueprint for libvirt serial console work in juno.                         | 67 days  | v=-1 c=1,1,-1,-1,-1,-1   |
| https://review.openstack.org/81828 | Scheduler: Adds per-aggregate filters                                               | 63 days  | v=1 c=1,1,-1,1           |
| https://review.openstack.org/82456 | Propose: Normalize Weights (adapt weighers)                                         | 60 days  | v=-1 c=-1                |
| https://review.openstack.org/82584 | Proposed blueprint for libvirt Sheepdog instances.                                  | 59 days  | v=1 c=1,2,1,1            |
...snip....

This output preference can be added to the $HOME/.gerrymander config file directly, avoiding the need to create a wrapper script

[command-changes]
field=url, subject:80, createdOn, approvals
branch=master
sort=createdOn
color=true

With the result that this is now the default

$ gerrymander changes -p openstack/nova-specs 
Changes
-------

+------------------------------------+-------------------------------------------------------------------------------------+----------+--------------------------+
| URL                                | Subject                                                                             | Created  | Approvals                |
+------------------------------------+-------------------------------------------------------------------------------------+----------+--------------------------+
| https://review.openstack.org/80865 | Proposed blueprint for libvirt serial console work in juno.                         | 67 days  | v=-1 c=1,1,-1,-1,-1,-1   |
| https://review.openstack.org/81828 | Scheduler: Adds per-aggregate filters                                               | 63 days  | v=1 c=1,1,-1,1           |
| https://review.openstack.org/82456 | Propose: Normalize Weights (adapt weighers)                                         | 60 days  | v=-1 c=-1                |
| https://review.openstack.org/82584 | Proposed blueprint for libvirt Sheepdog instances.                                  | 59 days  | v=1 c=1,2,1,1            |
...snip....

Now the obvious limitation with setting defaults in the config file is that you might have many different sets of defaults you care about. For example when looking at nova-specs designs, I’d prefer the sorting to be done by subject and don’t really care about the author. The gerrymander config file copes with this too, by allowing you to setup command aliases:

[commands]
aliases=nova-specs, cinder-specs

[alias-nova-specs]
basecmd=changes
help=Nova design specs

[alias-cinder-specs]
basecmd=changes
help=Cinder design specs

These new commands are now first-class citizens on a par with any other built-in commands as far as gerrymander is concerned, so you can then define default settings for them independently.

[command-nova-specs]
project = openstack/nova-specs
status = open
field = url, subject:80, createdOn, approvals
sort = subject
color = true

[command-cinder-specs]
project = openstack/cinder-specs
status = open
field = url, subject:80, createdOn, approvals
sort = subject
color = true

Trying out the new nova-specs command…

$ gerrymander nova-specs
Changes
-------

+------------------------------------+-------------------------------------------------------------------------------------+----------+--------------------------+
| URL                                | Subject                                                                             | Created  | Approvals                |
+------------------------------------+-------------------------------------------------------------------------------------+----------+--------------------------+
| https://review.openstack.org/95054 | API: Live Resize                                                                    | 9 hours  | v=1                      |
| https://review.openstack.org/85726 | API: Metadata Service Callbacks                                                     | 45 days  | v=1 c=1                  |
| https://review.openstack.org/85673 | API: Proxy neutron configuration to guest instance                                  | 24 days  | v=1 c=1                  |
| https://review.openstack.org/94918 | Add Barbican wrapper specification                                                  | 20 hours | v=1                      |
| https://review.openstack.org/94370 | Add LVM ephemeral storage encryption specification                                  | 2 days   | v=1 c=1,1,-1             |
...snip....

This blog post has just looked at the ‘changes’ command, but any gerrymander command can be customized in this way – every single command line option is mapped into the configuration file in the same way.