This article presents how to use gertty to review Software Factory changes. The goal is to improve the review workflow and overcome the query limit of Gerrit REST to create dashboard for the many projects of Software Factory.


Documentation: Reference configuration:


sudo dnf install y python-gertty || pip install --user gertty


This is my configuration file:

# ~/.gertty.yaml
# replace APIKEY with the one from:
# replace USERNAME with your Github username
# replace RDO_APIKEY with the one from:
# replace OPENSTACK_USERNAME with your openstack username
# replace OPENSTACK_PASSWORD with the one from:
# replace GERTTY_HOME with an absolute path to store gertty data
  - name: sf
    git-url: ssh://${USERNAME}
    auth-type: basic
    username: ${USERNAME}
    password: ${APIKEY}
    git-root: ${GERTTY_HOME}/sf/
    log-file: ${GERTTY_HOME}/sf.log
    socket: ${GERTTY_HOME}/sf.sock
    dburi: sqlite:///${GERTTY_HOME}/sf.db
  - name: rdo
    git-url: ssh://${USERNAME}
    auth-type: basic
    username: ${USERNAME}
    password: ${RDO_APIKEY}
    git-root: ${GERTTY_HOME}/rdo/
    log-file: ${GERTTY_HOME}/rdo.log
    socket: ${GERTTY_HOME}/rdo.sock
    dburi: sqlite:///${GERTTY_HOME}/rdo.db
  - name: openstack
    git-url: ssh://${OPENSTACK_USERNAME}
    username: ${OPENSTACK_USERNAME}
    password: ${OPENSTACK_PASSWORD}
    git-root: ${GERTTY_HOME}/openstack/
    log-file: ${GERTTY_HOME}/openstack.log
    socket: ${GERTTY_HOME}/openstack.sock
    dburi: sqlite:///${GERTTY_HOME}/openstack.db

  - author: "^(.*CI|Jenkins)$"

# Comment to use the default side-by-side
diff-view: unified

# Gertty handles mouse input by default.  Don't mess with my terminal
# mouse handling:
handle-mouse: false

  - name: "Needs review"
    query: "status:open NOT owner:self label:Verified>=1 label:Code-Review>=1"
    key: "f2"

  - name: "My Patches"
    query: "status:open owner:self"
    key: "f3"

  - name: "I am a reviewer, but haven't voted in the current revision"
    query: "status:open NOT label:Code-Review<=-1,self NOT label:Code-Review>=1,self reviewer:self"
    key: "f4"

  - name: "Passed CI, No Negative Feedback"
    query: "status:open label:Code-Review>=0 NOT label:Verified<=-1 NOT owner:self NOT reviewer:self"
    key: "f5"

  - name: "Maybe Review?"
    query: "status:open NOT owner:self NOT reviewer:self limit:25"
    key: "f6"

  - name: "All patches"
    query: "status:open NOT label:Workflow<=-1"
    key: "f7"

Run "gertty" for sf's gerrit, "gertty rdo" for and "gertty openstack" for

Auto subscribe to SF projects

Start gertty once, wait for sync on top right to reach 0, press 'Ctrl-q' to close it and use this command to mass subscribe:

sqlite3 ${GERTTY_HOME}/sf.db 'update project set subscribed = true where name like "%software%factory%" or name like "scl/%"'

When gertty starts again, it will takes sometime to sync and clone all the projects. Wait for sync to reach 0 before continuing.


Here are some note to get started.


On any page, use '?' or 'F1' to display the local keybindings.


Gertty maintains a local cache and synchronize it periodically, look for the Sync number on the top right and wait until it reach 0.

  • Press 'Ctrl-r' to force a resync.

Project subscription

Check the projects you are subscribed:

  • Press 'ESC' many times or 'META-HOME' to go to the project list.
  • Press 'L' to load the list of all projects.
  • Press 's' on a project to subscribe.


The main page shows the open changes per subscribed project.

  • Press 'f2', 'f3', ... to load the custom dashboard defined in the conf.
  • Press 'Su' to sort by update date and 'Sr' to reverse the sort.
  • Press '?' to see available action from changes list.
  • Press 'ENTER' to review a change.
  • Press 'ESC' to close a dashboard (or any windows).

Changes visibility is defined by:

  • Un-reviewed changes are visible.
  • Press 'k' to kill a review. This is useful for DO-NOT-MERGE changes.
  • Press 'v' to mark a change reviewed. This is useful when you left a comment without a review.
  • Press 'l' to toggle hidden changes display.

Change review

  • Press 'ARROWS' to move the cursor
  • Select '< Diff >' to show the diff
    • Press 'p' to change base patchset diff
    • Press 'Enter' to leave a comment
    • Press 'ESC' to close the diff
  • Select '< Review >' to submit a review
  • Press 't' to see Zuul comments
  • Press 'ESC' to close a review


Gertty has a little learning curves, especially if you are not used to ncurse interface, but it pays off.