1GIT-REVIEW(1) BSD General Commands Manual GIT-REVIEW(1)
2
4 git-review — Submit changes to Gerrit for review
5
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 [--notify type] [branch]
15 git-review -l
16 git-review --version
17
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 re‐
22 cently switched to Git from another version control system.
23 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 The following options are available:
29 -d change, --download=change
31 Download change from Gerrit into a local branch. The branch will
32 be named after the patch author and the name of a topic. If the
33 local branch already exists, it will attempt to update with the
34 latest patchset for this change.
35 -x change, --cherrypick=change
37 Apply change from Gerrit and commit into the current local branch
38 ("cherry pick"). No additional branch is created.
39 This makes it possible to review a change without creating a lo‐
41 cal branch for it. On the other hand, be aware: if you are not
42 careful, this can easily result in additional patch sets for de‐
43 pendent changes. Also, if the current branch is different enough,
44 the change may not apply at all or produce merge conflicts that
45 need to be resolved by hand.
46 -N change, --cherrypickonly=change
48 Apply change from Gerrit into the current working directory, add
49 it to the staging area ("git index"), but do not commit it.
50 This makes it possible to review a change without creating a lo‐
52 cal commit for it. Useful if you want to merge several commits
53 into one that will be submitted for review.
54 If the current branch is different enough, the change may not ap‐
56 ply at all or produce merge conflicts that need to be resolved by
57 hand.
58 -X change, --cherrypickindicate=change
60 Apply change from Gerrit and commit into the current local branch
61 ("cherry pick"), indicating which commit this change was
62 cherry-picked from.
63 This makes it possible to re-review a change for a different
65 branch without creating a local branch for it.
66 If the current branch is different enough, the change may not ap‐
68 ply at all or produce merge conflicts that need to be resolved by
69 hand.
70 -i, --new-changeid
72 Force the git-review to generate a new Change-Id, even if one al‐
73 ready exists in the changelog.
74 -m change-ps-range, --compare=change-ps-range
76 Download the specified patchsets for change from Gerrit, rebase
77 both on master and display differences (git-diff).
78 change-ps-range can be specified as
80 changeNumber,oldPatchSetNumber[-newPatchSetNumber]
81 oldPatchSetNumber is mandatory, and if newPatchSetNumber is not
83 specified, the latest patchset will be used.
84 This makes it possible to easily compare what has changed from
86 last time you reviewed the proposed change.
87 If the master branch is different enough, the rebase can produce
89 merge conflicts. If that happens rebasing will be aborted and
90 diff displayed for not-rebased branches. You can also use
91 --no-rebase (-R) to always skip rebasing.
92 -f, --finish
94 Close down the local branch and switch back to the target branch
95 on successful submission.
96 -F, --force-rebase
98 Force a rebase before doing anything else, even if not otherwise
99 needed.
100 -n, --dry-run
102 Don't actually perform any commands that have direct effects.
103 Print them instead.
104 -r remote, --remote=remote
106 Git remote to use for Gerrit.
107 -s, --setup
109 Just run the repo setup commands but don't submit anything.
110 -t topic, --topic=topic
112 Sets the target topic for this change on the Gerrit server. If
113 not specified, a bug number from the commit summary will be used.
114 Alternatively, the local branch name will be used if different
115 from remote branch.
116 -T, --no-topic
118 Submit review without topic.
119 -p, --private
121 Send patch as a private patch ready for review. Gerrit versions
122 >= 2.15
123 -P, --remove-private
125 Send patch which already in private state to normal patch. Gerrit
126 versions >= 2.15
127 -w, --work-in-progress
129 Send patch as work in progress for Gerrit versions >= 2.15
130 -W, --ready
132 Send patch that is already work in progress as ready for review.
133 Gerrit versions >= 2.15
134 --reviewers reviewer ...
136 Subscribe one or more reviewers to the uploaded patch sets. Re‐
137 viewers should be identifiable by Gerrit (usually use their Ger‐
138 rit username or email address).
139 --notify type
141 Control to whom email notifications are sent. Possible values
142 are NONE, OWNER, OWNER_REVIEWERS, ALL (the last one is the de‐
143 fault).
144 -u, --update
146 Skip cached local copies and force updates from network re‐
147 sources.
148 -l, --list
150 List the available reviews on the Gerrit server for this project.
151 -y, --yes
153 Indicate that you do, in fact, understand if you are submitting
154 more than one patch.
155 -v, --verbose
157 Turns on more verbose output.
158 -R, --no-rebase
160 Do not automatically perform a rebase before submitting the
161 change to Gerrit.
162 When submitting a change for review, you will usually want it to
164 be based on the tip of upstream branch in order to avoid possible
165 conflicts. When amending a change and rebasing the new patchset,
166 the Gerrit web interface will show a difference between the two
167 patchsets which contains all commits in between. This may confuse
168 many reviewers that would expect to see a much simpler differ‐
169 ence.
170 Also can be used for --compare to skip automatic rebase of
172 fetched reviews.
173 --no-thin
175 Disable thin pushes when pushing to Gerrit. This should only be
176 used if you are currently experiencing unpack failures due to
177 missing trees. It should not be required in typical day to day
178 use.
179 --color always|never|auto
181 Enable or disable a color output. Default is "auto".
182 --no-color
184 Same thing as --color=never.
185 --no-custom-script
187 Do not run scripts, installed as hooks/{action}-review, where ac‐
188 tion is one of "pre" or "post".
189 --track
191 Choose the branch to submit the change against (and, if rebasing,
192 to rebase against) from the branch being tracked (if a branch is
193 being tracked), and set the tracking branch when downloading a
194 change to point to the remote and branch against which patches
195 should be submitted. See gitreview.track configuration.
196 --no-track
198 Ignore any branch being tracked by the current branch, overriding
199 gitreview.track. This option is implied by providing a specific
200 branch name on the command line.
201 --use-pushurl
203 Use the pushurl option for the origin remote rather than conven‐
204 tional separate Gerrit remotes.
205 --license
207 Print the license text and exit.
208 --version
210 Print the version number and exit.
211 --help Print the short help message and exit.
213
215 This utility can be configured by adding entries to Git configuration.
216 The following configuration keys are supported:
218 gitreview.username
220 Default username used to access the repository. If not specified
221 in the Git configuration, Git remote or .gitreview file, the user
222 will be prompted to specify the username.
223 Example entry in the .gitconfig file:
225 [gitreview]
227 username=mygerrituser
228 gitreview.scheme
230 This setting determines the default scheme (ssh/http/https) of
231 gerrit remote
232 gitreview.host
234 This setting determines the default hostname of gerrit remote
235 gitreview.port
237 This setting determines the default port of gerrit remote
238 gitreview.project
240 This setting determines the default name of gerrit git repo
241 gitreview.remote
243 This setting determines the default name to use for gerrit remote
244 gitreview.branch
246 This setting determines the default branch
247 gitreview.notopic
249 Set to true to never submit with a default topic
250 gitreview.track
252 Determines whether to prefer the currently-tracked branch (if
253 any) and the branch against which the changeset was submitted to
254 Gerrit (if there is exactly one such branch) to the defaultremote
255 and defaultbranch for submitting and rebasing against. If the
256 local topic branch is tracking a remote branch, the remote and
257 branch that the local topic branch is tracking should be used for
258 submit and rebase operations, rather than the defaultremote and
259 defaultbranch.
260 When downloading a patch, creates the local branch to track the
262 appropriate remote and branch in order to choose that branch by
263 default when submitting modifications to that changeset.
264 A value of 'true' or 'false' should be specified.
266 true Do prefer the currently-tracked branch (if any) - equiva‐
268 lent to setting --track when submitting changes.
269 false Ignore tracking branches - equivalent to setting
271 --no-track (the default) or providing an explicit branch
272 name when submitting changes. This is the default value
273 unless overridden by .gitreview file, and is implied by
274 providing a specific branch name on the command line.
275 gitreview.usepushurl
277 This setting determines whether to use a separate Git remote for
278 the Gerrit connection, or to set 'pushurl' on the remote 'ori‐
279 gin'.
280 A value of 'true' or 'false' should be specified.
282 false Do not use 'pushurl' and instead use a separate remote.
284 true Use 'pushurl' for interacting with Gerrit.
286 gitreview.rebase
288 This setting determines whether changes submitted will be rebased
289 to the newest state of the branch.
290 A value of 'true' or 'false' should be specified.
292 false Do not rebase changes on submit - equivalent to setting
294 -R when submitting changes.
295 true Do rebase changes on submit. This is the default value
297 unless overridden by .gitreview file.
298 This setting takes precedence over repository-specific configura‐
300 tion in the .gitreview file.
301 gitreview.branchauthor
303 This setting changes the look of the author part when naming the
304 local branch of a downloaded change. Value must be one of
305 "name", "email", or "username". Default is "name". See also the
306 --download option.
307 color.review
309 Whether to use ANSI escape sequences to add color to the output
310 displayed by this command. Default value is determined by
311 color.ui.
312 auto or true
314 If you want output to use color when written to the ter‐
315 minal (default with Git 1.8.4 and newer).
316 always If you want all output to use color
318 never or false
320 If you wish not to use color for any output. (default
321 with Git older than 1.8.4)
322 git-review will query git credential system for Gerrit user/password when
324 authentication failed over http(s). Unlike git, git-review does not per‐
325 sist Gerrit user/password in git credential system for security purposes
326 and git credential system configuration stays under user responsibility.
327
329 To use git-review with your project, it is recommended that you create a
330 file at the root of the repository named .gitreview and place information
331 about your Gerrit installation in it. The format is similar to the Win‐
332 dows .ini file format:
333 [gerrit]
335 host=hostname
336 port=TCP port number of gerrit
337 project=project name
338 defaultbranch=branch to work on
339 It is also possible to specify optional default name for the Git remote
341 using the defaultremote configuration parameter.
342 Setting defaultrebase to zero will make git-review not to rebase changes
344 by default (same as the -R command line option)
345 [gerrit]
347 scheme=ssh
348 host=review.example.com
349 port=29418
350 project=department/project.git
351 defaultbranch=master
352 defaultremote=review
353 defaultrebase=0
354 track=0
355 When the same option is provided through FILES and CONFIGURATION, the
357 CONFIGURATION value wins.
358
360 Normally, exit status is 0 if executed successfully. Exit status 1 indi‐
361 cates general error, sometimes more specific error codes are available:
362 2 Gerrit commit-msg hook could not be successfully installed.
364 3 Could not parse malformed argument value or user input.
366 32 Cannot fetch list of open changesets from Gerrit.
368 33 Cannot parse list of open changesets received from Gerrit.
370 34 Cannot query information about changesets.
372 35 Cannot fetch information about the changeset to be downloaded.
374 36 Changeset not found.
376 37 Particular patchset cannot be fetched from the remote git reposi‐
378 tory.
379 38 Specified patchset number not found in the changeset.
381 39 Invalid patchsets for comparison.
383 40 Connection to Gerrit was closed.
385 64 Cannot checkout downloaded patchset into the new branch.
387 65 Cannot checkout downloaded patchset into existing branch.
389 66 Cannot hard reset working directory and git index after download.
391 67 Cannot switch to some other branch when trying to finish the current
393 branch.
394 68 Cannot delete current branch.
396 69 Requested patchset cannot be fully applied to the current branch.
398 This exit status will be returned when there are merge conflicts
399 with the current branch. Possible reasons include an attempt to ap‐
400 ply patchset from the different branch or code. This exit status
401 will also be returned if the patchset is already applied to the cur‐
402 rent branch.
403 70 Cannot determine top level Git directory or .git subdirectory path.
405 101 Unauthorized (401) http request done by git-review.
407 104 Not Found (404) http request done by git-review.
409 Exit status larger than 31 indicates problem with communication with Ger‐
411 rit or remote Git repository, exit status larger than 63 means there was
412 a problem with a local repository or a working copy.
413 Exit status larger than or equal to 128 means internal error in running
415 the "git" command.
416
418 To fetch a remote change number 3004:
419 $ git-review -d 3004
421 Downloading refs/changes/04/3004/1 from gerrit into
422 review/someone/topic_name
423 Switched to branch 'review/someone/topic_name
424 $ git branch
425 master
426 * review/author/topic_name
427 Gerrit looks up both name of the author and the topic name from Gerrit to
429 name a local branch. This facilitates easier identification of changes.
430 To fetch a remote patchset number 5 from change number 3004:
432 $ git-review -d 3004,5
434 Downloading refs/changes/04/3004/5 from gerrit into
435 review/someone/topic_name-patch5
436 Switched to branch 'review/someone/topic_name-patch5
437 $ git branch
438 master
439 * review/author/topic_name-patch5
440 To send a change for review and delete local branch afterwards:
442 $ git-review -f
444 remote: Resolving deltas: 0% (0/8)
445 To ssh://username@review.example.com/department/project.git
446 * [new branch] HEAD -> refs/for/master/topic_name
447 Switched to branch 'master'
448 Deleted branch 'review/someone/topic_name'
449 $ git branch
450 * master
451 An example .gitreview configuration file for a project department/project
453 hosted on review.example.com port 29418 in the branch master :
454 [gerrit]
456 host=review.example.com
457 port=29418
458 project=department/project.git
459 defaultbranch=master
460
462 Bug reports can be submitted to
463 https://storyboard.openstack.org/#!/project/opendev/git-review
464
466 git-review is maintained by OpenDev Contributors
467 This manpage has been enhanced by:
469 Antoine Musso <hashar@free.fr>
470 Jeremy Stanley <fungi@yuggoth.org>
471 Marcin Cieslak <saper@saper.info>
472 Pavel Sedlák <psedlak@redhat.com>
473 July 21, 2022