1GIT-REVIEW(1)             BSD General Commands Manual            GIT-REVIEW(1)
2

NAME

4     git-review — Submit changes to Gerrit for review
5

SYNOPSIS

7     git-review [-r remote] [-uv] -d change [branch]
8     git-review [-r remote] [-uv] -x change [branch]
9     git-review [-r remote] [-uv] -N change [branch]
10     git-review [-r remote] [-uv] -X change [branch]
11     git-review [-r remote] [-uv] -m change-ps-range [branch]
12     git-review [-r remote] [-fnuv] -s [branch]
13     git-review [-fnuvDRT] [-r remote] [-t topic] [--reviewers reviewer ...]
14                [branch]
15     git-review -l
16     git-review --version
17

DESCRIPTION

19     git-review automates and streamlines some of the tasks involved with sub‐
20     mitting local changes to a Gerrit server for review. It is designed to
21     make it easier to comprehend Gerrit, especially for users that have
22     recently switched to Git from another version control system.
23
24     change can be changeNumber as obtained using --list option, or it can be
25     changeNumber,patchsetNumber for fetching exact patchset from the change.
26     In that case local branch name will have a -patch[patchsetNumber] suffix.
27
28     The following options are available:
29
30     -c, --compatible
31             Push changes to refs compatible with Gerrit of versions before
32             2.3.
33
34     -d change, --download=change
35             Download change from Gerrit into a local branch. The branch will
36             be named after the patch author and the name of a topic.  If the
37             local branch already exists, it will attempt to update with the
38             latest patchset for this change.
39
40     -x change, --cherrypick=change
41             Apply change from Gerrit and commit into the current local branch
42             ("cherry pick").  No additional branch is created.
43
44             This makes it possible to review a change without creating a
45             local branch for it. On the other hand, be aware: if you are not
46             careful, this can easily result in additional patch sets for
47             dependent changes. Also, if the current branch is different
48             enough, the change may not apply at all or produce merge con‐
49             flicts that need to be resolved by hand.
50
51     -N change, --cherrypickonly=change
52             Apply change from Gerrit into the current working directory, add
53             it to the staging area ("git index"), but do not commit it.
54
55             This makes it possible to review a change without creating a
56             local commit for it. Useful if you want to merge several commits
57             into one that will be submitted for review.
58
59             If the current branch is different enough, the change may not
60             apply at all or produce merge conflicts that need to be resolved
61             by hand.
62
63     -X change, --cherrypickindicate=change
64             Apply change from Gerrit and commit into the current local branch
65             ("cherry pick"), indicating which commit this change was
66             cherry-picked from.
67
68             This makes it possible to re-review a change for a different
69             branch without creating a local branch for it.
70
71             If the current branch is different enough, the change may not
72             apply at all or produce merge conflicts that need to be resolved
73             by hand.
74
75     -i, --new-changeid
76             Force the git-review to generate a new Change-Id, even if one
77             already exists in the changelog.
78
79     -m change-ps-range, --compare=change-ps-range
80             Download the specified  patchsets for change from Gerrit, rebase
81             both on master and display differences (git-diff).
82
83             change-ps-range can be specified as
84             changeNumber,oldPatchSetNumber[-newPatchSetNumber]
85
86             oldPatchSetNumber is mandatory, and if newPatchSetNumber is not
87             specified, the latest patchset will be used.
88
89             This makes it possible to easily compare what has changed from
90             last time you reviewed the proposed change.
91
92             If the master branch is different enough, the rebase can produce
93             merge conflicts.  If that happens rebasing will be aborted and
94             diff displayed for not-rebased branches.  You can also use
95             --no-rebase (-R) to always skip rebasing.
96
97     -f, --finish
98             Close down the local branch and switch back to the target branch
99             on successful submission.
100
101     -F, --force-rebase
102             Force a rebase before doing anything else, even if not otherwise
103             needed.
104
105     -n, --dry-run
106             Don't actually perform any commands that have direct effects.
107             Print them instead.
108
109     -r remote, --remote=remote
110             Git remote to use for Gerrit.
111
112     -s, --setup
113             Just run the repo setup commands but don't submit anything.
114
115     -t topic, --topic=topic
116             Sets the target topic for this change on the Gerrit server.  If
117             not specified, a bug number from the commit summary will be used.
118             Alternatively, the local branch name will be used if different
119             from remote branch.
120
121     -T, --no-topic
122             Submit review without topic.
123
124     --reviewers reviewer ...
125             Subscribe one or more reviewers to the uploaded patch sets.
126             Reviewers should be identifiable by Gerrit (usually use their
127             Gerrit username or email address).
128
129     -u, --update
130             Skip cached local copies and force updates from network
131             resources.
132
133     -l, --list
134             List the available reviews on the Gerrit server for this project.
135
136     -y, --yes
137             Indicate that you do, in fact, understand if you are submitting
138             more than one patch.
139
140     -v, --verbose
141             Turns on more verbose output.
142
143     -D, --draft
144             Submit review as a draft. Requires Gerrit 2.3 or newer.
145
146     -R, --no-rebase
147             Do not automatically perform a rebase before submitting the
148             change to Gerrit.
149
150             When submitting a change for review, you will usually want it to
151             be based on the tip of upstream branch in order to avoid possible
152             conflicts. When amending a change and rebasing the new patchset,
153             the Gerrit web interface will show a difference between the two
154             patchsets which contains all commits in between. This may confuse
155             many reviewers that would expect to see a much simpler differ‐
156             ence.
157
158             Also can be used for --compare to skip automatic rebase of
159             fetched reviews.
160
161     --color always|never|auto
162             Enable or disable a color output. Default is "auto".
163
164     --no-color
165             Same thing as --color=never.
166
167     --no-custom-script
168             Do not run scripts, installed as hooks/{action}-review, where
169             action is one of "pre", "draft", or "post".
170
171     --track
172             Choose the branch to submit the change against (and, if rebasing,
173             to rebase against) from the branch being tracked (if a branch is
174             being tracked), and set the tracking branch when downloading a
175             change to point to the remote and branch against which patches
176             should be submitted.  See gitreview.track configuration.
177
178     --no-track
179             Ignore any branch being tracked by the current branch, overriding
180             gitreview.track.  This option is implied by providing a specific
181             branch name on the command line.
182
183     --use-pushurl
184             Use the pushurl option for the origin remote rather than conven‐
185             tional separate Gerrit remotes.
186
187     --version
188             Print the version number and exit.
189

