Minor fixes

man/man7/depot_tools_tutorial.7

 '\" t
 .\"     Title: depot_tools_tutorial
 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
-.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date: 04/28/2014
+.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
+.\"      Date: 05/09/2014
 .\"    Manual: Chromium depot_tools Manual
-.\"    Source: depot_tools 32af7d9
+.\"    Source: depot_tools 54dac93
 .\"  Language: English
 .\"
-.TH "DEPOT_TOOLS_TUTORIAL" "7" "04/28/2014" "depot_tools 32af7d9" "Chromium depot_tools Manual"
+.TH "DEPOT_TOOLS_TUTORIAL" "7" "05/09/2014" "depot_tools 54dac93" "Chromium depot_tools Manual"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .\" http://bugs.debian.org/507673
 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .\" -----------------------------------------------------------------
@@ skipping 13 matching lines @@
 The Chromium \fBdepot_tools\fR(7) suite contains many git workflow\-enhancing tools which are designed to work together to enable anyone to wrangle the Chromium codebase expertly\&. This tutorial explains how to do development on Chromium using these tools\&. This will cover:
 .sp
 .RS 4
 .ie n \{\
 \h'-04'\(bu\h'+03'\c
 .\}
 .el \{\
 .sp -1
 .IP \(bu 2.3
 .\}
+
 Setting up
 .RE
 .sp
 .RS 4
 .ie n \{\
 \h'-04'\(bu\h'+03'\c
 .\}
 .el \{\
 .sp -1
 .IP \(bu 2.3
 .\}
+
 Getting the code
 .RE
 .sp
 .RS 4
 .ie n \{\
 \h'-04'\(bu\h'+03'\c
 .\}
 .el \{\
 .sp -1
 .IP \(bu 2.3
 .\}
+
 TL;DR
 .RE
 .sp
 .RS 4
 .ie n \{\
 \h'-04'\(bu\h'+03'\c
 .\}
 .el \{\
 .sp -1
 .IP \(bu 2.3
 .\}
+
 Creating / Uploading a CL
 .RE
 .sp
 .RS 4
 .ie n \{\
 \h'-04'\(bu\h'+03'\c
 .\}
 .el \{\
 .sp -1
 .IP \(bu 2.3
 .\}
+
 Updating the code
 .RE
 .sp
 .RS 4
 .ie n \{\
 \h'-04'\(bu\h'+03'\c
 .\}
 .el \{\
 .sp -1
 .IP \(bu 2.3
 .\}
+
 Managing multiple CLs
 .RE
 .sp
 .RS 4
 .ie n \{\
 \h'-04'\(bu\h'+03'\c
 .\}
 .el \{\
 .sp -1
 .IP \(bu 2.3
 .\}
+
 Managing dependent CLs
 .RE
 .sp
 .RS 4
 .ie n \{\
 \h'-04'\(bu\h'+03'\c
 .\}
 .el \{\
 .sp -1
 .IP \(bu 2.3
 .\}
+
 Example Walkthrough
 .RE
 .sp
 Please refer to the manpages (or \-\-help output) for details about any of the commands mentioned in this tutorial\&.
 .if n \{\
 .sp
 .\}
 .RS 4
 .it 1 an-trap
 .nr an-no-space-flag 1
@@ skipping 12 matching lines @@
 This tutorial assumes basic familiarity with git terminology and concepts\&. If you need to brush up on these, the following are very good resources:
 .sp
 .RS 4
 .ie n \{\
 \h'-04'\(bu\h'+03'\c
 .\}
 .el \{\
 .sp -1
 .IP \(bu 2.3
 .\}
+
 \m[blue]\fBThink like (a) Git\fR\m[]\&\s-2\u[1]\d\s+2
 \- A lighthearted overview of git\&. If you\(cqre sorta\-familiar with git, but not
 \fIcomfortable\fR
 with it, then give this a look\&.
 .RE
 .sp
 .RS 4
 .ie n \{\
 \h'-04'\(bu\h'+03'\c
 .\}
 .el \{\
 .sp -1
 .IP \(bu 2.3
 .\}
+
 \m[blue]\fBGit Immersion Tutorial\fR\m[]\&\s-2\u[2]\d\s+2
 \- An in\-depth git tutorial\&.
 .RE
 .sp
 .RS 4
 .ie n \{\
 \h'-04'\(bu\h'+03'\c
 .\}
 .el \{\
 .sp -1
 .IP \(bu 2.3
 .\}
+
 \m[blue]\fBpcottle\(cqs Visual Git Branching\fR\m[]\&\s-2\u[3]\d\s+2
 \- An excellent interactive/graphical demo on how git handles commits, branches, and shows the operations git performs on them\&.
 .RE
 .sp
 .RS 4
 .ie n \{\
 \h'-04'\(bu\h'+03'\c
 .\}
 .el \{\
 .sp -1
 .IP \(bu 2.3
 .\}
+
 \m[blue]\fBPro Git book\fR\m[]\&\s-2\u[4]\d\s+2
 \- \(lqThe\(rq book for learning git from basics to advanced concepts\&. A bit dry, but very through\&.
 .RE
 .sp
 If you\(cqve tried these out and are still having some trouble getting started, there are \fImany\fR other resources online which should help\&. If you\(cqre \fIreally\fR \fB\fIreally\fR\fR stuck, then chat up one of the Chromium infrastructure team members for some pointers\&.
 .PP
 Litmus Test
 .RS 4
 If you know what
 git add,
@@ skipping 59 matching lines @@
 .\}
 .nf
 \fB$\fR # get the code
 \fB$\fR # In an empty directory:
 \fB$ fetch {chromium,blink,\&.\&.\&.}\fR
 
 \fB$\fR # Update third_party repos and run pre\-compile hooks
 \fB$ gclient sync\fR
 
 \fB$\fR # Make a new change and upload it for review
-\fB$ git new\-branch branchname\fR
+\fB$ git new\-branch <branch_name>\fR
 \fB$\fR # repeat: [edit, git add, git commit]
 \fB$ git cl upload\fR
 
 \fB$\fR # After change is reviewed, commit with the CQ
 \fB$ git cl set_commit\fR
 \fB$\fR # Note that the committed hash which lands will /not/ match the
 \fB$\fR # commit hashes of your local branch\&.
 .fi
 .if n \{\
 .RE
@@ skipping 24 matching lines @@
 .\}
 .nf
 \fB\&.gclient\fR   # A configuration file for you source checkout
 \fBsrc/\fR       # Top\-level Chromium source checkout\&.
 .fi
 .if n \{\
 .RE
 .\}
 .sp
 .sp
-If you are on linux, then you\(cqll need to run:
+If you are on linux and fetching the code for the first time, then you\(cqll need to run:
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
 \fB$ cd src && \&./build/install\-build\-deps\&.sh\fR
 .fi
 .if n \{\
 .RE
 .\}
 .sp
 .sp
 And finally:
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
 \fB$ gclient sync\fR
 .fi
 .if n \{\
 .RE
 .\}
 .sp
 .sp
-This will pull all dependencies of the Chromium src checkout\&. You will need to run this any time you update the main src checkout\&.
+This will pull all dependencies of the Chromium src checkout\&. You will need to run this any time you update the main src checkout, including when you switch branches\&.
 .SH "CREATING / UPLOADING A CL"
 .if n \{\
 .sp
 .\}
 .RS 4
 .it 1 an-trap
 .nr an-no-space-flag 1
 .nr an-break-flag 1
 .br
 .ps +1
 \fBNote\fR
 .ps -1
 .br
 .sp
 The remainder of the tutorial assumes that your current working directory is the src/ folder mentioned in Getting the code\&.
 .sp .5v
 .RE
 .sp
-Each CL corresponds exactly with a single branch in git\&. Any time you want to begin a new CL, just:
+Each CL corresponds exactly with a single branch in git\&. Any time you want to begin a new CL:
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
 \fB$ git new\-branch <branch_name>\fR
 .fi
 .if n \{\
 .RE
 .\}
 .sp
 .sp
-This will create and checkout a new branch named branch_name which will track the default upstream (which is origin/master)\&. See \fBgit-new-branch\fR(1) for more features, such as the ability to track \fILKGR\fR\&.
+This will create and checkout a new branch named branch_name which will track the default upstream branch (origin/master)\&. See \fBgit-new-branch\fR(1) for more features\&.
 .sp
 Commit as many changes as you like to this branch\&. When you want to upload it for review, run:
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
 \fB$ git cl upload\fR
 .fi
 .if n \{\
 .RE
 .\}
 .sp
 .sp
-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\&.
+This will take the diff of your branch against its upstream branch (in that case origin/master), and will post it to the \m[blue]\fBChromium code review site\fR\m[]\&\s-2\u[5]\d\s+2\&.
 .SH "UPDATING THE CODE"
 .sp
 Inevitably, you\(cqll want to pull in changes from the main Chromium repo\&. This is pretty easy with \fIdepot_tools\fR:
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
 \fB$ git rebase\-update\fR
 .fi
@@ skipping 20 matching lines @@
 .ps +1
 \fBNote\fR
 .ps -1
 .br
 .sp
 Running git rebase\-update will update all your branches, but it will not automatically run gclient sync to update your dependencies\&.
 .sp .5v
 .RE
 .SH "MANAGING MULTIPLE CLS"
 .sp
-Sometimes you want to work on more than one CL at once (say, you have a CL posted for review and want to work on something else)\&. For each CL that you want to work on, just use git new\-branch <branchname>\&.
+Sometimes you want to work on more than one CL at once (say, you have a CL posted for review and want to work on something else)\&. For each CL that you want to work on, just use git new\-branch <branch_name>\&.
 .sp
 Once you start to have more than one CL at a time, it can be easy to lose your bearings\&. Fortunately, \fIdepot_tools\fR has two tools to help you out:
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
 \fB$ git map\fR
 *\:\fB 7dcfe47       \fR (\:\fBfrozen_changes\fR\:) 2014\-03\-12 ~ FREEZE\&.unindexed
 * \fB4b0c180\fR        2014\-03\-12 ~ modfile
@@ skipping 26 matching lines @@
 origin/master
   cool_feature
     subfeature
   frozen_changes *
   master
 .fi
 .if n \{\
 .RE
 .\}
 .sp
-
 .PP
 \fBgit-map\fR(1)
 .RS 4
 This tool shows you the history of all of your branches in a pseudo\-graphical format\&. 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 for the full details\&.
 .RE
 .PP
 \fBgit-map-branches\fR(1)
 .RS 4
-This tool just shows you which branches you have in your repo, and thier upstream relationship to each other (as well as which branch you have checked out at the moment)\&.
+This tool just shows you which branches you have in your repo, and their upstream relationship to each other (as well as which branch you have checked out at the moment)\&.
 .RE
 .sp
 Additionally, sometimes you need to switch between branches, but you\(cqve got work in progress\&. You could use \fBgit-stash\fR(1), but that can be tricky to manage 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:
 .sp
 \fBgit-freeze\fR(1) allows you to put the current branch in \*(Aqsuspended animation\*(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\&.
 .sp
 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 branch compared to its downstreams\&.
 .sp
 Finally, take a look at \fBgit-upstream-diff\fR(1)\&. This will show you the combined diff for all the commits on your branch against the upstream tracking branch\&. This is \fIexactly\fR what git cl upload will push up to code review\&. Additionally, consider trying the \-\-wordwise argument to get a colorized per\-word diff (instead of a per\-line diff)\&.
 .SH "MANAGING DEPENDENT CLS"
@@ skipping 64 matching lines @@
 .sp
 Let\*(Aqs fix something!
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
 \fB$ git new\-branch fix_typo\fR
 \fB$ echo \-e \*(Aq/Banana\ens/Banana/Kuun\enwq\*(Aq | ed build/whitespace_file\&.txt\fR
 1503
+1501
 It was a Domo\-Banana\&.
 It was a Domo\-Kuun\&.
-1501
 \fB$ git commit \-am \*(AqFix terrible typo\&.\*(Aq\fR
 [fix_typo 615ffa7] Fix terrible typo\&.
  1 file changed, 1 insertion(+), 1 deletion(\-)
 \fB$ git map\fR
 \fB* 615ffa7    \fR (\fBfix_typo\fR) 2014\-04\-10 ~ Fix terrible typo\&.
 * \fBbeec6f4    \fR (origin/master, origin/HEAD) 2014\-04\-10 ~ Make ReflectorImpl use mailboxes\fB    <(fix_typo)\fR
 * \fB41290e0    \fR 2014\-04\-10 ~ don\*(Aqt use glibc\-specific execinfo\&.h on uclibc builds
 * \fBa76fde7    \fR 2014\-04\-10 ~ [fsp] Add requestUnmount() method together with the request manager\&.
 * \fB9de7a71    \fR 2014\-04\-10 ~ linux_aura: Use system configuration for middle clicking the titlebar\&.
 * \fB073b0c2    \fR 2014\-04\-10 ~ ContentView\->ContentViewCore in ContentViewRenderView
 * \fB2250f53    \fR 2014\-04\-10 ~ ozone: evdev: Filter devices by path
 * \fB33a7a74    \fR 2014\-04\-10 ~ Always output seccomp error messages to stderr
 \fB$ git status\fR
-On branch fix_typo
-Your branch is ahead of \*(Aqorigin/master\*(Aq by 1 commit\&.
-  (use "git push" to publish your local commits)
-
+# On branch fix_typo
+# Your branch is ahead of \*(Aqorigin/master\*(Aq by 1 commit\&.
+#   (use "git push" to publish your local commits)
+#
 nothing to commit, working directory clean
 \fB$ git cl upload \-r domo@chromium\&.org \-\-send\-mail\fR
 \&.\&.\&. truncated output \&.\&.\&.
 .fi
 .if n \{\
 .RE
 .\}
 .sp
 While we wait for feedback, let\*(Aqs do something else\&.
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
 \fB$ git new\-branch chap2\fR
 \fB$ git map\-branches\fR
 \fBorigin/master
   chap2 *
 \fR  fix_typo
 \fB$ cat >> build/whitespace_file\&.txt <<EOF\fR
 
 "You recall what happened on Mulholland drive?" The ceiling fan rotated slowly
 overhead, barely disturbing the thick cigarette smoke\&. No doubt was left about
 when the fan was last cleaned\&.
 EOF
 \fB$ git status\fR
-On branch chap2
-Your branch is up\-to\-date with \*(Aqorigin/master\*(Aq\&.
-
-Changes not staged for commit:
-  (use "git add <file>\&.\&.\&." to update what will be committed)
-  (use "git checkout \-\- <file>\&.\&.\&." to discard changes in working directory)
-
-        modified:   build/whitespace_file\&.txt
-
+# On branch chap2
+# Your branch is up\-to\-date with \*(Aqorigin/master\*(Aq\&.
+#
+# Changes not staged for commit:
+#   (use "git add <file>\&.\&.\&." to update what will be committed)
+#   (use "git checkout \-\- <file>\&.\&.\&." to discard changes in working directory)
+#
+#       modified:   build/whitespace_file\&.txt
+#
 no changes added to commit (use "git add" and/or "git commit \-a")
 .fi
 .if n \{\
 .RE
 .\}
 .sp
 Someone on the code review pointed out that our typo\-fix has a typo :( We\*(Aqre still working on \*(Aqchap2\*(Aq but we really want to land \*(Aqfix_typo\*(Aq, so let\*(Aqs switch over and fix it\&.
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
 \fB$ git freeze\fR
 \fB$ git checkout fix_typo\fR
 Switched to branch \*(Aqfix_typo\*(Aq
 Your branch is ahead of \*(Aqorigin/master\*(Aq by 1 commit\&.
   (use "git push" to publish your local commits)
 \fB$ echo \-e \*(Aq/Kuun\ens/Kuun/Kun\enwq\*(Aq | ed build/whitespace_file\&.txt\fR
 1501
+1500
 It was a Domo\-Kuun\&.
 It was a Domo\-Kun\&.
-1500
 \fB$ git upstream\-diff \-\-wordwise\fR
 \fBdiff \-\-git a/build/whitespace_file\&.txt b/build/whitespace_file\&.txt\fR
 \fBindex 3eba355\&.\&.57cdcee 100644\fR
 \fB\-\-\- a/build/whitespace_file\&.txt\fR
 \fB+++ b/build/whitespace_file\&.txt\fR
 @@ \-17,7 +17,7 @@ swept up the streets (for it is in London that our scene lies), rattling along
 the housetops, and fiercely agitating the scanty flame of the lamps that
 struggled against the elements\&. A hooded figure emerged\&.
 
 It was a Domo\-BananaKun\&.
@@ skipping 390 matching lines @@
 .IP " 6." 4
 main Chromium waterfall
 .RS 4
 \%http://build.chromium.org
 .RE
 .IP " 7." 4
 here
 .RS 4
 \%https://chromium.googlesource.com/chromium/tools/depot_tools.git
 .RE