gerrit.el

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

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

The function gerrit-upload uses the transient package 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=3.8 and the gerrit version used on review.gerrithub.org.

News

March 2024:

• Renamed gerrit-get-changeid-from-current-commit to gerrit-get-changeid-from-commit with optional revision parameter.
• Renamed gerrit-get-unique-changeid-from-current-commit to gerrit-get-unique-changeid-from-commit with optional revision parameter.

February 2024:

• Add gerrit-rest-change-get-description and gerrit-rest-change-set-description.
• gerrit-upload: Do nothing if remote SHA1 matches SHA1 of HEAD.

Dezember 2023:

• Try to fetch as much gerrit account-info objects as possible at startup.
• Fix invalid json in request problems with gerrit-rest-change-delete-cr-vote, gerrit-rest-change-delete-reviewer and gerrit-rest-change-delete-verified-vote.

Use DELETE method for deleting verified votes + Improve rest-sync-v2

September 2022:

• Add "--no-verify" option to gerrit-upload-transient, which allows skipping the pre-push git hooks.

August 2022:

• [internal] Introduce new gerrit-rest-sync-v2.
• Update gerrit-dashboard-query-alist (Include the "Your turn" in the query, which requires a new-ish gerrit server release >= 3.3).
• Update storage format of gerrit--accounts-alist. This allows displaying the real names of the users instead usernames in the dashboards and the query frontends.
• Display the reviewers instead of the assignee in the default dashboard. It is still possible to display the assignee by adding an assignee entry to gerrit-dashboard-columns.
• Add support for displaying the CC list in the dashboard. To add the CC list to the dashboard add "CC" to gerrit-dashboard-columns.

April 2022:

• Add a new interactive gerrit-query function, which display the results of a user defined gerrit query.
• Display clickable links in the gerrit-dashboard.
• Add support for sorting the columns in the dashboard buffers: To sort by column either click on the column that you want to sort or use tabulated-list-sort (S). [Requested by Gerald]

March 2022:

• Add support for voting to gerrit-dashboard.
  • V set a "Verified" vote for the entire topic under point.
  • C set a "Code-Review" vote for the entire topic under point.

Februrary 2022:

• Fix formatting issue when gerrit-dashboard-columns is customized.
• Allow toggling between HTTPS and HTTP by changing gerrit-use-ssl.

Jannuary 2022:

• Legacy git-review functions were dropped. The gerrit-use-gitreview-interface variable is no longer used.
• Support displaying the owner-name in the displayed changes in gerrit-download.

October 2021:

• Add a new transient called gerrit-download-transient, which will replace the gerrit-download function in the future.
• Add support for downloading changes in arbitrary git workspaces using gerrit-download-transient.
• Add new d keybinding to gerrit-dashboard.

Installation

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

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.

Pre-commit hook

As you know, there is a gerrit pre-commit hook that must be installed for every gerrit repo s.t. the Change-ID is added to the bottom of your git commit messages. This pre-commit hook can be installed using the gerrit--ensure-commit-msg-hook-exists function or e.g. by calling git review -s provided that the git-review CLI tool is installed.

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
• d Download change under point in a local clone of the repository
• t Switch to a buffer containing a topic-overview of the change under point
• e Edit the query and open a new buffer with query results
• RET Download patch of change under point and display it in new buffer

It is possible to click on the links in the dashboard buffer to open new query buffers like in the gerrit webfrontend.

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 the git-review command line tool under the hood.

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