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.
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.
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
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
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.
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 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 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
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
For the full documentation see the git-change.rst file or the man
page, git-change(1).
The extras directory of the source distribution contains the
following extras:
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.
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.
Please report bugs on the GitHub issues page.
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
The folks at OpenStack maintain a similar tool called git-review.