============ git-change

Disclaimer: git-change is no longer in development. Use it at your own risk.

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`_.


.. _Gerrit Code Review: http://code.google.com/p/gerrit/
.. _Python Package Index: http://pypi.python.org/pypi/git-change
.. _issues page: https://github.com/Nextdoor/git-change/issues
.. _GitHub mirror: https://github.com/Nextdoor/git-change
.. _virtualenv: http://www.virtualenv.org/
.. _OpenStack: http://openstack.org/
.. _git-review: https://github.com/openstack-ci/git-review
.. _Nextdoor: http://www.nextdoor.com/
.. _Gerrit repository: https://review.opensource.nextdoor.com/
.. _Gerrit Uploading Changes:
   https://review.opensource.nextdoor.com/Documentation/user-upload.html