478 lines
15 KiB
Groff
478 lines
15 KiB
Groff
.\" Uses mdoc(7). See `man 7 mdoc` for details about the syntax used here
|
|
.\"
|
|
.Dd June 12th, 2015
|
|
.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 uv
|
|
.Fl x Ar change
|
|
.Op Ar branch
|
|
.Nm
|
|
.Op Fl r Ar remote
|
|
.Op Fl uv
|
|
.Fl N Ar change
|
|
.Op Ar branch
|
|
.Nm
|
|
.Op Fl r Ar remote
|
|
.Op Fl uv
|
|
.Fl X Ar change
|
|
.Op Ar branch
|
|
.Nm
|
|
.Op Fl r Ar remote
|
|
.Op Fl uv
|
|
.Fl m
|
|
.Ar change\-ps\-range
|
|
.Op Ar branch
|
|
.Nm
|
|
.Op Fl r Ar remote
|
|
.Op Fl fnuv
|
|
.Fl s
|
|
.Op Ar branch
|
|
.Nm
|
|
.Op Fl fnuvDRT
|
|
.Op Fl r Ar remote
|
|
.Op Fl t Ar topic
|
|
.Op Fl \-reviewers Ar reviewer ...
|
|
.Op Ar branch
|
|
.Nm
|
|
.Fl l
|
|
.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 comprehend Gerrit, especially for
|
|
users that have recently switched to Git from another version
|
|
control system.
|
|
.Pp
|
|
.Ar change
|
|
can be
|
|
.Ar changeNumber
|
|
as obtained using
|
|
.Fl \-list
|
|
option, or it can be
|
|
.Ar changeNumber,patchsetNumber
|
|
for fetching exact patchset from the change.
|
|
In that case local branch name will have a \-patch[patchsetNumber] suffix.
|
|
.Pp
|
|
The following options are available:
|
|
.Bl -tag -width indent
|
|
.It Fl c , Fl \-compatible
|
|
Push changes to refs compatible with Gerrit of versions before 2.3.
|
|
.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 x Ar change , Fl \-cherrypick= Ns Ar change
|
|
Apply
|
|
.Ar change
|
|
from Gerrit and commit into the current local branch ("cherry pick").
|
|
No additional branch is created.
|
|
.Pp
|
|
This makes it possible to review a change without creating a local branch for
|
|
it. On the other hand, be aware: if you are not careful, this can easily result
|
|
in additional patch sets for dependent changes. Also, if the current branch is
|
|
different enough, the change may not apply at all or produce merge conflicts
|
|
that need to be resolved by hand.
|
|
.It Fl N Ar change , Fl \-cherrypickonly= Ns Ar change
|
|
Apply
|
|
.Ar change
|
|
from Gerrit
|
|
into the current working directory, add it to the staging area ("git index"), but do not commit it.
|
|
.Pp
|
|
This makes it possible to review a change without creating a local commit for
|
|
it. Useful if you want to merge several commits into one that will be submitted for review.
|
|
.Pp
|
|
If the current branch is different enough, the change may not apply at all
|
|
or produce merge conflicts that need to be resolved by hand.
|
|
.It Fl X Ar change , Fl \-cherrypickindicate= Ns Ar change
|
|
Apply
|
|
.Ar change
|
|
from Gerrit and commit into the current local branch ("cherry pick"),
|
|
indicating which commit this change was cherry\-picked from.
|
|
.Pp
|
|
This makes it possible to re\-review a change for a different branch without
|
|
creating a local branch for it.
|
|
.Pp
|
|
If the current branch is different enough, the change may not apply at all
|
|
or produce merge conflicts that need to be resolved by hand.
|
|
.It Fl i , Fl \-new\-changeid
|
|
Force the git-review to generate a new Change-Id, even if one already exists
|
|
in the changelog.
|
|
.It Fl m Ar change\-ps\-range , Fl \-compare= Ns Ar change\-ps\-range
|
|
Download the specified patchsets for
|
|
.Ar change
|
|
from Gerrit, rebase both on master and display differences (git\-diff).
|
|
.Pp
|
|
.Ar change\-ps\-range
|
|
can be specified as
|
|
.Ar changeNumber, Ns Ar oldPatchSetNumber Ns Op Ns Ar \-newPatchSetNumber
|
|
.Pp
|
|
.Ar oldPatchSetNumber
|
|
is mandatory, and if
|
|
.Ar newPatchSetNumber
|
|
is not specified, the latest patchset will be used.
|
|
.Pp
|
|
This makes it possible to easily compare what has changed from last time you
|
|
reviewed the proposed change.
|
|
.Pp
|
|
If the master branch is different enough, the rebase can produce merge conflicts.
|
|
If that happens rebasing will be aborted and diff displayed for not\-rebased branches.
|
|
You can also use
|
|
.Ar \-\-no\-rebase ( Ar \-R )
|
|
to always skip rebasing.
|
|
.It Fl f , Fl \-finish
|
|
Close down the local branch and switch back to the target branch on
|
|
successful submission.
|
|
.It Fl F , Fl \-force\-rebase
|
|
Force a rebase before doing anything else, even if not otherwise needed.
|
|
.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 T , Fl \-no\-topic
|
|
Submit review without topic.
|
|
.It Fl \-reviewers Ar reviewer ...
|
|
Subscribe one or more reviewers to the uploaded patch sets. Reviewers should be identifiable by Gerrit (usually use their Gerrit username or email address).
|
|
.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.
|
|
.Pp
|
|
Also can be used for
|
|
.Fl \-compare
|
|
to skip automatic rebase of fetched reviews.
|
|
.It Fl \-color Ar always|never|auto
|
|
Enable or disable a color output. Default is "auto".
|
|
.It Fl \-no\-color
|
|
Same thing as \-\-color=never.
|
|
.It Fl \-no\-custom\-script
|
|
Do not run scripts, installed as hooks/{action}-review, where action
|
|
is one of "pre", "draft", or "post".
|
|
.It Fl \-track
|
|
Choose the branch to submit the change against (and, if
|
|
rebasing, to rebase against) from the branch being tracked
|
|
(if a branch is being tracked), and set the tracking branch
|
|
when downloading a change to point to the remote and branch
|
|
against which patches should be submitted.
|
|
See gitreview.track configuration.
|
|
.It Fl \-no\-track
|
|
Ignore any branch being tracked by the current branch,
|
|
overriding gitreview.track.
|
|
This option is implied by providing a specific branch name
|
|
on the command line.
|
|
.It Fl \-use-pushurl
|
|
Use the pushurl option for the origin remote rather than conventional
|
|
separate Gerrit remotes.
|
|
.It Fl \-version
|
|
Print the version number and exit.
|
|
.El
|
|
.Sh CONFIGURATION
|
|
This utility can be configured by adding entries to Git configuration.
|
|
.Pp
|
|
The following configuration keys are supported:
|
|
.Bl -tag
|
|
.It gitreview.username
|
|
Default username used to access the repository. If not specified
|
|
in the Git configuration, Git remote or
|
|
.Pa .gitreview
|
|
file, the user will be prompted to specify the username.
|
|
.Pp
|
|
Example entry in the
|
|
.Pa .gitconfig
|
|
file:
|
|
.Bd -literal -offset indent
|
|
[gitreview]
|
|
username=\fImygerrituser\fP
|
|
.Ed
|
|
.It gitreview.scheme
|
|
This setting determines the default scheme (ssh/http/https) of gerrit remote
|
|
.It gitreview.host
|
|
This setting determines the default hostname of gerrit remote
|
|
.It gitreview.port
|
|
This setting determines the default port of gerrit remote
|
|
.It gitreview.project
|
|
This setting determines the default name of gerrit git repo
|
|
.It gitreview.remote
|
|
This setting determines the default name to use for gerrit remote
|
|
.It gitreview.branch
|
|
This setting determines the default branch
|
|
.It gitreview.track
|
|
Determines whether to prefer the currently-tracked branch (if any)
|
|
and the branch against which the changeset was submitted to Gerrit
|
|
(if there is exactly one such branch) to the defaultremote and
|
|
defaultbranch for submitting and rebasing against.
|
|
If the local topic branch is tracking a remote branch, the remote
|
|
and branch that the local topic branch is tracking should be used
|
|
for submit and rebase operations, rather than the defaultremote
|
|
and defaultbranch.
|
|
.Pp
|
|
When downloading a patch, creates the local branch to track the
|
|
appropriate remote and branch in order to choose that branch by
|
|
default when submitting modifications to that changeset.
|
|
.Pp
|
|
A value of 'true' or 'false' should be specified.
|
|
.Bl -tag
|
|
.It true
|
|
Do prefer the currently-tracked branch (if any) \- equivalent
|
|
to setting
|
|
.Fl \-track
|
|
when submitting changes.
|
|
.It false
|
|
Ignore tracking branches \- equivalent to setting
|
|
.Fl \-no\-track
|
|
(the default) or providing an explicit branch name when submitting
|
|
changes. This is the default value unless overridden by
|
|
.Pa .gitreview
|
|
file, and is implied by providing a specific branch name on the
|
|
command line.
|
|
.El
|
|
.It gitreview.rebase
|
|
This setting determines whether changes submitted will
|
|
be rebased to the newest state of the branch.
|
|
.Pp
|
|
A value of 'true' or 'false' should be specified.
|
|
.Bl -tag
|
|
.It false
|
|
Do not rebase changes on submit \- equivalent to setting
|
|
.Fl R
|
|
when submitting changes.
|
|
.It true
|
|
Do rebase changes on submit. This is the default value unless
|
|
overridden by
|
|
.Pa .gitreview
|
|
file.
|
|
.El
|
|
.Pp
|
|
This setting takes precedence over repository\-specific configuration
|
|
in the
|
|
.Pa .gitreview
|
|
file.
|
|
.El
|
|
.Bl -tag
|
|
.It color.review
|
|
Whether to use ANSI escape sequences to add color to the output displayed by
|
|
this command. Default value is determined by color.ui.
|
|
.Bl -tag
|
|
.It auto or true
|
|
If you want output to use color when written to the terminal (default with Git
|
|
1.8.4 and newer).
|
|
.It always
|
|
If you want all output to use color
|
|
.It never or false
|
|
If you wish not to use color for any output. (default with Git older than 1.8.4)
|
|
.El
|
|
.El
|
|
.Pp
|
|
.Nm
|
|
will query git credential system for Gerrit user/password when
|
|
authentication failed over http(s). Unlike git,
|
|
.Nm
|
|
does not persist Gerrit user/password in git credential system for security
|
|
purposes and git credential system configuration stays under user responsibility.
|
|
.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]
|
|
scheme=ssh
|
|
host=review.example.com
|
|
port=29418
|
|
project=department/project.git
|
|
defaultbranch=master
|
|
defaultremote=review
|
|
defaultrebase=0
|
|
track=0
|
|
.Ed
|
|
.Pp
|
|
When the same option is provided through FILES and CONFIGURATION, the
|
|
CONFIGURATION value wins.
|
|
.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 3
|
|
Could not parse malformed argument value or user input.
|
|
.It 32
|
|
Cannot fetch list of open changesets from Gerrit.
|
|
.It 33
|
|
Cannot parse list of open changesets received from Gerrit.
|
|
.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 38
|
|
Specified patchset number not found in the changeset.
|
|
.It 39
|
|
Invalid patchsets for comparison.
|
|
.It 40
|
|
Connection to Gerrit was closed.
|
|
.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.
|
|
.It 69
|
|
Requested patchset cannot be fully applied to the current branch. This exit
|
|
status will be returned when there are merge conflicts with the current branch.
|
|
Possible reasons include an attempt to apply patchset from the different branch
|
|
or code. This exit status will also be returned if the patchset is already
|
|
applied to the current branch.
|
|
.It 70
|
|
Cannot determine top level Git directory or .git subdirectory path.
|
|
.It 101
|
|
Unauthorized (401) http request done by git-review.
|
|
.It 104
|
|
Not Found (404) http request done by git-review.
|
|
.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
|
|
Exit status larger than or equal to 128 means internal
|
|
error in running the "git" command.
|
|
.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 fetch a remote patchset number 5 from change number 3004:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
$ git\-review \-d 3004,5
|
|
Downloading refs/changes/04/3004/5 from gerrit into
|
|
review/someone/topic_name\-patch5
|
|
Switched to branch 'review/someone/topic_name\-patch5
|
|
$ git branch
|
|
master
|
|
* review/author/topic_name\-patch5
|
|
.Ed
|
|
.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/department/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
|
|
.An "Pavel Sedlák" Aq psedlak@redhat.com
|