about summary refs log blame commit diff
path: root/third_party/go/git-appraise/docs/tutorial.md
blob: 6f95bb7e2ff527bcbfd12ba7f4300e8061515003 (plain) (tree)
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
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404



















































































































































































































































































































































































































                                                                                                                                                                                                          
# Getting started with git-appraise

This file gives an example code-review workflow using git-appraise. It starts
with cloning a repository and goes all the way through to browsing
your submitted commits.

The git-appraise tool is largely agnostic of what workflow you use, so feel
free to change things to your liking, but this particular workflow should help
you get started.

## Cloning your repository

Since you're using a code review tool, we'll assume that you have a URL that
you can push to and pull from in order to collaborate with the rest of your team.

First we'll create our local clone of the repository:
```shell
git clone ${URL} example-repo
cd example-repo
```

If you are starting from an empty repository, then it's a good practice to add a
README file explaining the purpose of the repository:

```shell
echo '# Example Repository' > README.md
git add README.md
git commit -m 'Added a README file to the repo'
git push
```

## Creating our first review

Generally, reviews in git-appraise are used to decide if the code in one branch
(called the "source") is ready to merge into another branch (called the
"target"). The meaning of each branch and the policies around merging into a
branch vary from team to team, but for this example we'll use a simple practice
called [GitHub Flow](https://guides.github.com/introduction/flow/).

Specifically, we'll create a new branch for a particular feature, review the
changes to that branch against our master branch, and then delete the feature
branch once we are done.

### Creating our change

Create the feature branch:
```shell
git checkout -b ${USER}/getting-started
git push --set-upstream origin ${USER}/getting-started
```

... And make some changes to it:
```shell
echo "This is an example repository used for coming up to speed" >> README.md
git commit -a -m "Added an explanation to the README file"
git push
```

### Requesting the review

Up to this point we've only used the regular commands that come with git. Now,
we will use git-appraise to perform a review:

Request a review:
```shell
git appraise request
```

The output of this will be a summary of the newly requested review:
```
Review requested:
Commit: 1e6eb14c8014593843c5b5f29377585e4ed55304
Target Ref: refs/heads/master
Review Ref: refs/heads/ojarjur/getting-started
Message: "Added an explanation to the README file"
```

Show the details of the current review:
```shell
git appraise show
```

```
[pending] 1e6eb14c8014
  Added an explanation to the README file
  "refs/heads/ojarjur/getting-started" -> "refs/heads/master"
  reviewers: ""
  requester: "ojarjur@google.com"
  build status: unknown
  analyses:  No analyses available
  comments (0 threads):
```

Show the changes included in the review:
```shell
git appraise show --diff
```

```
diff --git a/README.md b/README.md
index 08fde78..85c4208 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,2 @@
 # Example Repository
+This is an example repository used for coming up to speed
```

### Sending our updates to the remote repository

Before a teammate can review our change, we have to make it available to them.
This involves pushing both our commits, and our code review data to the remote
repository:
```shell
git push
git appraise pull
git appraise push
```

The command `git appraise pull` is used to make sure that our local code review
data includes everything from the remote repo before we try to push our changes
back to it. If you forget to run this command, then the subsequent call to
`git appraise push` might fail with a message that the push was rejected. If
that happens, simply run `git appraise pull` and try again.

## Reviewing the change

Your teammates can review your changes using the same tool.

Fetch the current data from the remote repository:
```shell
git fetch origin
git appraise pull
```

List the open reviews:
```shell
git appraise list
```

The output of this command will be a list of entries formatted like this:
```
Loaded 1 open reviews:
[pending] 1e6eb14c8014
  Added an explanation to the README file
```

The text within the square brackets is the status of a review, and for open
reviews will be one of "pending", "accepted", or "rejected". The text which
follows the status is the hash of the first commit in the review. This is
used to uniquely identify reviews, and most git-appraise commands will accept
this hash as an argument in order to select the review to handle.

For instance, we can see the details of a specific review using the "show"
subcommand:
```shell
git appraise show 1e6eb14c8014
```

```
[pending] 1e6eb14c8014
  Added an explanation to the README file
  "refs/heads/ojarjur/getting-started" -> "refs/heads/master"
  reviewers: ""
  requester: "ojarjur@google.com"
  build status: unknown
  analyses:  No analyses available
  comments (0 threads):
```

... or, we can see the diff of the changes under review:
```shell
git appraise show --diff 1e6eb14c8014
```

```
diff --git a/README.md b/README.md
index 08fde78..85c4208 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,2 @@
 # Example Repository
+This is an example repository used for coming up to speed
```

Comments can be added either for the entire review, or on individual lines:
```shell
git appraise comment -f README.md -l 2 -m "Ah, so that's what this is" 1e6eb14c8014
```

These comments then show up in the output of `git appraise show`:
```shell
git appraise show 1e6eb14c8014
```

```
[pending] 1e6eb14c8014
  Added an explanation to the README file
  "refs/heads/ojarjur/getting-started" -> "refs/heads/master"
  reviewers: ""
  requester: "ojarjur@google.com"
  build status: unknown
  analyses:  No analyses available
  comments (1 threads):
    "README.md"@1e6eb14c8014
    |# Example Repository
    |This is an example repository used for coming up to speed
    comment: bd4c11ecafd443c9d1dde6035e89804160cd7487
      author: ojarjur@google.com
      time:   Fri Dec 18 10:58:54 PST 2015
      status: fyi
      Ah, so that's what this is
```

Comments initially only exist in your local repository, so to share them
with the rest of your team you have to push your review changes back:

```shell
git appraise pull
git appraise push
```

When the change is ready to be merged, you indicate that by accepting the
review:

```shell
git appraise accept 1e6eb14c8014
git appraise pull
git appraise push
```

The updated status of the review will be visible in the output of "show":
```shell
git appraise show 1e6eb14c8014
```

```
[accepted] 1e6eb14c8014
  Added an explanation to the README file
  "refs/heads/ojarjur/getting-started" -> "refs/heads/master"
  reviewers: ""
  requester: "ojarjur@google.com"
  build status: unknown
  analyses:  No analyses available
  comments (2 threads):
    "README.md"@1e6eb14c8014
    |# Example Repository
    |This is an example repository used for coming up to speed
    comment: bd4c11ecafd443c9d1dde6035e89804160cd7487
      author: ojarjur@google.com
      time:   Fri Dec 18 10:58:54 PST 2015
      status: fyi
      Ah, so that's what this is
    comment: 4034c60e6ed6f24b01e9a581087d1ab86d376b81
      author: ojarjur@google.com
      time:   Fri Dec 18 11:02:45 PST 2015
      status: fyi
```

## Submitting the change

Once a review has been accepted, you can merge it with the tool:

```shell
git appraise submit --merge 1e6eb14c8014
git push
```

The submit command will pop up a text editor where you can edit the default
merge message. That message will be used to create a new commit that is a
merge of the previous commit on the master branch, and the history of all
of your changes to the review. You can see what this looks like using
the `git log --graph` command:

```
*   commit 3a4d1b8cd264b921c858185f2c36aac283b45e49
|\  Merge: b404fa3 1e6eb14
| | Author: Omar Jarjur <ojarjur@google.com>
| | Date:   Fri Dec 18 11:06:24 2015 -0800
| | 
| |     Submitting review 1e6eb14c8014
| |     
| |     Added an explanation to the README file
| |   
| * commit 1e6eb14c8014593843c5b5f29377585e4ed55304
|/  Author: Omar Jarjur <ojarjur@google.com>
|   Date:   Fri Dec 18 10:49:56 2015 -0800
|   
|       Added an explanation to the README file
|  
* commit b404fa39ae98950d95ab06012191f58507e51d12
  Author: Omar Jarjur <ojarjur@google.com>
  Date:   Fri Dec 18 10:48:06 2015 -0800
  
      Added a README file to the repo
```

This is sometimes called a "merge bubble". When the review is simply accepted
as is, these do not add much value. However, reviews often go through several
rounds of changes before they are accepted. By using these merge commits, we
can preserve both the full history of individual reviews, and the high-level
(review-based) history of the repository.

This can be seen with the history of git-appraise itself. We can see the high
level review history using `git log --first-parent`:

```
commit 83c4d770cfde25c943de161c0cac54d714b7de38
Merge: 9a607b8 931d1b4
Author: Omar Jarjur <ojarjur@google.com>
Date:   Fri Dec 18 09:46:10 2015 -0800

    Submitting review 8cb887077783
    
    Fix a bug where requesting a review would fail with an erroneous message.
    
    We were figuring out the set of commits to include in a review by
    listing the commits between the head of the target ref and the head of
    the source ref. However, this only works if the source ref is a
    fast-forward of the target ref.
    
    This commit changes it so that we use the merge-base of the target and
    source refs as the starting point instead of the target ref.

commit 9a607b8529d7483e5b323303c73da05843ff3ca9
Author: Harry Lawrence <hazbo@gmx.com>
Date:   Fri Dec 18 10:24:00 2015 +0000

    Added links to Eclipse and Jenkins plugins
    
    As suggested in #11

commit 8876cfff2ed848d50cb559c05d44e11b95ca791c
Merge: 00c0e82 1436c83
Author: Omar Jarjur <ojarjur@google.com>
Date:   Thu Dec 17 12:46:32 2015 -0800

    Submitting review 09aecba64027
    
    Force default git editor when omitting -m
    For review comments, the absence of the -m flag will now attempt to load the
    user's default git editor.
    
    i.e. git appraise comment c0a643ff39dd
    
    An initial draft as discussed in #8
    
    I'm still not sure whether or not the file that is saved is in the most appropriate place or not. I like the idea of it being relative to the project although it could have gone in `/tmp` I suppose.

commit 00c0e827e5b86fb9d200f474d4f65f43677cbc6c
Merge: 31209ce 41fde0b
Author: Omar Jarjur <ojarjur@google.com>
Date:   Wed Dec 16 17:10:06 2015 -0800

    Submitting review 2c9bff89f0f8
    
    Improve the error messages returned when a git command fails.
    
    Previously, we were simply cascading the error returned by the instance
    of exec.Command. However, that winds up just being something of the form
    "exit status 128", with all of the real error message going to the
    Stderr field.
    
    As such, this commit changes the behavior to save the data written to
    stderr, and use it to construct a new error to return.

...
```

Here you see a linear view of the reviews that have been submitted, but if we
run the command `git log --oneline --graph`, then we can see that the full
history of each individual review is also available:

```
*   83c4d77 Submitting review 8cb887077783
|\  
| *   931d1b4 Merge branch 'master' into ojarjur/fix-request-bug
| |\  
| |/  
|/|   
* | 9a607b8 Added links to Eclipse and Jenkins plugins
| *   c7be567 Merge branch 'master' into ojarjur/fix-request-bug
| |\  
| |/  
|/|   
* |   8876cff Submitting review 09aecba64027
|\ \  
| * | 1436c83 Using git var GIT_EDITOR rather than git config
| * | 09aecba Force default git editor when omitting -m
|/ /  
| * 8cb8870 Fix a bug where requesting a review would fail with an erroneous message.
|/  
*   00c0e82 Submitting review 2c9bff89f0f8
...
```

## Cleaning up

Now that our feature branch has been merged into master, we can delete it:

```shell
git branch -d ${USER}/getting-started
git push origin --delete ${USER}/getting-started
```