opendev/git-review
Code Issues Proposed changes
master
git-review/doc/source/installation.rst
Florian Haas 04786cd9ea Doc updates for Git "core.hooksPath" option support 
Couple of small follow-ups to Id8a3ac464ff75e6d8207f198089f018cc790eca5:

* Fix formatting in the reno (use monospace as applicable).
* Update "Installation and Configuration" to say that the local hook
  *normally* goes into .git/hooks.

Change-Id: I1b326bdcaed38d3a82a65f944431f3640652dd33
2021-06-24 12:06:12 +02:00

3.4 KiB
Raw Permalink Blame History

Installation and Configuration

Installing git-review

git-review can be installed from PyPI or system packages. To install from PyPI, run:

pip install git-review

Alternatively, refer to the MediaWiki Guide for information on installing from system packages.

Note

git-review requires git version 1.8 or greater.

Windows

The Windows cmd console has a number of issues with Python and Unicode encodings which can manifest when reviews include non-ASCII characters. Python 3.6 and beyond has addressed most issues and is recommended for Windows users. For earlier Python versions, modifying the local install with win-unicode-console may also help.

Setup

By default, git-review will look for a remote named gerrit for working with Gerrit. If the remote exists, git-review will submit the current branch to HEAD:refs/for/master at that remote.

If the Gerrit remote does not exist, git-review looks for a file called .gitreview at the root of the repository with information about the Gerrit remote. Assuming that file is present, git-review should be able to automatically configure your repository the first time it is run.

The name of the Gerrit remote is configurable; see the configuration section below.

.gitreview file format

Example .gitreview file (used to upload for git-review itself):

[gerrit]
host=review.opendev.org
port=29418
project=opendev/git-review.git
defaultbranch=master

Required values: host, project

Optional values: port (default: 29418), defaultbranch (default: master), defaultremote (default: gerrit).

Notes

  • Username is not required because it is requested on first run
  • Unlike git config files, there cannot be any whitespace before the name of the variable.
  • Upon first run, git-review will create a remote for working with Gerrit, if it does not already exist. By default, the remote name is gerrit, but this can be overridden with the defaultremote configuration option.
  • You can specify different values to be used as defaults in ~/.config/git-review/git-review.conf or /etc/git-review/git-review.conf.
  • git-review will query git credential system for Gerrit user/password when authentication failed over http(s). Unlike git, git-review does not persist Gerrit user/password in git credential system for security purposes and git credential system configuration stays under user responsibility.

Hooks

git-review has a custom hook mechanism to run a script before certain actions. This is done in the same spirit as the classic hooks in git.

There are two types of hooks:

  • a global one which is stored in ~/.config/git-review/hooks/,
  • and one local to the repository, which is stored with the other git hook scripts. Normally that's the .git/hooks/ directory in your checkout.

The script needs be executable before getting executed

The name of the script is $action-review where action can be:

  • pre - run at first before doing anything.
  • post - run at the end after the review was sent.

If the script returns with an exit status different than zero, git-review will exit with the custom shell exit code 71.