git-change 0.2.0

Git command to create and manage Gerrit Code Review changes

Git-change is a Git command which creates and manages changes for the Gerrit Code Review tool.

The goal of git-change is to simplify the interface for creating and managing code reviews in Gerrit and make that process feel like a natural extension of Git.

Aside from providing some syntactic sugar for dealing with Gerrit code reviews in the form of a Git command, the primary feature git-change adds is branch management for changes. git-change creates a temporary, local branch (a change branch) for each change, allowing you to have several code reviews in flight without introducting dependencies between them. For example, let’s say you’ve made two changes, A followed by B, and sent them both out for code reviews. If the reviewer of change B responds with thumbs up before A’s reviewer does, you can go ahead and submit B and Gerrit will merge it right away. Without separate branches, Gerrit would refuse to submit B until A has been approved and submitted. Because git-change creates a separate branch for each change, they are independent, allowing Gerrit to merge them out of order into the same target branch (e.g., master). Of course, sometimes you want B to depend on A and you can do that, too, by passing the --chain flag to git change.

Git-change is written in Python.

Installation

To install, run

pip install git-change

You can also download the latest release directly from the Python Package Index or clone the GitHub mirror and install with python setup.py install.

Setup

Configure Gerrit SSH host

Add an entry to your SSH config file for your Gerrit server. Place the following lines in ~/.ssh/config, substituting the details according to your system:

Host review
    Hostname review.example.com
    Port 29418
    User tyrion

Set git-config options

Add an entry to your repository’s Git config file for the Gerrit SSH host above. Add an entry for your remote (note that this is necessary only if the remote is named something other than “origin”). You can add the entries by running the following commands, substituting the details according to your system:

git config git-change.remote <remote-name>
git config git-change.gerrit-ssh-host <gerrit-ssh-host>

As of version 0.2.0, git-change includes support for OWNERS files (see more information below). Add an entry if you want to turn on this feature:

git config git-change.include_owners true

Install Git hooks

Git-change requires that you install the commit-msg hook that ships with Gerrit. The hook ensures that every commit has a Change-Id header in its commit message. Assuming you configured the Gerrit SSH host above with the name review, and that the current working directory is the root of your local Git repository, run the following command to install the hook:

scp -p review:hooks/commit-msg .git/hooks/

If you want git-change to inject bug IDs to your commit messages via the --bug option, install the prepare-commit-msg hook script by copying the file from the extras directory of the git-change source distribution to your repository’s .git/hooks directory.

Workflow

After hacking together a killer feature, stage the changed files and send to Gerrit for review:

git add .
git change create --reviewers=arya

This commits the staged changes to a temporary, local change branch. The tracking branch you started from (master, for example) is left in the state it was in before the changes, which means that you can now start on another change that does not depend on the first change.

Note that create is the default subcommand and can be omitted. So git change --reviewers=arya does exactly the same thing as the command above.

The change branch created by git-change includes the Change ID generated by the Gerrit commit-msg hook. It looks something like change-I5372aa17af2c0ddc0de4c15688c605a0e668caa0.

After the reviewer has responded to your code review with feedback and you’ve made the requested changes, switch to the change branch and use git change update to push the changes as a new patch set:

git change list
git add .
git change update

git change list lists all your change branches and as a convenience it provides a menu to select the one you want to switch to. You can also just switch using git checkout. After you stage your changes, running git change update adds the staged changes to the current HEAD commit (by running git commit --amend behind the scenes) and pushes a new patch set to Gerrit.

When it comes time to submit you can either use the Gerrit web interface, or you can run

git change submit

If one or more of the files in your change was updated by someone else in the remote branch meanwhile, Gerrit will refuse to submit the change. Usually in this case you need to pull the upstream changes into your local tracking branch and from there rebase them into your change branch, then finally push them back up to Gerrit as part of your change. The rebase subcommand handles all of this for you in one step:

git change rebase

