git-review/git-review.1

.\" Uses mdoc(7). See `man 7 mdoc` for details about the syntax used here
.\"
.Dd April 4th, 2012
.Dt GIT-REVIEW 1
.Sh NAME
.Nm git-review
.Nd Submit changes to Gerrit for review
.Sh SYNOPSIS
.Nm
.Op Fl r Ar remote
.Op Fl uv
.Fl d Ar change
.Op Ar branch
.Nm
.Op Fl r Ar remote
.Op Fl fnuv
.Fl s
.Op Ar branch
.Nm
.Op Fl fnuvDR
.Op Fl r Ar remote
.Op Fl t Ar topic
.Op Ar branch
.Nm
.Fl -version
.Sh DESCRIPTION
.Nm
automates and streamlines some of the tasks involved with
submitting local changes to a Gerrit server for review. It is
designed to make it easier to apprehend Gerrit, especially for
users that have recently switched to Git from another version
control system.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl d Ar change , Fl -download= Ns Ar change
Download
.Ar change
from Gerrit
into a local branch. The branch will be named after the patch author and the name of a topic.
If the local branch already exists, it will attempt to update with the latest patchset for this change.
.It Fl f , Fl -finish
Close down the local branch and switch back to the target branch on
successful submission.
.It Fl n , Fl -dry-run
Don\(aqt actually perform any commands that have direct effects. Print them
instead.
.It Fl r Ar remote , Fl -remote= Ns Ar remote
Git remote to use for Gerrit.
.It Fl s , Fl -setup
Just run the repo setup commands but don\(aqt submit anything.
.It Fl t Ar topic , Fl -topic= Ns Ar topic
Sets the target topic for this change on the gerrit server.
If not specified, a bug number from the commit summary will be used. Alternatively, the local branch name will be used if different from remote branch.
.It Fl u , Fl -update
Skip cached local copies and force updates from network resources.
.It Fl l , Fl -list
List the available reviews on the gerrit server for this project.
.It Fl y , Fl -yes
Indicate that you do, in fact, understand if you are submitting more than
one patch.
.It Fl v Fl -verbose
Turns on more verbose output.
.It Fl D , Fl -draft
Submit review as a draft. Requires Gerrit 2.3 or newer.
.It Fl R , Fl -no-rebase
Do not automatically perform a rebase before submitting the change to
Gerrit.
.Pp
When submitting a change for review, you will usually want it to be based on the tip of upstream branch in order to avoid possible conflicts. When amending a change and rebasing the new patchset, the Gerrit web interface will show a difference between the two patchsets which contains all commits in between. This may confuse many reviewers that would expect to see a much simpler difference.
.It Fl -version
Print the version number and exit.
.El
.Sh FILES
To use 
.Nm
with your project, it is recommended that you create
a file at the root of the repository named
.Pa .gitreview
and place information about your gerrit installation in it.  The format is similar to the Windows .ini file format:
.Bd -literal -offset indent
[gerrit]
host=\fIhostname\fP
port=\fITCP port number of gerrit\fP
project=\fIproject name\fP
defaultbranch=\fIbranch to work on\fP
.Ed
.Pp
It is also possible to specify optional default name for 
the Git remote using the
.Cm defaultremote
configuration parameter. 
.Pp
Setting
.Cm defaultrebase
to zero will make
.Nm
not to rebase changes by default (same as the 
.Fl R
command line option)
.Bd -literal -offset indent
[gerrit]
host=review.example.com
port=29418
project=department/project.git
defaultbranch=master
defaultremote=review
defaultrebase=0
.Ed
.Pp
.Sh DIAGNOSTICS
.Pp
Normally, exit status is 0 if executed successfully.
Exit status 1 indicates general error, sometimes more
specific error codes are available:
.Bl -tag -width 999
.It 2
Gerrit
.Ar commit-msg
hook could not be successfully installed.
.It 34
Cannot query information about changesets.
.It 35
Cannot fetch information about the changeset to be downloaded.
.It 36
Changeset not found.
.It 37
Particular patchset cannot be fetched from the remote git repository.
.It 64
Cannot checkout downloaded patchset into the new branch.
.It 65
Cannot checkout downloaded patchset into existing branch.
.It 66
Cannot hard reset working directory and git index after download.
.It 67
Cannot switch to some other branch when trying to finish
the current branch.
.It 68
Cannot delete current branch.
.El
.Pp
Exit status larger than 31 indicates problem with
communication with Gerrit or remote Git repository,
exit status larger than 63 means there was a problem with
a local repository or a working copy.
.Pp
.Sh EXAMPLES
To fetch a remote change number 3004:
.Pp
.Bd -literal -offset indent
$ git-review -d 3004
Downloading refs/changes/04/3004/1 from gerrit into
review/someone/topic_name
Switched to branch 'review/someone/topic_name
$ git branch
  master
* review/author/topic_name
.Ed
.Pp
Gerrit looks up both name of the author and the topic name from Gerrit
to name a local branch. This facilitates easier identification of changes.
.Pp
To send a change for review and delete local branch afterwards:
.Bd -literal -offset indent
$ git-review -f
remote: Resolving deltas:   0% (0/8)
To ssh://username@review.example.com/departement/project.git
 * [new branch]      HEAD -> refs/for/master/topic_name
Switched to branch 'master'
Deleted branch 'review/someone/topic_name'
$ git branch
* master
.Ed
.Pp
An example 
.Pa .gitreview
configuration file for a project
.Pa department/project
hosted on
.Cm review.example.com
port
.Cm 29418
in the branch
.Cm master
:
.Bd -literal -offset indent
[gerrit]
host=review.example.com
port=29418
project=department/project.git
defaultbranch=master
.Ed
.Sh BUGS
Bug reports can be submitted to
.Lk https://launchpad.net/git-review
.Sh AUTHORS
.Nm
is maintained by
.An "OpenStack, LLC"
.Pp
This manpage has been enhanced by:
.An "Antoine Musso" Aq hashar@free.fr
.An "Marcin Cieslak" Aq saper@saper.info