CONFIGURATION

191     This utility can be configured by adding entries to Git configuration.
192
193     The following configuration keys are supported:
194
195     gitreview.username
196                   Default username used to access the repository. If not
197                   specified in the Git configuration, Git remote or
198                   .gitreview file, the user will be prompted to specify the
199                   username.
200
201                   Example entry in the .gitconfig file:
202
203                         [gitreview]
204                         username=mygerrituser
205
206     gitreview.scheme
207                   This setting determines the default scheme (ssh/http/https)
208                   of gerrit remote
209
210     gitreview.host
211                   This setting determines the default hostname of gerrit
212                   remote
213
214     gitreview.port
215                   This setting determines the default port of gerrit remote
216
217     gitreview.project
218                   This setting determines the default name of gerrit git repo
219
220     gitreview.remote
221                   This setting determines the default name to use for gerrit
222                   remote
223
224     gitreview.branch
225                   This setting determines the default branch
226
227     gitreview.track
228                   Determines whether to prefer the currently-tracked branch
229                   (if any) and the branch against which the changeset was
230                   submitted to Gerrit (if there is exactly one such branch)
231                   to the defaultremote and defaultbranch for submitting and
232                   rebasing against.  If the local topic branch is tracking a
233                   remote branch, the remote and branch that the local topic
234                   branch is tracking should be used for submit and rebase
235                   operations, rather than the defaultremote and default‐
236                   branch.
237
238                   When downloading a patch, creates the local branch to track
239                   the appropriate remote and branch in order to choose that
240                   branch by default when submitting modifications to that
241                   changeset.
242
243                   A value of 'true' or 'false' should be specified.
244
245                   true          Do prefer the currently-tracked branch (if
246                                 any) - equivalent to setting --track when
247                                 submitting changes.
248
249                   false         Ignore tracking branches - equivalent to set‐
250                                 ting --no-track (the default) or providing an
251                                 explicit branch name when submitting changes.
252                                 This is the default value unless overridden
253                                 by .gitreview file, and is implied by provid‐
254                                 ing a specific branch name on the command
255                                 line.
256
257     gitreview.usepushurl
258                   This setting determines whether to use a separate Git
259                   remote for the Gerrit connection, or to set 'pushurl' on
260                   the remote 'origin'.
261
262                   A value of 'true' or 'false' should be specified.
263
264                   false         Do not use 'pushurl' and instead use a sepa‐
265                                 rate remote.
266
267                   true          Use 'pushurl' for interacting with Gerrit.
268
269     gitreview.rebase
270                   This setting determines whether changes submitted will be
271                   rebased to the newest state of the branch.
272
273                   A value of 'true' or 'false' should be specified.
274
275                   false         Do not rebase changes on submit - equivalent
276                                 to setting -R when submitting changes.
277
278                   true          Do rebase changes on submit. This is the
279                                 default value unless overridden by .gitreview
280                                 file.
281
282                   This setting takes precedence over repository-specific con‐
283                   figuration in the .gitreview file.
284
285     color.review  Whether to use ANSI escape sequences to add color to the
286                   output displayed by this command. Default value is deter‐
287                   mined by color.ui.
288
289                   auto or true  If you want output to use color when written
290                                 to the terminal (default with Git 1.8.4 and
291                                 newer).
292
293                   always        If you want all output to use color
294
295                   never or false
296                                 If you wish not to use color for any output.
297                                 (default with Git older than 1.8.4)
298
299     git-review will query git credential system for Gerrit user/password when
300     authentication failed over http(s). Unlike git, git-review does not per‐
301     sist Gerrit user/password in git credential system for security purposes
302     and git credential system configuration stays under user responsibility.
303

