forked from openstack-infra/git-review
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathgit-review.1
365 lines (364 loc) · 10.4 KB
/
git-review.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
.\" 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 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 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 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 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 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 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.
.Pp
Also can be used for
.Fl --compare
to skip automatic rebase of fetched reviews.
.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 gireview.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
.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 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 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.
.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.
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://[email protected]/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 [email protected]
.An "Marcin Cieslak" Aq [email protected]
.An "Pavel Sedlák" Aq [email protected]