gerrit.el

Gerrit is a great code review tool and a great git hosting serivce. This package provides an emacs interface for

• uploading changes (gerrit-upload)
• downloading changes (gerrit-download)
• creating a dashboard (gerrit-dashboard)
• creating buffers that contain details about gerrit topics an gerrit changes (gerrit-section-topic-info and gerrit-section-change-info).

The function gerrit-upload uses the transient package (if gerrit-use-gitreview-interface is set to nil) and provides the following features in addition to uploading new changes (and new patchsets)

• specify reviewers
• set an assignee
• set a topic name
• set WIP flag
• set a ready-for-review flag

Furthermore, a minimalistic open-reviews status-section (gerrit-magit-insert-status) for magit status buffers is available.

This code is tested using gerrit=2.16 and the gerrit version used on review.gerrithub.org.

Legacy git-review functions and new style REST-based functions

Initially this package depended on the git-review command line tool, which was used for downloading and uploading gerrit changes. The functions are still provided but they are no longer actively updated. They can be used by setting gerrit-use-gitreview-interface to t, which is the default value.

The recommended interface for downloading and uploading gerrit changes is the new REST-API only interface that has to be activated by setting gerrit-use-gitreview-interface to nil.

Installation

If you want to use the git-review interface, make sure that git-review is installed and that every cloned gerrit repo has a gerrit-specific pre-commit hook configured (git review -s).

This emacs package is available on MELPA.

Example use-package config

(use-package gerrit
  :ensure t
  :custom
  (gerrit-host "gerrit.my.domain")  ;; is needed for REST API calls
  (gerrit-use-gitreview-interface nil)
  :config
  (progn
    (add-hook 'magit-status-sections-hook #'gerrit-magit-insert-status t)
    (global-set-key (kbd "C-x i") 'gerrit-upload-transient)
    (global-set-key (kbd "C-x o") 'gerrit-download)))

In the case of the gerrit server review.opendev.org, the following variables have to be set:

(setq gerrit-host "review.opendev.org") ;; runs gerrit-2.13
(setq gerrit-rest-endpoint-prefix "") ;; needed for older(?) gerrit server versions

Authentication

.authinfo, .authinfo.gpg and .netrc

By default emacs searches in files called ~/.authinfo, ~/.authinfo.gpg and ~/.netrc in the specified order for credentials. Take a look at the auth-sources variable and its documentation if you want to change this.

You can add an entry with the following format to any of above files

machine gerrithostname.org
    login my-gerrit-username
    password xxxx

Note: Depending on your auth configuration, Gerrit may expect a generated HTTP password (ex. if you have git_basic_auth_policy="HTTP_LDAP"). If there is an HTTP credentials section in your user's account settings page, then an HTTP password needs to be generated and supplied in your auth-source file.

Keyring

Make sure that emacs was compiled with dbus support (requires devel packages of libdbus).

Load dbus emacs library using (load-library 'dbus).

Make sure that (dbus-list-names :session) returns a non-empty list, otherwise dbus is not working

Load the secrets library, which depends on a working dbus setup.

(load-library 'secrets) and check that the secrets-enabled variable is t.

Now you can list the secrets using secrets-show-secrets.

TODO extend/finalize this documentation.

Screenshots

Usage notes for the gerrit-upload transient

All settings entered in the gerrit-upload transient are saved to a file, whose filename is in the transient-history-file variable. This file is updated in the kill-emacs-hook, which is run when the emacs process/daemon is stopped using (kill-emacs).

If you are using systemd for starting emacs as a daemon, make sure that your unit files contains

ExecStop=/usr/bin/emacsclient --eval "(kill-emacs)"

You can cycle through the history by using M-p and M-n.

The reviewers have to be added as a comma-separated string. Completion of the individual reviewers using the account information from the gerrit servers should work with TAB.

Dashboards

gerrit-dashboard displays a dashboard similar to the one in the gerrit web-interface. The currently supported keybindings in a dashboard buffer are

• a Assign the change under point
• A Assign the change under point to me
• g Refresh
• o Open change under point in browser using browse-url
• t Switch to a buffer containing a topic-overview of the change under point
• RET Download patch of change under point and display it in new buffer

If you want to create multiple dashboards you can create a dashboard using

(defun gerrit-dashboard-standup ()
  (interactive)
  (let ((gerrit-dashboard-query-alist
         '(
           ("Waiting for +1" . "is:open assignee:groupX label:Code-Review=0")
           ("Waiting for +2" . "is:open assignee:groupX label:Code-Review=1")
           )
         )
        (gerrit-dashboard-buffer-name "*gerrit-groupX-standup*")
        )
    (gerrit-dashboard)))

Similar elisp packages

• magit-gerrit Fork of https://github.com/emacsorphanage/magit-gerrit. Uses the ssh interface for performing gerrit requests.

• gerrit-download Downloads gerrit change and shows the diff in a diff buffer. Uses git-review under the hood.

• gerrit-el reimplementation of the gerrit code review Web UI in emacs.