FILES

305     To use git-review with your project, it is recommended that you create a
306     file at the root of the repository named .gitreview and place information
307     about your Gerrit installation in it.  The format is similar to the Win‐
308     dows .ini file format:
309
310           [gerrit]
311           host=hostname
312           port=TCP port number of gerrit
313           project=project name
314           defaultbranch=branch to work on
315
316     It is also possible to specify optional default name for the Git remote
317     using the defaultremote configuration parameter.
318
319     Setting defaultrebase to zero will make git-review not to rebase changes
320     by default (same as the -R command line option)
321
322           [gerrit]
323           scheme=ssh
324           host=review.example.com
325           port=29418
326           project=department/project.git
327           defaultbranch=master
328           defaultremote=review
329           defaultrebase=0
330           track=0
331
332     When the same option is provided through FILES and CONFIGURATION, the
333     CONFIGURATION value wins.
334

DIAGNOSTICS

336     Normally, exit status is 0 if executed successfully.  Exit status 1 indi‐
337     cates general error, sometimes more specific error codes are available:
338
339     2    Gerrit commit-msg hook could not be successfully installed.
340
341     3    Could not parse malformed argument value or user input.
342
343     32   Cannot fetch list of open changesets from Gerrit.
344
345     33   Cannot parse list of open changesets received from Gerrit.
346
347     34   Cannot query information about changesets.
348
349     35   Cannot fetch information about the changeset to be downloaded.
350
351     36   Changeset not found.
352
353     37   Particular patchset cannot be fetched from the remote git reposi‐
354          tory.
355
356     38   Specified patchset number not found in the changeset.
357
358     39   Invalid patchsets for comparison.
359
360     40   Connection to Gerrit was closed.
361
362     64   Cannot checkout downloaded patchset into the new branch.
363
364     65   Cannot checkout downloaded patchset into existing branch.
365
366     66   Cannot hard reset working directory and git index after download.
367
368     67   Cannot switch to some other branch when trying to finish the current
369          branch.
370
371     68   Cannot delete current branch.
372
373     69   Requested patchset cannot be fully applied to the current branch.
374          This exit status will be returned when there are merge conflicts
375          with the current branch.  Possible reasons include an attempt to
376          apply patchset from the different branch or code.  This exit status
377          will also be returned if the patchset is already applied to the cur‐
378          rent branch.
379
380     70   Cannot determine top level Git directory or .git subdirectory path.
381
382     101  Unauthorized (401) http request done by git-review.
383
384     104  Not Found (404) http request done by git-review.
385
386     Exit status larger than 31 indicates problem with communication with Ger‐
387     rit or remote Git repository, exit status larger than 63 means there was
388     a problem with a local repository or a working copy.
389
390     Exit status larger than or equal to 128 means internal error in running
391     the "git" command.
392

EXAMPLES

394     To fetch a remote change number 3004:
395
396           $ git-review -d 3004
397           Downloading refs/changes/04/3004/1 from gerrit into
398           review/someone/topic_name
399           Switched to branch 'review/someone/topic_name
400           $ git branch
401             master
402           * review/author/topic_name
403
404     Gerrit looks up both name of the author and the topic name from Gerrit to
405     name a local branch. This facilitates easier identification of changes.
406
407     To fetch a remote patchset number 5 from change number 3004:
408
409           $ git-review -d 3004,5
410           Downloading refs/changes/04/3004/5 from gerrit into
411           review/someone/topic_name-patch5
412           Switched to branch 'review/someone/topic_name-patch5
413           $ git branch
414             master
415           * review/author/topic_name-patch5
416
417     To send a change for review and delete local branch afterwards:
418
419           $ git-review -f
420           remote: Resolving deltas:   0% (0/8)
421           To ssh://username@review.example.com/department/project.git
422            * [new branch]      HEAD -> refs/for/master/topic_name
423           Switched to branch 'master'
424           Deleted branch 'review/someone/topic_name'
425           $ git branch
426           * master
427
428     An example .gitreview configuration file for a project department/project
429     hosted on review.example.com port 29418 in the branch master :
430
431           [gerrit]
432           host=review.example.com
433           port=29418
434           project=department/project.git
435           defaultbranch=master
436

BUGS

438     Bug reports can be submitted to
439           https://launchpad.net/git-review
440

AUTHORS

442     git-review is maintained by OpenStack, LLC
443
444     This manpage has been enhanced by:
445     Antoine Musso <hashar@free.fr>
446     Marcin Cieslak <saper@saper.info>
447     Pavel Sedlák <psedlak@redhat.com>
448
449                                June 12th, 2015
Impressum