opendev
/
git-review
Code Issues Proposed changes

Merge "docs: Misc updates"

This commit is contained in:
Zuul 2018-12-17 21:38:03 +00:00 committed by Gerrit Code Review
parent a2bea9f57e f4b46e56be
commit e1958c91f5
3 changed files with 34 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/source/developing.rst
View File

@ -9,15 +9,11 @@ following:
* a Java Runtime Environment on the machine to run tests on
* Internet access to download the gerrit.war file, or a locally
cached copy (it needs to be located in a .gerrit directory at the
* Internet access to download the ``gerrit.war`` file, or a locally
cached copy (it needs to be located in a ``.gerrit`` directory at the
top level of the git-review project)
To run git-review integration tests the following commands may by run::
To run git-review integration tests, use tox. For example, to test against
Python 3.7::
tox -e py27
tox -e py26
tox -e py32
tox -e py33
depending on what Python interpreter would you like to use.
tox -e py37

11
doc/source/index.rst
View File

@ -2,7 +2,7 @@
git-review
============
``git-review`` is a tool that helps submitting git branches to gerrit
``git-review`` is a tool that helps submitting git branches to Gerrit
for review.
.. toctree::
@ -12,12 +12,3 @@ for review.
usage
developing
releasenotes
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

54
doc/source/installation.rst
View File

@ -5,16 +5,15 @@
Installing git-review
=====================
``git-review`` can be often be installed via system packages, ``pypi``
releases or other platform-specific methods. See
`<https://www.mediawiki.org/wiki/Gerrit/git-review>`__ for platform
information.
``git-review`` can be installed from PyPI or system packages. To install from
PyPI, run::
For assistance installing pacakges from ``pypi`` on your OS check out
`get-pip.py <https://pip.pypa.io/en/stable/installing/>`__.
pip install git-review
For installation from source simply add ``git-review`` to your $PATH
after installing the dependencies listed in requirements.txt
Alternatively, refer to the `MediaWiki Guide`__ for information on installing
from system packages.
__ https://www.mediawiki.org/wiki/Gerrit/git-review
.. note:: ``git-review`` requires git version 1.8 or greater.
@ -28,22 +27,24 @@ recommended for Windows users. For earlier Python versions,
modifying the local install with `win-unicode-console
<https://github.com/Drekin/win-unicode-console>`__ may also help.
Setup
=====
By default, git-review will look for a remote named 'gerrit' for working
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.
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
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
======================
@ -55,10 +56,10 @@ Example .gitreview file (used to upload for git-review itself)::
project=openstack-infra/git-review.git
defaultbranch=master
Required values: host, project
Required values: ``host``, ``project``
Optional values: port (default: 29418), defaultbranch (default: master),
defaultremote (default: gerrit).
Optional values: ``port`` (default: ``29418``), ``defaultbranch`` (default:
``master``), ``defaultremote`` (default: ``gerrit``).
**Notes**
@ -68,18 +69,20 @@ defaultremote (default: gerrit).
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
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.
``~/.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
* 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
Gerrit user/password in git credential system for security purposes and git
credential system configuration stays under user responsibility.
Hooks
=====
@ -87,13 +90,12 @@ 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 stored in
.git/hooks/ with the other git hook scripts.
``~/.config/git-review/hooks/`` and one local to the repository stored in
``.git/hooks/`` with the other git hook scripts.
**The script needs be executable before getting executed**
The name of the script is $action-review where action can be
:
The name of the script is $action-review where action can be:
* pre - run at first before doing anything.
@ -101,5 +103,5 @@ The name of the script is $action-review where action can be
* draft - run when in draft mode.
if the script returns with an exit status different than zero,
git-review will exit with the a custom shell exit code 71.
If the script returns with an exit status different than zero, git-review will
exit with the custom shell exit code ``71``.