Sometimes the rebase operation fails due to merge conflicts. If this happens, resolve the conflicts and run git change rebase again. See git-rebase(1) for more information about how to proceed after resolving conflicts.

Finally, a word on housekeeping. Any change branches that accumulate can be cleared out once the corresponding upstream commits have been pulled into your local tracking branch by running

git change gc

Note that only change branches that were created from the current tracking branch will be removed. If the current branch is master but you have old change branches created from the feature branch, you have to switch to feature before running git change gc in order to clear out those branches. Of course, you can also remove stale change branches “manually” with git branch -d <branch>.

OWNERS files

OWNERS files are plaintext files in your codebase containing Gerrit usernames specifying the “owners” of directories and their sub-directories recursively.

If git-change support for OWNERS files is turned on (see the section on Setup), every time a Gerrit changeset is created or updated, git-change will attempt to read the relevant OWNERS files and submit the change with the owners passed as Gerrit reviewers.

For example, let’s say you are listed as an owner of a directory and someone else submits a change to Gerrit that includes a change to a file in that directory:

git change create

Git-change will read the OWNERS files relevant to the changeset and pass your username as a reviewer with the change. This means that from the perspective of Gerrit, the other programmer’s command is effectively:

git change create --reviewers=your_username

OWNERS scope

OWNERS files have recursive scope. This means that if you are listed as a owner of a directory, you are implicitly listed as an owner of that directory’s sub-directories recursively. However, OWNERS files are overridden by OWNERS files in sub-directories.

For example, in the case below, a_file.py and a_file_test.py are owned by the owners listed in OWNERS (A), but configure_files.sh is owned by the owners listed in OWNERS (B):

owners-example/
├── a_file.py
├── OWNERS       (A)
├── scripts
│   ├── configure_files.sh
│   └── OWNERS   (B)
└── tests
    └── a_file_test.py

Creating OWNERS files

OWNERS files are plaintext files (named OWNERS in the filesystem) that list Gerrit usernames, one per line. OWNERS files can be added, edited and tracked with git like any other file:

$ cat owners-example/OWNERS
ayra
tyrion

Documentation

For the full documentation see the git-change.rst file or the man page, git-change(1).

Extras

The extras directory of the source distribution contains the following extras:

Bash completion

This package includes a Bash completion script that completes command line option names and values. It depends on the completion script that ships with Git. On Debian/Ubuntu systems, the git package installs that script as /etc/bash_completion.d/git.

Add the following lines to your Bash init file (e.g., ~/.bashrc), adjusting the paths as necessary for your system:

source /etc/bash_completion.d/git
source extras/bash_completion.d/git-change

If you use virtualenv, you can source the git-change completion script as follows:

source $VIRTUAL_ENV/etc/bash_completion.d/git-change

You can also define a list of reviewers in your organization so that their names appear as completion candidates for options like --reviewers and --cc. Place the list of reviewers according to their Gerrit user names in a text file, one per line. Then add this line to your Bash init file, adjusting the path as necessary:

export GIT_CHANGE_REVIEWERS_FILE=/path/to/file

This works for relatively small lists of reviewers, but probably does not scale well for large organizations.

Hooks

This package includes a prepare-commit-msg Git hook script which injects a Bug header into commit messages if the BUG_ID environment variable is set. git-commit create sets BUG_ID if you pass it the --bug option.

Bugs

Please report bugs on the GitHub issues page.

Contributing

Git-change is self-hosting; to contribute, first install git-change. Visit Gerrit repository to register for an account and upload your SSH key. See Gerrit Uploading Changes for more detailed instructions.

Then clone and configure the Gerrit repository, make your changes, and finally use git-change to send a code review with your changes to the git-change team:

git clone ssh://<sshusername>@review.opensource.nextdoor.com:29418/git-change.git
cd git-change
etc/configure-repository.sh
<make changes>
git add .
git change create

See also

The folks at OpenStack maintain a similar tool called git-review.