From b6aab6d9d6aec26fcf32c45c00f789dc2d2d1ab6 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Mon, 1 Dec 2014 14:34:28 -0500 Subject: Split README.rst into separate doc files Split up the README into separate documentation files so we can publish the documentation for git-review. Change-Id: Idcdf43e73c5ca5b8cb239606236e3b2a660c46b7 --- README.rst | 171 ++----------------------------------------------------------- 1 file changed, 4 insertions(+), 167 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 36541d5..5d60a29 100644 --- a/README.rst +++ b/README.rst @@ -6,170 +6,7 @@ A git command for submitting branches to Gerrit git-review is a tool that helps submitting git branches to gerrit for review. -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. - -Usage ------ - -Hack on some code, then:: - - git review - -If you want to submit that code to a branch other than "master", then:: - - git review branchname - -If you want to submit to a different remote:: - - git review -r my-remote - -If you want to supply a review topic:: - - git review -t topic/awesome-feature - -If you want to disable autogenerated topic:: - - git review -T - -If you want to submit a branch for review and then remove the local branch:: - - git review -f - -If you want to skip the automatic "git rebase -i" step:: - - git review -R - -If you want to download change 781 from gerrit to review it:: - - git review -d 781 - -If you want to download patchset 4 for change 781 from gerrit to review it:: - - git review -d 781,4 - -If you want to compare patchset 4 with patchset 10 of change 781 from gerrit:: - - git review -m 781,4-10 - -If you just want to do the commit message and remote setup steps:: - - git review -s - -.gitreview file format ----------------------- - -Example .gitreview file (used to upload for git-review itself):: - - [gerrit] - host=review.openstack.org - port=29418 - project=openstack-infra/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. - -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 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 -: - -* pre - run at first before doing anything. - -* post - run at the end after the review was sent. - -* 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. - -Installation ------------- - -Install with pip install git-review - -For assistance installing pip on your os check out get-pip: -http://pip.readthedocs.org/en/latest/installing.html - -For installation from source simply add git-review to your $PATH -after installing the dependencies listed in requirements.txt - -Running tests -------------- - -Running tests for git-review means running a local copy of Gerrit to -check that git-review interacts correctly with it. This requires the -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 - top level of the git-review project) - -To run git-review integration tests the following commands may by run:: - - tox -e py27 - tox -e py26 - tox -e py32 - tox -e py33 - -depending on what Python interpreter would you like to use. - -Contributing ------------- - -To get the latest code, see: https://git.openstack.org/cgit/openstack-infra/git-review - -Bugs are handled at: https://storyboard.openstack.org/#!/project/719 - -There is a mailing list at: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra - -Code reviews, as you might expect, are handled by gerrit at: https://review.openstack.org - -Use ``git review`` to submit patches (after creating a gerrit account that links to your launchpad account). Example:: - - # Do your commits - git review - # Enter your username if prompted +* Free software: Apache license +* Documentation: http://docs.openstack.org/developer/git-review +* Source: https://git.openstack.org/cgit/openstack-infra/git-review +* Bugs: https://storyboard.openstack.org/#!/project/719 -- cgit v1.2.1