Package: git-change
Git-changeis a Git command which creates and manages changes for
theGerrit Code Reviewtool.The goal ofgit-changeis 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 featuregit-changeadds is branch management for changes.git-changecreates a
temporary, local branch (achange 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. Becausegit-changecreates 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 youwantB to depend on A and you
can do that, too, by passing the--chainflag togit change.Git-changeis written in Python.InstallationTo install, runpip install git-changeYou can also download the latest release directly from thePython
Package Indexor clone theGitHub mirrorand install withpython setup.py install.SetupConfigure Gerrit SSH hostAdd 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 tyrionSetgit-configoptionsAdd 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-changeincludes 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 trueInstall Git hooksGit-changerequires that you install thecommit-msghook that
ships with Gerrit. The hook ensures that every commit has aChange-Idheader in its commit message. Assuming you configured
the Gerrit SSH host above with the namereview, 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 wantgit-changeto inject bug IDs to your commit messages via
the--bugoption, install theprepare-commit-msghook script
by copying the file from theextrasdirectory of thegit-changesource distribution to your repository’s.git/hooksdirectory.WorkflowAfter hacking together a killer feature, stage the changed files and
send to Gerrit for review:git add .
git change create --reviewers=aryaThis commits the staged changes to a temporary, localchangebranch. 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 thatcreateis the default subcommand and can be omitted. Sogit change--reviewers=aryadoes exactly the same thing as
the command above.The change branch created bygit-changeincludes the Change ID
generated by the Gerritcommit-msghook. It looks something likechange-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 usegit change updateto push the changes as a new patch set:git change list
git add .
git change updategit change listlists 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 usinggit checkout. After you stage
your changes, runninggit change updateadds the staged changes to
the current HEAD commit (by runninggit commit--amendbehind 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 rungit change submitIf 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. Therebasesubcommand handles all of this for you in
one step:git change rebaseSometimes the rebase operation fails due to merge conflicts. If this
happens, resolve the conflicts and rungit change rebaseagain. 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 runninggit change gcNote that only change branches that were created from thecurrenttracking branch will be removed. If the current branch ismasterbut you have old change branches created from thefeaturebranch,
you have to switch tofeaturebefore runninggit change gcin
order to clear out those branches. Of course, you can also remove
stale change branches “manually” withgit branch-d<branch>.OWNERSfilesOWNERSfiles are plaintext files in your codebase containing Gerrit
usernames specifying the “owners” of directories and their
sub-directories recursively.Ifgit-changesupport forOWNERSfiles is turned on (see the
section on Setup), every time a Gerrit changeset is created or
updated,git-changewill attempt to read the relevantOWNERSfiles 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 createGit-changewill read theOWNERSfiles 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_usernameOWNERSscopeOWNERSfiles 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,OWNERSfiles are overridden byOWNERSfiles in
sub-directories.For example, in the case below,a_file.pyanda_file_test.pyare
owned by the owners listed inOWNERS(A), butconfigure_files.shis owned by the owners listed inOWNERS(B):owners-example/
├── a_file.py
├── OWNERS       (A)
├── scripts
│   ├── configure_files.sh
│   └── OWNERS   (B)
└── tests
    └── a_file_test.pyCreatingOWNERSfilesOWNERSfiles are plaintext files (namedOWNERSin the
filesystem) that list Gerrit usernames, one per line.OWNERSfiles
can be added, edited and tracked with git like any other file:$ cat owners-example/OWNERS
ayra
tyrionDocumentationFor the full documentation see thegit-change.rstfile or the man
page,git-change(1).ExtrasTheextrasdirectory of the source distribution contains the
following extras:Bash completionThis 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, thegitpackage 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-changeIf you usevirtualenv, you can source thegit-changecompletion
script as follows:source $VIRTUAL_ENV/etc/bash_completion.d/git-changeYou can also define a list of reviewers in your organization so that
their names appear as completion candidates for options like--reviewersand--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/fileThis works for relatively small lists of reviewers, but probably does
not scale well for large organizations.HooksThis package includes aprepare-commit-msgGit hook script which
injects aBugheader into commit messages if theBUG_IDenvironment variable is set.git-commitcreatesetsBUG_IDif
you pass it the--bugoption.BugsPlease report bugs on the GitHubissues page.ContributingGit-changeis self-hosting; to contribute, first installgit-change. VisitGerrit repositoryto register for an account
and upload your SSH key. SeeGerrit Uploading Changesfor more
detailed instructions.Then clone and configure the Gerrit repository, make your changes, and
finally usegit-changeto send a code review with your changes to
thegit-changeteam: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 createSee alsoThe folks atOpenStackmaintain a similar tool calledgit-review.