OLD | NEW |
1 '\" t | 1 '\" t |
2 .\" Title: depot_tools_tutorial | 2 .\" Title: depot_tools_tutorial |
3 .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] | 3 .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] |
4 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> | 4 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> |
5 .\" Date: 04/10/2014 | 5 .\" Date: 04/14/2014 |
6 .\" Manual: Chromium depot_tools Manual | 6 .\" Manual: Chromium depot_tools Manual |
7 .\" Source: depot_tools bec7be9 | 7 .\" Source: depot_tools e722300 |
8 .\" Language: English | 8 .\" Language: English |
9 .\" | 9 .\" |
10 .TH "DEPOT_TOOLS_TUTORIAL" "7" "04/10/2014" "depot_tools bec7be9" "Chromium depo
t_tools Manual" | 10 .TH "DEPOT_TOOLS_TUTORIAL" "7" "04/14/2014" "depot_tools e722300" "Chromium depo
t_tools Manual" |
11 .\" ----------------------------------------------------------------- | 11 .\" ----------------------------------------------------------------- |
12 .\" * Define some portability stuff | 12 .\" * Define some portability stuff |
13 .\" ----------------------------------------------------------------- | 13 .\" ----------------------------------------------------------------- |
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
15 .\" http://bugs.debian.org/507673 | 15 .\" http://bugs.debian.org/507673 |
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html | 16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
18 .ie \n(.g .ds Aq \(aq | 18 .ie \n(.g .ds Aq \(aq |
19 .el .ds Aq ' | 19 .el .ds Aq ' |
20 .\" ----------------------------------------------------------------- | 20 .\" ----------------------------------------------------------------- |
(...skipping 35 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
56 .RE | 56 .RE |
57 .sp | 57 .sp |
58 .RS 4 | 58 .RS 4 |
59 .ie n \{\ | 59 .ie n \{\ |
60 \h'-04'\(bu\h'+03'\c | 60 \h'-04'\(bu\h'+03'\c |
61 .\} | 61 .\} |
62 .el \{\ | 62 .el \{\ |
63 .sp -1 | 63 .sp -1 |
64 .IP \(bu 2.3 | 64 .IP \(bu 2.3 |
65 .\} | 65 .\} |
66 TL;DR Walkthrough | 66 TL;DR |
67 .RE | 67 .RE |
68 .sp | 68 .sp |
69 .RS 4 | 69 .RS 4 |
70 .ie n \{\ | 70 .ie n \{\ |
71 \h'-04'\(bu\h'+03'\c | 71 \h'-04'\(bu\h'+03'\c |
72 .\} | 72 .\} |
73 .el \{\ | 73 .el \{\ |
74 .sp -1 | 74 .sp -1 |
75 .IP \(bu 2.3 | 75 .IP \(bu 2.3 |
76 .\} | 76 .\} |
(...skipping 26 matching lines...) Expand all Loading... |
103 .ie n \{\ | 103 .ie n \{\ |
104 \h'-04'\(bu\h'+03'\c | 104 \h'-04'\(bu\h'+03'\c |
105 .\} | 105 .\} |
106 .el \{\ | 106 .el \{\ |
107 .sp -1 | 107 .sp -1 |
108 .IP \(bu 2.3 | 108 .IP \(bu 2.3 |
109 .\} | 109 .\} |
110 Managing dependent CLs | 110 Managing dependent CLs |
111 .RE | 111 .RE |
112 .sp | 112 .sp |
| 113 .RS 4 |
| 114 .ie n \{\ |
| 115 \h'-04'\(bu\h'+03'\c |
| 116 .\} |
| 117 .el \{\ |
| 118 .sp -1 |
| 119 .IP \(bu 2.3 |
| 120 .\} |
| 121 Example Walkthrough |
| 122 .RE |
| 123 .sp |
113 Please refer to the manpages (or \-\-help output) for details about any of the c
ommands mentioned in this tutorial\&. | 124 Please refer to the manpages (or \-\-help output) for details about any of the c
ommands mentioned in this tutorial\&. |
114 .if n \{\ | 125 .if n \{\ |
115 .sp | 126 .sp |
116 .\} | 127 .\} |
117 .RS 4 | 128 .RS 4 |
118 .it 1 an-trap | 129 .it 1 an-trap |
119 .nr an-no-space-flag 1 | 130 .nr an-no-space-flag 1 |
120 .nr an-break-flag 1 | 131 .nr an-break-flag 1 |
121 .br | 132 .br |
122 .ps +1 | 133 .ps +1 |
(...skipping 117 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
240 \fB$ git config \-\-global user\&.email \(lqjdoe@email\&.com\(rq\fR | 251 \fB$ git config \-\-global user\&.email \(lqjdoe@email\&.com\(rq\fR |
241 \fB$ git config \-\-global core\&.autocrlf false\fR | 252 \fB$ git config \-\-global core\&.autocrlf false\fR |
242 \fB$ git config \-\-global core\&.filemode false\fR | 253 \fB$ git config \-\-global core\&.filemode false\fR |
243 \fB$\fR # and for fun! | 254 \fB$\fR # and for fun! |
244 \fB$ git config \-\-global color\&.ui true\fR | 255 \fB$ git config \-\-global color\&.ui true\fR |
245 .fi | 256 .fi |
246 .if n \{\ | 257 .if n \{\ |
247 .RE | 258 .RE |
248 .\} | 259 .\} |
249 .sp | 260 .sp |
| 261 .SH "TL;DR" |
| 262 .sp |
| 263 .if n \{\ |
| 264 .RS 4 |
| 265 .\} |
| 266 .nf |
| 267 \fB$\fR # get the code |
| 268 \fB$\fR # In an empty directory: |
| 269 \fB$ fetch {chromium,blink,\&.\&.\&.}\fR |
| 270 |
| 271 \fB$\fR # Update third_party repos and run pre\-compile hooks |
| 272 \fB$ gclient sync\fR |
| 273 |
| 274 \fB$\fR # Make a new change and upload it for review |
| 275 \fB$ git new\-branch branchname\fR |
| 276 \fB$\fR # repeat: [edit, git add, git commit] |
| 277 \fB$ git cl upload\fR |
| 278 |
| 279 \fB$\fR # After change is reviewed, commit with the CQ |
| 280 \fB$ git cl set_commit\fR |
| 281 \fB$\fR # Note that the committed hash which lands will /not/ match the |
| 282 \fB$\fR # commit hashes of your local branch\&. |
| 283 .fi |
| 284 .if n \{\ |
| 285 .RE |
| 286 .\} |
| 287 .sp |
250 .SH "GETTING THE CODE" | 288 .SH "GETTING THE CODE" |
251 .sp | 289 .sp |
252 Pick an empty directory and run one of the following: | 290 Pick an empty directory and run one of the following: |
253 .sp | 291 .sp |
254 .if n \{\ | 292 .if n \{\ |
255 .RS 4 | 293 .RS 4 |
256 .\} | 294 .\} |
257 .nf | 295 .nf |
258 \fB$ fetch chromium\fR # Basic checkout for desktop Chromium | 296 \fB$ fetch chromium\fR # Basic checkout for desktop Chromium |
259 \fB$ fetch blink\fR # Chromium code with Blink checked out to tip\-of\-tree | 297 \fB$ fetch blink\fR # Chromium code with Blink checked out to tip\-of\-tree |
(...skipping 31 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
291 .RE | 329 .RE |
292 .\} | 330 .\} |
293 .sp | 331 .sp |
294 .sp | 332 .sp |
295 And finally: | 333 And finally: |
296 .sp | 334 .sp |
297 .if n \{\ | 335 .if n \{\ |
298 .RS 4 | 336 .RS 4 |
299 .\} | 337 .\} |
300 .nf | 338 .nf |
301 \fB$ gclient sync\fR \fB(1)\fR | 339 \fB$ gclient sync\fR |
302 .fi | 340 .fi |
303 .if n \{\ | 341 .if n \{\ |
304 .RE | 342 .RE |
305 .\} | 343 .\} |
306 .sp | 344 .sp |
307 .sp | 345 .sp |
308 \fB1. \fRThis will pull all dependencies of the Chromium src checkout\&. You wil
l need to run this any time you update the main src checkout\&. | 346 This will pull all dependencies of the Chromium src checkout\&. You will need to
run this any time you update the main src checkout\&. |
| 347 .SH "CREATING / UPLOADING A CL" |
| 348 .if n \{\ |
| 349 .sp |
| 350 .\} |
| 351 .RS 4 |
| 352 .it 1 an-trap |
| 353 .nr an-no-space-flag 1 |
| 354 .nr an-break-flag 1 |
309 .br | 355 .br |
310 .SH "TL;DR WALKTHROUGH" | 356 .ps +1 |
| 357 \fBNote\fR |
| 358 .ps -1 |
| 359 .br |
| 360 .sp |
| 361 The remainder of the tutorial assumes that your current working directory is the
src/ folder mentioned in Getting the code\&. |
| 362 .sp .5v |
| 363 .RE |
| 364 .sp |
| 365 Each CL corresponds exactly with a single branch in git\&. Any time you want to
begin a new CL, just: |
| 366 .sp |
| 367 .if n \{\ |
| 368 .RS 4 |
| 369 .\} |
| 370 .nf |
| 371 \fB$ git new\-branch <branch_name>\fR |
| 372 .fi |
| 373 .if n \{\ |
| 374 .RE |
| 375 .\} |
| 376 .sp |
| 377 .sp |
| 378 This will create and checkout a new branch named branch_name which will track th
e default upstream (which is origin/master)\&. See \fBgit-new-branch\fR(1) for m
ore features, such as the ability to track \fILKGR\fR\&. |
| 379 .sp |
| 380 Commit as many changes as you like to this branch\&. When you want to upload it
for review, run: |
| 381 .sp |
| 382 .if n \{\ |
| 383 .RS 4 |
| 384 .\} |
| 385 .nf |
| 386 \fB$ git cl upload\fR |
| 387 .fi |
| 388 .if n \{\ |
| 389 .RE |
| 390 .\} |
| 391 .sp |
| 392 .sp |
| 393 This will take the diff of your branch against its upstream (origin/master), and
will post it to the \m[blue]\fBChromium code review site\fR\m[]\&\s-2\u[5]\d\s+
2\&. |
| 394 .SH "UPDATING THE CODE" |
| 395 .sp |
| 396 Inevitably, you\(cqll want to pull in changes from the main Chromium repo\&. Thi
s is pretty easy with \fIdepot_tools\fR: |
| 397 .sp |
| 398 .if n \{\ |
| 399 .RS 4 |
| 400 .\} |
| 401 .nf |
| 402 \fB$ git rebase\-update\fR |
| 403 .fi |
| 404 .if n \{\ |
| 405 .RE |
| 406 .\} |
| 407 .sp |
| 408 .sp |
| 409 This command will update all of your CLs to contain the latest code from their u
pstreams\&. It will also automatically clean up CLs which have been committed an
d a couple other nice things\&. See \fBgit-rebase-update\fR(1) for the full scoo
p\&. |
| 410 .sp |
| 411 One thing to look out for are \fImerge conflicts\fR\&. These happen for exactly
the same as they do with SVN, but the experience is a little more controllable w
ith git\&. git rebase\-update will try to rebase all your branches for you, but
if it encounters a merge conflict in one, it will halt and leave you in a rebase
conflict state (see \fBgit-rebase\fR(1))\&. Resolving git rebase merge conflict
s is beyond the scope of this tutorial, but there are many good sources online (
see the Prerequisites for some)\&. |
| 412 .sp |
| 413 Sometimes you\(cqre pretty certain that you\(cqve committed a certain branch, bu
t git rebase\-update isn\(cqt able to tell that for sure\&. This is usually beca
use your branch doesn\(cqt rebase cleanly\&. You could just delete the branch wi
th git branch \-D <branch>, but you\(cqd like to double check the diff of your b
ranch against its upstream before deleting it\&. If this is the case you can abo
rt the rebase started by git rebase\-update, and then run \fBgit-squash-branch\f
R(1) to flatten your branch into a single commit\&. When you run git rebase\-upd
ate again, you\(cqll get a (hopefully) much smaller / saner diff\&. If it turns
out you were wrong about your branch being fully committed, you can use \fBgit-r
eflog\fR(1) to reset your branch back to where it was before\&. If the diff look
s inconsequential, you can use git rebase \-\-skip to ignore it, and then git re
base\-update will clean it up for you\&. |
| 414 .sp |
| 415 Once you\(cqre done resolving all of the merge conflict, just run git rebase\-up
date, and it will pick up where it left off\&. Once the command has finished upd
ating all of your branches, it will return you back to the branch you started on
\&. |
| 416 .if n \{\ |
| 417 .sp |
| 418 .\} |
| 419 .RS 4 |
| 420 .it 1 an-trap |
| 421 .nr an-no-space-flag 1 |
| 422 .nr an-break-flag 1 |
| 423 .br |
| 424 .ps +1 |
| 425 \fBNote\fR |
| 426 .ps -1 |
| 427 .br |
| 428 .sp |
| 429 Running git rebase\-update will update all your branches, but it will not automa
tically run gclient sync to update your dependencies\&. |
| 430 .sp .5v |
| 431 .RE |
| 432 .SH "MANAGING MULTIPLE CLS" |
| 433 .sp |
| 434 Sometimes you want to work on more than one CL at once (say, you have a CL poste
d for review and want to work on something else)\&. For each CL that you want to
work on, just use git new\-branch <branchname>\&. |
| 435 .sp |
| 436 Once you start to have more than one CL at a time, it can be easy to lose your b
earings\&. Fortunately, \fIdepot_tools\fR has two tools to help you out: |
| 437 .sp |
| 438 .if n \{\ |
| 439 .RS 4 |
| 440 .\} |
| 441 .nf |
| 442 \fB$ git map\fR |
| 443 *\:\fB 7dcfe47 \fR (\:\fBfrozen_changes\fR\:) 2014\-03\-12 ~ FREEZE\&.unin
dexed |
| 444 * \fB4b0c180\fR 2014\-03\-12 ~ modfile |
| 445 * \fB59a7cca\fR 2014\-03\-12 ~ a deleted file |
| 446 * \fB6bec695\fR (\:origin/master\:) 2014\-03\-11 ~ Add neat feature \f
B<(frozen_changes)\fR |
| 447 * \fBd15a38a\fR 2014\-03\-11 ~ Epic README update |
| 448 * \fBd559894\fR (\:\fBmaster\fR\:) 2014\-03\-11 ~ Important upstream chan
ge |
| 449 | * \fB9c311fd\fR (\:\fBcool_feature\fR\:) 2014\-03\-11 ~ Respond to CL com
ments |
| 450 | | * \fB2a1eeb2\fR (\:\fBsubfeature\fR\:) 2014\-03\-11 ~ integrate with Cool
Service |
| 451 | | * \fBd777af6\fR 2014\-03\-11 ~ slick commenting action |
| 452 | |/ |
| 453 | * \fB265803a\fR 2014\-03\-11 ~ another improvement \fB<(subfeature)\fR |
| 454 | * \fB6d831ac\fR (\:\fBspleen_tag\fR\:) 2014\-03\-11 ~ Refactor spleen |
| 455 | * \fB82e74ab\fR 2014\-03\-11 ~ Add widget |
| 456 |/ |
| 457 * \fBd08c5b3\fR (\:\fBbogus_noparent\fR\:) 2014\-03\-11 ~ Wonderful begin
nings \fB<(cool_feature)\fR |
| 458 .fi |
| 459 .if n \{\ |
| 460 .RE |
| 461 .\} |
| 462 .sp |
| 463 .sp |
| 464 Note that this example repo is in dire need of a \fBgit-rebase-update\fR(1)! |
| 465 .sp |
| 466 .if n \{\ |
| 467 .RS 4 |
| 468 .\} |
| 469 .nf |
| 470 \fB$ git map\-branches\fR |
| 471 origin/master |
| 472 cool_feature |
| 473 subfeature |
| 474 frozen_changes * |
| 475 master |
| 476 .fi |
| 477 .if n \{\ |
| 478 .RE |
| 479 .\} |
| 480 .sp |
| 481 |
| 482 .PP |
| 483 \fBgit-map\fR(1) |
| 484 .RS 4 |
| 485 This tool shows you the history of all of your branches in a pseudo\-graphical f
ormat\&. In particular, it will show you which commits all of your branches are
on, which commit you currently have checked out, and more\&. Check out the doc f
or the full details\&. |
| 486 .RE |
| 487 .PP |
| 488 \fBgit-map-branches\fR(1) |
| 489 .RS 4 |
| 490 This tool just shows you which branches you have in your repo, and thier upstrea
m relationship to each other (as well as which branch you have checked out at th
e moment)\&. |
| 491 .RE |
| 492 .sp |
| 493 Additionally, sometimes you need to switch between branches, but you\(cqve got w
ork in progress\&. You could use \fBgit-stash\fR(1), but that can be tricky to m
anage because you need to remember which branches you stashed what changes on\&.
Helpfully \fIdepot_tools\fR includes two tools which can greatly assist in case
: |
| 494 .sp |
| 495 \fBgit-freeze\fR(1) allows you to put the current branch in \*(Aqsuspended anima
tion\*(Aq by committing your changes to a specially\-named commit on the top of
your current branch\&. When you come back to your branch later, you can just run
\fBgit-thaw\fR(1) to get your work\-in\-progress changes back to what they were
\&. |
| 496 .sp |
| 497 Another useful tool is \fBgit-rename-branch\fR(1)\&. Unlike git branch \-m <old>
<new>, this tool will correctly preserve the upstream relationships of your bra
nch compared to its downstreams\&. |
| 498 .sp |
| 499 Finally, take a look at \fBgit-upstream-diff\fR(1)\&. This will show you the com
bined diff for all the commits on your branch against the upstream tracking bran
ch\&. This is \fIexactly\fR what git cl upload will push up to code review\&. Ad
ditionally, consider trying the \-\-wordwise argument to get a colorized per\-wo
rd diff (instead of a per\-line diff)\&. |
| 500 .SH "MANAGING DEPENDENT CLS" |
| 501 .sp |
| 502 Now that you know how to manage \fIindependent\fR CLs, we\(cqll see how to manag
e \fIdependent\fR CLs\&. Dependent CLs are useful when your second (or third or
fourth or \&...) CL depends on the changes in one of your other CLs (such as: CL
2 won\(cqt compile without CL 1, but you want to submit them as two separate re
views)\&. |
| 503 .sp |
| 504 Like all of the other CLs we\(cqve created, we use \fBgit-new-branch\fR(1), but
this time with an extra argument\&. First, git checkout the branch you want to b
ase the new one on (i\&.e\&. CL 1), and then run: |
| 505 .sp |
| 506 .if n \{\ |
| 507 .RS 4 |
| 508 .\} |
| 509 .nf |
| 510 \fB$ git new\-branch \-\-upstream_current <branch_name>\fR |
| 511 .fi |
| 512 .if n \{\ |
| 513 .RE |
| 514 .\} |
| 515 .sp |
| 516 .sp |
| 517 This will make a new branch which tracks the \fIcurrent\fR branch as its upstrea
m (as opposed to \fIorigin/master\fR)\&. All changes you commit to this branch w
ill be in addition to the previous branch, but when you git cl upload, you will
only upload the diff for the dependent (child) branch\&. You may have as many br
anches nested in this fashion as you like\&. |
| 518 .sp |
| 519 \fBgit-map\fR(1) and \fBgit-map-branches\fR(1) are particularly helpful when you
have dependent branches\&. In addition, there are two helper commands which let
you traverse your working copy up and down this tree of branches: \fBgit-nav-up
stream\fR(1) and \fBgit-nav-downstream\fR(1)\&. |
| 520 .sp |
| 521 Sometimes when dealing with dependent CLs, it turns out that you accidentally ba
sed a branch on the wrong upstream, but since then you\(cqve committed changes t
o it, or even based \fIanother\fR branch off of that one\&. Or you discover that
you have two independent CLs that would actually be much better off as dependen
t CLs\&. In instances like these, you can check out the offending branch and use
\fBgit-reparent-branch\fR(1) to move it to track a different parent\&. Note tha
t this can also be used to move a branch from tracking origin/master to lkgr or
vice versa\&. |
| 522 .SH "EXAMPLE WALKTHROUGH" |
311 .sp | 523 .sp |
312 This section will demo what a typical workflow looks like when writing, updating
, and committing multiple CLs\&. | 524 This section will demo what a typical workflow looks like when writing, updating
, and committing multiple CLs\&. |
313 .sp | 525 .sp |
314 | 526 |
315 .sp | 527 .sp |
316 .if n \{\ | 528 .if n \{\ |
317 .RS 4 | 529 .RS 4 |
318 .\} | 530 .\} |
319 .nf | 531 .nf |
320 \fB$ fetch chromium\fR | 532 \fB$ fetch chromium\fR |
(...skipping 48 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
369 \fB$ git map\fR | 581 \fB$ git map\fR |
370 \fB* 615ffa7 \fR (\fBfix_typo\fR) 2014\-04\-10 ~ Fix terrible typo\&. | 582 \fB* 615ffa7 \fR (\fBfix_typo\fR) 2014\-04\-10 ~ Fix terrible typo\&. |
371 * \fBbeec6f4 \fR (origin/master, origin/HEAD) 2014\-04\-10 ~ Make ReflectorIm
pl use mailboxes\fB <(fix_typo)\fR | 583 * \fBbeec6f4 \fR (origin/master, origin/HEAD) 2014\-04\-10 ~ Make ReflectorIm
pl use mailboxes\fB <(fix_typo)\fR |
372 * \fB41290e0 \fR 2014\-04\-10 ~ don\*(Aqt use glibc\-specific execinfo\&.h on
uclibc builds | 584 * \fB41290e0 \fR 2014\-04\-10 ~ don\*(Aqt use glibc\-specific execinfo\&.h on
uclibc builds |
373 * \fBa76fde7 \fR 2014\-04\-10 ~ [fsp] Add requestUnmount() method together wi
th the request manager\&. | 585 * \fBa76fde7 \fR 2014\-04\-10 ~ [fsp] Add requestUnmount() method together wi
th the request manager\&. |
374 * \fB9de7a71 \fR 2014\-04\-10 ~ linux_aura: Use system configuration for midd
le clicking the titlebar\&. | 586 * \fB9de7a71 \fR 2014\-04\-10 ~ linux_aura: Use system configuration for midd
le clicking the titlebar\&. |
375 * \fB073b0c2 \fR 2014\-04\-10 ~ ContentView\->ContentViewCore in ContentViewR
enderView | 587 * \fB073b0c2 \fR 2014\-04\-10 ~ ContentView\->ContentViewCore in ContentViewR
enderView |
376 * \fB2250f53 \fR 2014\-04\-10 ~ ozone: evdev: Filter devices by path | 588 * \fB2250f53 \fR 2014\-04\-10 ~ ozone: evdev: Filter devices by path |
377 * \fB33a7a74 \fR 2014\-04\-10 ~ Always output seccomp error messages to stder
r | 589 * \fB33a7a74 \fR 2014\-04\-10 ~ Always output seccomp error messages to stder
r |
378 \fB$ git status\fR | 590 \fB$ git status\fR |
379 # On branch fix_typo | 591 On branch fix_typo |
380 # Your branch is ahead of \*(Aqorigin/master\*(Aq by 1 commit\&. | 592 Your branch is ahead of \*(Aqorigin/master\*(Aq by 1 commit\&. |
381 # (use "git push" to publish your local commits) | 593 (use "git push" to publish your local commits) |
382 # | 594 |
383 nothing to commit, working directory clean | 595 nothing to commit, working directory clean |
384 \fB$ git cl upload \-r domo@chromium\&.org \-\-send\-mail\fR | 596 \fB$ git cl upload \-r domo@chromium\&.org \-\-send\-mail\fR |
385 \&.\&.\&. truncated output \&.\&.\&. | 597 \&.\&.\&. truncated output \&.\&.\&. |
386 .fi | 598 .fi |
387 .if n \{\ | 599 .if n \{\ |
388 .RE | 600 .RE |
389 .\} | 601 .\} |
390 .sp | 602 .sp |
391 While we wait for feedback, let\*(Aqs do something else\&. | 603 While we wait for feedback, let\*(Aqs do something else\&. |
392 .sp | 604 .sp |
393 .if n \{\ | 605 .if n \{\ |
394 .RS 4 | 606 .RS 4 |
395 .\} | 607 .\} |
396 .nf | 608 .nf |
397 \fB$ git new\-branch chap2\fR | 609 \fB$ git new\-branch chap2\fR |
398 \fB$ git map\-branches\fR | 610 \fB$ git map\-branches\fR |
399 \fBorigin/master | 611 \fBorigin/master |
400 chap2 * | 612 chap2 * |
401 \fR fix_typo | 613 \fR fix_typo |
402 \fB$ cat >> build/whitespace_file\&.txt <<EOF\fR | 614 \fB$ cat >> build/whitespace_file\&.txt <<EOF\fR |
403 | 615 |
404 "You recall what happened on Mulholland drive?" The ceiling fan rotated slowly | 616 "You recall what happened on Mulholland drive?" The ceiling fan rotated slowly |
405 overhead, barely disturbing the thick cigarette smoke\&. No doubt was left about | 617 overhead, barely disturbing the thick cigarette smoke\&. No doubt was left about |
406 when the fan was last cleaned\&. | 618 when the fan was last cleaned\&. |
407 EOF | 619 EOF |
408 \fB$ git status\fR | 620 \fB$ git status\fR |
409 # On branch chap2 | 621 On branch chap2 |
410 # Your branch is up\-to\-date with \*(Aqorigin/master\*(Aq\&. | 622 Your branch is up\-to\-date with \*(Aqorigin/master\*(Aq\&. |
411 # | 623 |
412 # Changes not staged for commit: | 624 Changes not staged for commit: |
413 # (use "git add <file>\&.\&.\&." to update what will be committed) | 625 (use "git add <file>\&.\&.\&." to update what will be committed) |
414 # (use "git checkout \-\- <file>\&.\&.\&." to discard changes in working direc
tory) | 626 (use "git checkout \-\- <file>\&.\&.\&." to discard changes in working directo
ry) |
415 # | 627 |
416 #» modified: build/whitespace_file\&.txt | 628 » modified: build/whitespace_file\&.txt |
417 # | 629 |
418 no changes added to commit (use "git add" and/or "git commit \-a") | 630 no changes added to commit (use "git add" and/or "git commit \-a") |
419 .fi | 631 .fi |
420 .if n \{\ | 632 .if n \{\ |
421 .RE | 633 .RE |
422 .\} | 634 .\} |
423 .sp | 635 .sp |
424 Someone on the code review pointed out that our typo\-fix has a typo :( We\*(Aqr
e still working on \*(Aqchap2\*(Aq but we really want to land \*(Aqfix_typo\*(Aq
, so let\*(Aqs switch over and fix it\&. | 636 Someone on the code review pointed out that our typo\-fix has a typo :( We\*(Aqr
e still working on \*(Aqchap2\*(Aq but we really want to land \*(Aqfix_typo\*(Aq
, so let\*(Aqs switch over and fix it\&. |
425 .sp | 637 .sp |
426 .if n \{\ | 638 .if n \{\ |
427 .RS 4 | 639 .RS 4 |
(...skipping 345 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
773 * \fB33a7a74 \fR 2014\-04\-10 ~ Always output seccomp error messages to stder
r | 985 * \fB33a7a74 \fR 2014\-04\-10 ~ Always output seccomp error messages to stder
r |
774 \fB$ git cl upload\fR | 986 \fB$ git cl upload\fR |
775 \&.\&.\&. truncated output \&.\&.\&. | 987 \&.\&.\&. truncated output \&.\&.\&. |
776 .fi | 988 .fi |
777 .if n \{\ | 989 .if n \{\ |
778 .RE | 990 .RE |
779 .\} | 991 .\} |
780 .sp | 992 .sp |
781 .sp | 993 .sp |
782 So there you have the basic flow\&. Note that you don\(cqt \fIhave\fR to do chro
mium development using these tools\&. Any git workflow is compatible, as long as
git cl upload is able to upload good patches\&. | 994 So there you have the basic flow\&. Note that you don\(cqt \fIhave\fR to do chro
mium development using these tools\&. Any git workflow is compatible, as long as
git cl upload is able to upload good patches\&. |
783 .SH "CREATING / UPLOADING A CL" | |
784 .if n \{\ | |
785 .sp | |
786 .\} | |
787 .RS 4 | |
788 .it 1 an-trap | |
789 .nr an-no-space-flag 1 | |
790 .nr an-break-flag 1 | |
791 .br | |
792 .ps +1 | |
793 \fBNote\fR | |
794 .ps -1 | |
795 .br | |
796 .sp | |
797 The remainder of the tutorial assumes that your current working directory is the
src/ folder mentioned in Getting the code\&. | |
798 .sp .5v | |
799 .RE | |
800 .sp | |
801 Each CL corresponds exactly with a single branch in git\&. Any time you want to
begin a new CL, just: | |
802 .sp | |
803 .if n \{\ | |
804 .RS 4 | |
805 .\} | |
806 .nf | |
807 \fB$ git new\-branch <branch_name>\fR | |
808 .fi | |
809 .if n \{\ | |
810 .RE | |
811 .\} | |
812 .sp | |
813 .sp | |
814 This will create and checkout a new branch named branch_name which will track th
e default upstream (which is origin/master)\&. See \fBgit-new-branch\fR(1) for m
ore features, such as the ability to track \fILKGR\fR\&. | |
815 .sp | |
816 Commit as many changes as you like to this branch\&. When you want to upload it
for review, run: | |
817 .sp | |
818 .if n \{\ | |
819 .RS 4 | |
820 .\} | |
821 .nf | |
822 \fB$ git cl upload\fR | |
823 .fi | |
824 .if n \{\ | |
825 .RE | |
826 .\} | |
827 .sp | |
828 .sp | |
829 This will take the diff of your branch against its upstream (origin/master), and
will post it to the \m[blue]\fBChromium code review site\fR\m[]\&\s-2\u[5]\d\s+
2\&. | |
830 .SH "UPDATING THE CODE" | |
831 .sp | |
832 Inevitably, you\(cqll want to pull in changes from the main Chromium repo\&. Thi
s is pretty easy with \fIdepot_tools\fR: | |
833 .sp | |
834 .if n \{\ | |
835 .RS 4 | |
836 .\} | |
837 .nf | |
838 \fB$ git rebase\-update\fR | |
839 .fi | |
840 .if n \{\ | |
841 .RE | |
842 .\} | |
843 .sp | |
844 .sp | |
845 This command will update all of your CLs to contain the latest code from their u
pstreams\&. It will also automatically clean up CLs which have been committed an
d a couple other nice things\&. See \fBgit-rebase-update\fR(1) for the full scoo
p\&. | |
846 .sp | |
847 One thing to look out for are \fImerge conflicts\fR\&. These happen for exactly
the same as they do with SVN, but the experience is a little more controllable w
ith git\&. git rebase\-update will try to rebase all your branches for you, but
if it encounters a merge conflict in one, it will halt and leave you in a rebase
conflict state (see \fBgit-rebase\fR(1))\&. Resolving git rebase merge conflict
s is beyond the scope of this tutorial, but there are many good sources online (
see the Prerequisites for some)\&. | |
848 .sp | |
849 Sometimes you\(cqre pretty certain that you\(cqve committed a certain branch, bu
t git rebase\-update isn\(cqt able to tell that for sure\&. This is usually beca
use your branch doesn\(cqt rebase cleanly\&. You could just delete the branch wi
th git branch \-D <branch>, but you\(cqd like to double check the diff of your b
ranch against its upstream before deleting it\&. If this is the case you can abo
rt the rebase started by git rebase\-update, and then run \fBgit-squash-branch\f
R(1) to flatten your branch into a single commit\&. When you run git rebase\-upd
ate again, you\(cqll get a (hopefully) much smaller / saner diff\&. If it turns
out you were wrong about your branch being fully committed, you can use \fBgit-r
eflog\fR(1) to reset your branch back to where it was before\&. If the diff look
s inconsequential, you can use git rebase \-\-skip to ignore it, and then git re
base\-update will clean it up for you\&. | |
850 .sp | |
851 Once you\(cqre done resolving all of the merge conflict, just run git rebase\-up
date, and it will pick up where it left off\&. Once the command has finished upd
ating all of your branches, it will return you back to the branch you started on
\&. | |
852 .if n \{\ | |
853 .sp | |
854 .\} | |
855 .RS 4 | |
856 .it 1 an-trap | |
857 .nr an-no-space-flag 1 | |
858 .nr an-break-flag 1 | |
859 .br | |
860 .ps +1 | |
861 \fBNote\fR | |
862 .ps -1 | |
863 .br | |
864 .sp | |
865 Running git rebase\-update will update all your branches, but it will not automa
tically run gclient sync to update your dependencies\&. | |
866 .sp .5v | |
867 .RE | |
868 .SH "MANAGING MULTIPLE CLS" | |
869 .sp | |
870 Sometimes you want to work on more than one CL at once (say, you have a CL poste
d for review and want to work on something else)\&. For each CL that you want to
work on, just use git new\-branch <branchname>\&. | |
871 .sp | |
872 Once you start to have more than one CL at a time, it can be easy to lose your b
earings\&. Fortunately, \fIdepot_tools\fR has two tools to help you out: | |
873 .sp | |
874 .if n \{\ | |
875 .RS 4 | |
876 .\} | |
877 .nf | |
878 \fB$ git map\fR | |
879 *\:\fB 7dcfe47 \fR (\:\fBfrozen_changes\fR\:) 2014\-03\-12 ~ FREEZE\&.unin
dexed | |
880 * \fB4b0c180\fR 2014\-03\-12 ~ modfile | |
881 * \fB59a7cca\fR 2014\-03\-12 ~ a deleted file | |
882 * \fB6bec695\fR (\:origin/master\:) 2014\-03\-11 ~ Add neat feature \f
B<(frozen_changes)\fR | |
883 * \fBd15a38a\fR 2014\-03\-11 ~ Epic README update | |
884 * \fBd559894\fR (\:\fBmaster\fR\:) 2014\-03\-11 ~ Important upstream chan
ge | |
885 | * \fB9c311fd\fR (\:\fBcool_feature\fR\:) 2014\-03\-11 ~ Respond to CL com
ments | |
886 | | * \fB2a1eeb2\fR (\:\fBsubfeature\fR\:) 2014\-03\-11 ~ integrate with Cool
Service | |
887 | | * \fBd777af6\fR 2014\-03\-11 ~ slick commenting action | |
888 | |/ | |
889 | * \fB265803a\fR 2014\-03\-11 ~ another improvement \fB<(subfeature)\fR | |
890 | * \fB6d831ac\fR (\:\fBspleen_tag\fR\:) 2014\-03\-11 ~ Refactor spleen | |
891 | * \fB82e74ab\fR 2014\-03\-11 ~ Add widget | |
892 |/ | |
893 * \fBd08c5b3\fR (\:\fBbogus_noparent\fR\:) 2014\-03\-11 ~ Wonderful begin
nings \fB<(cool_feature)\fR | |
894 .fi | |
895 .if n \{\ | |
896 .RE | |
897 .\} | |
898 .sp | |
899 .sp | |
900 Note that this example repo is in dire need of a \fBgit-rebase-update\fR(1)! | |
901 .sp | |
902 .if n \{\ | |
903 .RS 4 | |
904 .\} | |
905 .nf | |
906 \fB$ git map\-branches\fR | |
907 origin/master | |
908 cool_feature | |
909 subfeature | |
910 frozen_changes * | |
911 master | |
912 .fi | |
913 .if n \{\ | |
914 .RE | |
915 .\} | |
916 .sp | |
917 | |
918 .PP | |
919 \fBgit-map\fR(1) | |
920 .RS 4 | |
921 This tool shows you the history of all of your branches in a pseudo\-graphical f
ormat\&. In particular, it will show you which commits all of your branches are
on, which commit you currently have checked out, and more\&. Check out the doc f
or the full details\&. | |
922 .RE | |
923 .PP | |
924 \fBgit-map-branches\fR(1) | |
925 .RS 4 | |
926 This tool just shows you which branches you have in your repo, and thier upstrea
m relationship to each other (as well as which branch you have checked out at th
e moment)\&. | |
927 .RE | |
928 .sp | |
929 Additionally, sometimes you need to switch between branches, but you\(cqve got w
ork in progress\&. You could use \fBgit-stash\fR(1), but that can be tricky to m
anage because you need to remember which branches you stashed what changes on\&.
Helpfully \fIdepot_tools\fR includes two tools which can greatly assist in case
: | |
930 .sp | |
931 \fBgit-freeze\fR(1) allows you to put the current branch in \*(Aqsuspended anima
tion\*(Aq by committing your changes to a specially\-named commit on the top of
your current branch\&. When you come back to your branch later, you can just run
\fBgit-thaw\fR(1) to get your work\-in\-progress changes back to what they were
\&. | |
932 .sp | |
933 Another useful tool is \fBgit-rename-branch\fR(1)\&. Unlike git branch \-m <old>
<new>, this tool will correctly preserve the upstream relationships of your bra
nch compared to its downstreams\&. | |
934 .sp | |
935 Finally, take a look at \fBgit-upstream-diff\fR(1)\&. This will show you the com
bined diff for all the commits on your branch against the upstream tracking bran
ch\&. This is \fIexactly\fR what git cl upload will push up to code review\&. Ad
ditionally, consider trying the \-\-wordwise argument to get a colorized per\-wo
rd diff (instead of a per\-line diff)\&. | |
936 .SH "MANAGING DEPENDENT CLS" | |
937 .sp | |
938 Now that you know how to manage \fIindependent\fR CLs, we\(cqll see how to manag
e \fIdependent\fR CLs\&. Dependent CLs are useful when your second (or third or
fourth or \&...) CL depends on the changes in one of your other CLs (such as: CL
2 won\(cqt compile without CL 1, but you want to submit them as two separate re
views)\&. | |
939 .sp | |
940 Like all of the other CLs we\(cqve created, we use \fBgit-new-branch\fR(1), but
this time with an extra argument\&. First, git checkout the branch you want to b
ase the new one on (i\&.e\&. CL 1), and then run: | |
941 .sp | |
942 .if n \{\ | |
943 .RS 4 | |
944 .\} | |
945 .nf | |
946 \fB$ git new\-branch \-\-upstream_current <branch_name>\fR | |
947 .fi | |
948 .if n \{\ | |
949 .RE | |
950 .\} | |
951 .sp | |
952 .sp | |
953 This will make a new branch which tracks the \fIcurrent\fR branch as its upstrea
m (as opposed to \fIorigin/master\fR)\&. All changes you commit to this branch w
ill be in addition to the previous branch, but when you git cl upload, you will
only upload the diff for the dependent (child) branch\&. You may have as many br
anches nested in this fashion as you like\&. | |
954 .sp | |
955 \fBgit-map\fR(1) and \fBgit-map-branches\fR(1) are particularly helpful when you
have dependent branches\&. In addition, there are two helper commands which let
you traverse your working copy up and down this tree of branches: \fBgit-nav-up
stream\fR(1) and \fBgit-nav-downstream\fR(1)\&. | |
956 .sp | |
957 Sometimes when dealing with dependent CLs, it turns out that you accidentally ba
sed a branch on the wrong upstream, but since then you\(cqve committed changes t
o it, or even based \fIanother\fR branch off of that one\&. Or you discover that
you have two independent CLs that would actually be much better off as dependen
t CLs\&. In instances like these, you can check out the offending branch and use
\fBgit-reparent-branch\fR(1) to move it to track a different parent\&. Note tha
t this can also be used to move a branch from tracking origin/master to lkgr or
vice versa\&. | |
958 .SH "CONCLUSION" | 995 .SH "CONCLUSION" |
959 .sp | 996 .sp |
960 Hopefully that gives you a good starting overview on Chromium development using
\fIdepot_tools\fR\&. If you have questions which weren\(cqt answered by this tut
orial or the man pages for the tools (see the index of all tools here: \fBdepot_
tools\fR(7)), please feel free to ask\&. | 997 Hopefully that gives you a good starting overview on Chromium development using
\fIdepot_tools\fR\&. If you have questions which weren\(cqt answered by this tut
orial or the man pages for the tools (see the index of all tools here: \fBdepot_
tools\fR(7)), please feel free to ask\&. |
961 .SH "GLOSSARY" | 998 .SH "GLOSSARY" |
962 .PP | 999 .PP |
963 CL | 1000 CL |
964 .RS 4 | 1001 .RS 4 |
965 A | 1002 A |
966 \fIchange\-list\fR\&. This is a diff which you would like to commit to the codeb
ase\&. | 1003 \fIchange\-list\fR\&. This is a diff which you would like to commit to the codeb
ase\&. |
967 .RE | 1004 .RE |
(...skipping 47 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1015 .IP " 6." 4 | 1052 .IP " 6." 4 |
1016 main Chromium waterfall | 1053 main Chromium waterfall |
1017 .RS 4 | 1054 .RS 4 |
1018 \%http://build.chromium.org | 1055 \%http://build.chromium.org |
1019 .RE | 1056 .RE |
1020 .IP " 7." 4 | 1057 .IP " 7." 4 |
1021 here | 1058 here |
1022 .RS 4 | 1059 .RS 4 |
1023 \%https://chromium.googlesource.com/chromium/tools/depot_tools.git | 1060 \%https://chromium.googlesource.com/chromium/tools/depot_tools.git |
1024 .RE | 1061 .RE |
OLD | NEW |