Move walkthrough to end of tutorial, add real TL;DR section.
R=scottmg@chromium.org
BUG=261743
Review URL: https://codereview.chromium.org/238203002
git-svn-id: svn://svn.chromium.org/chrome/trunk/tools/depot_tools@263746 0039d316-1c4b-4281-b951-d872f2087c98
diff --git a/docs/html/depot_tools_tutorial.html b/docs/html/depot_tools_tutorial.html
index 3595c59..73c545d 100644
--- a/docs/html/depot_tools_tutorial.html
+++ b/docs/html/depot_tools_tutorial.html
@@ -771,7 +771,7 @@
</li>
<li>
<p>
-<a href="#_tl_dr_walkthrough">TL;DR Walkthrough</a>
+<a href="#_tl_dr">TL;DR</a>
</p>
</li>
<li>
@@ -794,6 +794,11 @@
<a href="#_managing_dependent_cls">Managing dependent CLs</a>
</p>
</li>
+<li>
+<p>
+<a href="#_example_walkthrough">Example Walkthrough</a>
+</p>
+</li>
</ul></div>
<div class="paragraph"><p>Please refer to the manpages (or <code>--help</code> output) for details about any of the
commands mentioned in this tutorial.</p></div>
@@ -979,6 +984,30 @@
</div>
</div>
<div class="sect1">
+<h2 id="_tl_dr">TL;DR</h2>
+<div class="sectionbody">
+<div class="listingblock">
+<div class="content">
+<pre><code><strong><span class="white">$</span></strong> # get the code
+<strong><span class="white">$</span></strong> # In an empty directory:
+<strong><span class="white">$ fetch {chromium,blink,...}</span></strong>
+
+<strong><span class="white">$</span></strong> # Update third_party repos and run pre-compile hooks
+<strong><span class="white">$ gclient sync</span></strong>
+
+<strong><span class="white">$</span></strong> # Make a new change and upload it for review
+<strong><span class="white">$ git new-branch branchname</span></strong>
+<strong><span class="white">$</span></strong> # repeat: [edit, git add, git commit]
+<strong><span class="white">$ git cl upload</span></strong>
+
+<strong><span class="white">$</span></strong> # After change is reviewed, commit with the CQ
+<strong><span class="white">$ git cl set_commit</span></strong>
+<strong><span class="white">$</span></strong> # Note that the committed hash which lands will /not/ match the
+<strong><span class="white">$</span></strong> # commit hashes of your local branch.</code></pre>
+</div></div>
+</div>
+</div>
+<div class="sect1">
<h2 id="_getting_the_code">GETTING THE CODE</h2>
<div class="sectionbody">
<div class="paragraph"><p>Pick an empty directory and run one of the following:</p></div>
@@ -1004,23 +1033,207 @@
<div class="paragraph"><p>And finally:</p></div>
<div class="listingblock">
<div class="content">
-<pre><code><strong><span class="white">$ gclient sync</span></strong> <b><1></b></code></pre>
+<pre><code><strong><span class="white">$ gclient sync</span></strong></code></pre>
</div></div>
-<div class="colist arabic"><ol>
-<li>
-<p>
-This will pull all dependencies of the Chromium src checkout. You will need
-to run this any time you update the main src checkout.
-</p>
-</li>
-</ol></div>
+<div class="paragraph"><p>This will pull all dependencies of the Chromium src checkout. You will need
+to run this any time you update the main src checkout.</p></div>
</div>
</div>
<div class="sect1">
-<h2 id="_tl_dr_walkthrough">TL;DR WALKTHROUGH</h2>
+<h2 id="_creating_uploading_a_cl">CREATING / UPLOADING A CL</h2>
<div class="sectionbody">
-<div class="paragraph"><p>This section will demo what a typical workflow looks like when writing, updating,
-and committing multiple CLs.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">The remainder of the tutorial assumes that your current working directory
+is the <code>src/</code> folder mentioned in <a href="#_getting_the_code">Getting the code</a>.</td>
+</tr></table>
+</div>
+<div class="paragraph"><p>Each CL corresponds exactly with a single branch in git. Any time you want to
+begin a new CL, just:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code><strong><span class="white">$ git new-branch <branch_name></span></strong></code></pre>
+</div></div>
+<div class="paragraph"><p>This will create and checkout a new branch named <code>branch_name</code> which will track
+the default upstream (which is <code>origin/master</code>). See <a href="git-new-branch.html">git-new-branch(1)</a>
+for more features, such as the ability to track <em>LKGR</em>.</p></div>
+<div class="paragraph"><p>Commit as many changes as you like to this branch. When you want to upload it
+for review, run:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code><strong><span class="white">$ git cl upload</span></strong></code></pre>
+</div></div>
+<div class="paragraph"><p>This will take the diff of your branch against its upstream (<code>origin/master</code>),
+and will post it to the <a href="https://codereview.chromium.org">Chromium code
+review site</a>.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_updating_the_code">UPDATING THE CODE</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Inevitably, you’ll want to pull in changes from the main Chromium repo. This is
+pretty easy with <em>depot_tools</em>:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code><strong><span class="white">$ git rebase-update</span></strong></code></pre>
+</div></div>
+<div class="paragraph"><p>This command will update all of your CLs to contain the latest code from their
+upstreams. It will also automatically clean up CLs which have been committed and
+a couple other nice things. See <a href="git-rebase-update.html">git-rebase-update(1)</a> for the full
+scoop.</p></div>
+<div class="paragraph"><p>One thing to look out for are <em>merge conflicts</em>. These happen for exactly the
+same as they do with SVN, but the experience is a little more controllable with
+git. <code>git rebase-update</code> 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 <a href="git-rebase.html">git-rebase(1)</a>). Resolving <code>git rebase</code> merge
+conflicts is beyond the scope of this tutorial, but there are many good sources
+online (see the <a href="#_prerequisites">Prerequisites</a> for some).</p></div>
+<div class="paragraph"><p>Sometimes you’re pretty certain that you’ve committed a certain branch, but <code>git
+rebase-update</code> isn’t able to tell that for sure. This is usually because your
+branch doesn’t rebase cleanly. You could just delete the branch with <code>git branch
+-D <branch></code>, but you’d like to double check the diff of your branch against its
+upstream before deleting it. If this is the case you can abort the rebase
+started by <code>git rebase-update</code>, and then run <a href="git-squash-branch.html">git-squash-branch(1)</a> to
+flatten your branch into a single commit. When you run <code>git rebase-update</code>
+again, you’ll get a (hopefully) much smaller / saner diff. If it turns out you
+were wrong about your branch being fully committed, you can use
+<a href="git-reflog.html">git-reflog(1)</a> to reset your branch back to where it was before. If the
+diff looks inconsequential, you can use <code>git rebase --skip</code> to ignore it, and
+then <code>git rebase-update</code> will clean it up for you.</p></div>
+<div class="paragraph"><p>Once you’re done resolving all of the merge conflict, just run <code>git
+rebase-update</code>, and it will pick up where it left off. Once the command has
+finished updating all of your branches, it will return you back to the branch
+you started on.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">Running <code>git rebase-update</code> will update all your branches, but it will not
+automatically run <code>gclient sync</code> to update your dependencies.</td>
+</tr></table>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_managing_multiple_cls">MANAGING MULTIPLE CLS</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>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 <code>git new-branch <branchname></code>.</p></div>
+<div class="paragraph"><p>Once you start to have more than one CL at a time, it can be easy to lose your
+bearings. Fortunately, <em>depot_tools</em> has two tools to help you out:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code><strong><span class="white">$ git map</span></strong>
+<span class="white blue-background">*</span>​<strong><span class="blue-background red"> 7dcfe47 </span></strong> <span class="green">(</span>​<strong><span class="aqua">frozen_changes</span></strong>​<span class="green">)</span> <span class="yellow">2014-03-12</span> ~ FREEZE.unindexed
+* <strong><span class="red">4b0c180</span></strong> <span class="yellow">2014-03-12</span> ~ modfile
+* <strong><span class="red">59a7cca</span></strong> <span class="yellow">2014-03-12</span> ~ a deleted file
+* <strong><span class="red">6bec695</span></strong> <span class="green">(</span>​<span class="red">origin/master</span>​<span class="green">)</span> <span class="yellow">2014-03-11</span> ~ Add neat feature <strong><span class="white"><(frozen_changes)</span></strong>
+* <strong><span class="red">d15a38a</span></strong> <span class="yellow">2014-03-11</span> ~ Epic README update
+* <strong><span class="red">d559894</span></strong> <span class="green">(</span>​<strong><span class="lime">master</span></strong>​<span class="green">)</span> <span class="yellow">2014-03-11</span> ~ Important upstream change
+<span class="red">|</span> * <strong><span class="red">9c311fd</span></strong> <span class="green">(</span>​<strong><span class="lime">cool_feature</span></strong>​<span class="green">)</span> <span class="yellow">2014-03-11</span> ~ Respond to CL comments
+<span class="red">|</span> <span class="green">|</span> * <strong><span class="red">2a1eeb2</span></strong> <span class="green">(</span>​<strong><span class="lime">subfeature</span></strong>​<span class="green">)</span> <span class="yellow">2014-03-11</span> ~ integrate with CoolService
+<span class="red">|</span> <span class="green">|</span> * <strong><span class="red">d777af6</span></strong> <span class="yellow">2014-03-11</span> ~ slick commenting action
+<span class="red">|</span> <span class="green">|/</span>
+<span class="red">|</span> * <strong><span class="red">265803a</span></strong> <span class="yellow">2014-03-11</span> ~ another improvement <strong><span class="white"><(subfeature)</span></strong>
+<span class="red">|</span> * <strong><span class="red">6d831ac</span></strong> <span class="green">(</span>​<strong><span class="fuchsia">spleen_tag</span></strong>​<span class="green">)</span> <span class="yellow">2014-03-11</span> ~ Refactor spleen
+<span class="red">|</span> * <strong><span class="red">82e74ab</span></strong> <span class="yellow">2014-03-11</span> ~ Add widget
+<span class="red">|/</span>
+* <strong><span class="red">d08c5b3</span></strong> <span class="green">(</span>​<strong><span class="lime">bogus_noparent</span></strong>​<span class="green">)</span> <span class="yellow">2014-03-11</span> ~ Wonderful beginnings <strong><span class="white"><(cool_feature)</span></strong></code></pre>
+</div></div>
+<div class="paragraph"><p>Note that this example repo is in dire need of a <a href="git-rebase-update.html">git-rebase-update(1)</a>!</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code><strong><span class="white">$ git map-branches</span></strong>
+<span class="red">origin/master</span>
+ <span class="green">cool_feature</span>
+ <span class="green">subfeature</span>
+ <span class="aqua">frozen_changes *</span>
+ <span class="green">master</span></code></pre>
+</div></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<a href="git-map.html">git-map(1)</a>
+</dt>
+<dd>
+<p>
+ 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.
+</p>
+</dd>
+<dt class="hdlist1">
+<a href="git-map-branches.html">git-map-branches(1)</a>
+</dt>
+<dd>
+<p>
+ 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).
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Additionally, sometimes you need to switch between branches, but you’ve got work
+in progress. You could use <a href="git-stash.html">git-stash(1)</a>, but that can be tricky to
+manage because you need to remember which branches you stashed what changes on.
+Helpfully <em>depot_tools</em> includes two tools which can greatly assist in case:</p></div>
+<div class="paragraph"><p><a href="git-freeze.html">git-freeze(1)</a> allows you to put the current branch in 'suspended
+animation' 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
+<a href="git-thaw.html">git-thaw(1)</a> to get your work-in-progress changes back to what they were.</p></div>
+<div class="paragraph"><p>Another useful tool is <a href="git-rename-branch.html">git-rename-branch(1)</a>. Unlike <code>git branch -m <old>
+<new></code>, this tool will correctly preserve the upstream relationships of your
+branch compared to its downstreams.</p></div>
+<div class="paragraph"><p>Finally, take a look at <a href="git-upstream-diff.html">git-upstream-diff(1)</a>. This will show you the
+combined diff for all the commits on your branch against the upstream tracking
+branch. This is <em>exactly</em> what <code>git cl upload</code> will push up to code review.
+Additionally, consider trying the <code>--wordwise</code> argument to get a colorized
+per-word diff (instead of a per-line diff).</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_managing_dependent_cls">MANAGING DEPENDENT CLS</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Now that you know how to manage <em>independent</em> CLs, we’ll see how to manage
+<em>dependent</em> 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’t
+compile without CL 1, but you want to submit them as two separate reviews).</p></div>
+<div class="paragraph"><p>Like all of the other CLs we’ve created, we use <a href="git-new-branch.html">git-new-branch(1)</a>, but
+this time with an extra argument. First, <code>git checkout</code> the branch
+you want to base the new one on (i.e. CL 1), and then run:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code><strong><span class="white">$ git new-branch --upstream_current <branch_name></span></strong></code></pre>
+</div></div>
+<div class="paragraph"><p>This will make a new branch which tracks the <em>current</em> branch as its upstream
+(as opposed to <em>origin/master</em>). All changes you commit to this branch will be
+in addition to the previous branch, but when you <code>git cl upload</code>, you will only
+upload the diff for the dependent (child) branch. You may have as many branches
+nested in this fashion as you like.</p></div>
+<div class="paragraph"><p><a href="git-map.html">git-map(1)</a> and <a href="git-map-branches.html">git-map-branches(1)</a> 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:
+<a href="git-nav-upstream.html">git-nav-upstream(1)</a> and <a href="git-nav-downstream.html">git-nav-downstream(1)</a>.</p></div>
+<div class="paragraph"><p>Sometimes when dealing with dependent CLs, it turns out that you accidentally
+based a branch on the wrong upstream, but since then you’ve committed changes to
+it, or even based <em>another</em> branch off of that one. Or you discover that you
+have two independent CLs that would actually be much better off as dependent
+CLs. In instances like these, you can check out the offending branch and use
+<a href="git-reparent-branch.html">git-reparent-branch(1)</a> to move it to track a different parent. Note that
+this can also be used to move a branch from tracking <code>origin/master</code> to <code>lkgr</code>
+or vice versa.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_example_walkthrough">EXAMPLE WALKTHROUGH</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>This section will demo what a typical workflow looks like when writing,
+updating, and committing multiple CLs.</p></div>
<div class="paragraph"><p></p></div><div class="listingblock"><div class="content"><pre><code><span style="font-weight: bold; color: #ffffff">$ fetch chromium</span>
... truncated output ...
<span style="font-weight: bold; color: #ffffff">$ cd src</span>
@@ -1047,10 +1260,10 @@
* <span style="font-weight: bold; color: #e42e16">2250f53 </span><span style="color: #19c518"></span> <span style="color: #e7e71c">2014-04-10</span> ~ ozone: evdev: Filter devices by path
* <span style="font-weight: bold; color: #e42e16">33a7a74 </span><span style="color: #19c518"></span> <span style="color: #e7e71c">2014-04-10</span> ~ Always output seccomp error messages to stderr
<span style="font-weight: bold; color: #ffffff">$ git status</span>
-# On branch fix_typo
-# Your branch is ahead of 'origin/master' by 1 commit.
-# (use "git push" to publish your local commits)
-#
+On branch fix_typo
+Your branch is ahead of 'origin/master' by 1 commit.
+ (use "git push" to publish your local commits)
+
nothing to commit, working directory clean
<span style="font-weight: bold; color: #ffffff">$ git cl upload -r domo@chromium.org --send-mail</span>
... truncated output ...
@@ -1066,15 +1279,15 @@
when the fan was last cleaned.
EOF
<span style="font-weight: bold; color: #ffffff">$ git status</span>
-# On branch chap2
-# Your branch is up-to-date with 'origin/master'.
-#
-# 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)
-#
-# <span style="color: #e42e16">modified: build/whitespace_file.txt</span>
-#
+On branch chap2
+Your branch is up-to-date with 'origin/master'.
+
+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)
+
+ <span style="color: #e42e16">modified: build/whitespace_file.txt</span>
+
no changes added to commit (use "git add" and/or "git commit -a")
</code></pre></div></div><p><div class="paragraph"> Someone on the code review pointed out that our typo-fix has a typo :( We're still working on 'chap2' but we really want to land 'fix_typo', so let's switch over and fix it.</p></div><div class="listingblock"><div class="content"><pre><code><span style="font-weight: bold; color: #ffffff">$ git freeze</span>
<span style="font-weight: bold; color: #ffffff">$ git checkout fix_typo</span>
@@ -1319,196 +1532,6 @@
</div>
</div>
<div class="sect1">
-<h2 id="_creating_uploading_a_cl">CREATING / UPLOADING A CL</h2>
-<div class="sectionbody">
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">The remainder of the tutorial assumes that your current working directory
-is the <code>src/</code> folder mentioned in <a href="#_getting_the_code">Getting the code</a>.</td>
-</tr></table>
-</div>
-<div class="paragraph"><p>Each CL corresponds exactly with a single branch in git. Any time you want to
-begin a new CL, just:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code><strong><span class="white">$ git new-branch <branch_name></span></strong></code></pre>
-</div></div>
-<div class="paragraph"><p>This will create and checkout a new branch named <code>branch_name</code> which will track
-the default upstream (which is <code>origin/master</code>). See <a href="git-new-branch.html">git-new-branch(1)</a>
-for more features, such as the ability to track <em>LKGR</em>.</p></div>
-<div class="paragraph"><p>Commit as many changes as you like to this branch. When you want to upload it
-for review, run:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code><strong><span class="white">$ git cl upload</span></strong></code></pre>
-</div></div>
-<div class="paragraph"><p>This will take the diff of your branch against its upstream (<code>origin/master</code>),
-and will post it to the <a href="https://codereview.chromium.org">Chromium code
-review site</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_updating_the_code">UPDATING THE CODE</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Inevitably, you’ll want to pull in changes from the main Chromium repo. This is
-pretty easy with <em>depot_tools</em>:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code><strong><span class="white">$ git rebase-update</span></strong></code></pre>
-</div></div>
-<div class="paragraph"><p>This command will update all of your CLs to contain the latest code from their
-upstreams. It will also automatically clean up CLs which have been committed and
-a couple other nice things. See <a href="git-rebase-update.html">git-rebase-update(1)</a> for the full
-scoop.</p></div>
-<div class="paragraph"><p>One thing to look out for are <em>merge conflicts</em>. These happen for exactly the
-same as they do with SVN, but the experience is a little more controllable with
-git. <code>git rebase-update</code> 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 <a href="git-rebase.html">git-rebase(1)</a>). Resolving <code>git rebase</code> merge
-conflicts is beyond the scope of this tutorial, but there are many good sources
-online (see the <a href="#_prerequisites">Prerequisites</a> for some).</p></div>
-<div class="paragraph"><p>Sometimes you’re pretty certain that you’ve committed a certain branch, but <code>git
-rebase-update</code> isn’t able to tell that for sure. This is usually because your
-branch doesn’t rebase cleanly. You could just delete the branch with <code>git branch
--D <branch></code>, but you’d like to double check the diff of your branch against its
-upstream before deleting it. If this is the case you can abort the rebase
-started by <code>git rebase-update</code>, and then run <a href="git-squash-branch.html">git-squash-branch(1)</a> to
-flatten your branch into a single commit. When you run <code>git rebase-update</code>
-again, you’ll get a (hopefully) much smaller / saner diff. If it turns out you
-were wrong about your branch being fully committed, you can use
-<a href="git-reflog.html">git-reflog(1)</a> to reset your branch back to where it was before. If the
-diff looks inconsequential, you can use <code>git rebase --skip</code> to ignore it, and
-then <code>git rebase-update</code> will clean it up for you.</p></div>
-<div class="paragraph"><p>Once you’re done resolving all of the merge conflict, just run <code>git
-rebase-update</code>, and it will pick up where it left off. Once the command has
-finished updating all of your branches, it will return you back to the branch
-you started on.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">Running <code>git rebase-update</code> will update all your branches, but it will not
-automatically run <code>gclient sync</code> to update your dependencies.</td>
-</tr></table>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_managing_multiple_cls">MANAGING MULTIPLE CLS</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>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 <code>git new-branch <branchname></code>.</p></div>
-<div class="paragraph"><p>Once you start to have more than one CL at a time, it can be easy to lose your
-bearings. Fortunately, <em>depot_tools</em> has two tools to help you out:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code><strong><span class="white">$ git map</span></strong>
-<span class="white blue-background">*</span>​<strong><span class="blue-background red"> 7dcfe47 </span></strong> <span class="green">(</span>​<strong><span class="aqua">frozen_changes</span></strong>​<span class="green">)</span> <span class="yellow">2014-03-12</span> ~ FREEZE.unindexed
-* <strong><span class="red">4b0c180</span></strong> <span class="yellow">2014-03-12</span> ~ modfile
-* <strong><span class="red">59a7cca</span></strong> <span class="yellow">2014-03-12</span> ~ a deleted file
-* <strong><span class="red">6bec695</span></strong> <span class="green">(</span>​<span class="red">origin/master</span>​<span class="green">)</span> <span class="yellow">2014-03-11</span> ~ Add neat feature <strong><span class="white"><(frozen_changes)</span></strong>
-* <strong><span class="red">d15a38a</span></strong> <span class="yellow">2014-03-11</span> ~ Epic README update
-* <strong><span class="red">d559894</span></strong> <span class="green">(</span>​<strong><span class="lime">master</span></strong>​<span class="green">)</span> <span class="yellow">2014-03-11</span> ~ Important upstream change
-<span class="red">|</span> * <strong><span class="red">9c311fd</span></strong> <span class="green">(</span>​<strong><span class="lime">cool_feature</span></strong>​<span class="green">)</span> <span class="yellow">2014-03-11</span> ~ Respond to CL comments
-<span class="red">|</span> <span class="green">|</span> * <strong><span class="red">2a1eeb2</span></strong> <span class="green">(</span>​<strong><span class="lime">subfeature</span></strong>​<span class="green">)</span> <span class="yellow">2014-03-11</span> ~ integrate with CoolService
-<span class="red">|</span> <span class="green">|</span> * <strong><span class="red">d777af6</span></strong> <span class="yellow">2014-03-11</span> ~ slick commenting action
-<span class="red">|</span> <span class="green">|/</span>
-<span class="red">|</span> * <strong><span class="red">265803a</span></strong> <span class="yellow">2014-03-11</span> ~ another improvement <strong><span class="white"><(subfeature)</span></strong>
-<span class="red">|</span> * <strong><span class="red">6d831ac</span></strong> <span class="green">(</span>​<strong><span class="fuchsia">spleen_tag</span></strong>​<span class="green">)</span> <span class="yellow">2014-03-11</span> ~ Refactor spleen
-<span class="red">|</span> * <strong><span class="red">82e74ab</span></strong> <span class="yellow">2014-03-11</span> ~ Add widget
-<span class="red">|/</span>
-* <strong><span class="red">d08c5b3</span></strong> <span class="green">(</span>​<strong><span class="lime">bogus_noparent</span></strong>​<span class="green">)</span> <span class="yellow">2014-03-11</span> ~ Wonderful beginnings <strong><span class="white"><(cool_feature)</span></strong></code></pre>
-</div></div>
-<div class="paragraph"><p>Note that this example repo is in dire need of a <a href="git-rebase-update.html">git-rebase-update(1)</a>!</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code><strong><span class="white">$ git map-branches</span></strong>
-<span class="red">origin/master</span>
- <span class="green">cool_feature</span>
- <span class="green">subfeature</span>
- <span class="aqua">frozen_changes *</span>
- <span class="green">master</span></code></pre>
-</div></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<a href="git-map.html">git-map(1)</a>
-</dt>
-<dd>
-<p>
- 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.
-</p>
-</dd>
-<dt class="hdlist1">
-<a href="git-map-branches.html">git-map-branches(1)</a>
-</dt>
-<dd>
-<p>
- 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).
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Additionally, sometimes you need to switch between branches, but you’ve got work
-in progress. You could use <a href="git-stash.html">git-stash(1)</a>, but that can be tricky to
-manage because you need to remember which branches you stashed what changes on.
-Helpfully <em>depot_tools</em> includes two tools which can greatly assist in case:</p></div>
-<div class="paragraph"><p><a href="git-freeze.html">git-freeze(1)</a> allows you to put the current branch in 'suspended
-animation' 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
-<a href="git-thaw.html">git-thaw(1)</a> to get your work-in-progress changes back to what they were.</p></div>
-<div class="paragraph"><p>Another useful tool is <a href="git-rename-branch.html">git-rename-branch(1)</a>. Unlike <code>git branch -m <old>
-<new></code>, this tool will correctly preserve the upstream relationships of your
-branch compared to its downstreams.</p></div>
-<div class="paragraph"><p>Finally, take a look at <a href="git-upstream-diff.html">git-upstream-diff(1)</a>. This will show you the
-combined diff for all the commits on your branch against the upstream tracking
-branch. This is <em>exactly</em> what <code>git cl upload</code> will push up to code review.
-Additionally, consider trying the <code>--wordwise</code> argument to get a colorized
-per-word diff (instead of a per-line diff).</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_managing_dependent_cls">MANAGING DEPENDENT CLS</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Now that you know how to manage <em>independent</em> CLs, we’ll see how to manage
-<em>dependent</em> 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’t
-compile without CL 1, but you want to submit them as two separate reviews).</p></div>
-<div class="paragraph"><p>Like all of the other CLs we’ve created, we use <a href="git-new-branch.html">git-new-branch(1)</a>, but
-this time with an extra argument. First, <code>git checkout</code> the branch
-you want to base the new one on (i.e. CL 1), and then run:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code><strong><span class="white">$ git new-branch --upstream_current <branch_name></span></strong></code></pre>
-</div></div>
-<div class="paragraph"><p>This will make a new branch which tracks the <em>current</em> branch as its upstream
-(as opposed to <em>origin/master</em>). All changes you commit to this branch will be
-in addition to the previous branch, but when you <code>git cl upload</code>, you will only
-upload the diff for the dependent (child) branch. You may have as many branches
-nested in this fashion as you like.</p></div>
-<div class="paragraph"><p><a href="git-map.html">git-map(1)</a> and <a href="git-map-branches.html">git-map-branches(1)</a> 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:
-<a href="git-nav-upstream.html">git-nav-upstream(1)</a> and <a href="git-nav-downstream.html">git-nav-downstream(1)</a>.</p></div>
-<div class="paragraph"><p>Sometimes when dealing with dependent CLs, it turns out that you accidentally
-based a branch on the wrong upstream, but since then you’ve committed changes to
-it, or even based <em>another</em> branch off of that one. Or you discover that you
-have two independent CLs that would actually be much better off as dependent
-CLs. In instances like these, you can check out the offending branch and use
-<a href="git-reparent-branch.html">git-reparent-branch(1)</a> to move it to track a different parent. Note that
-this can also be used to move a branch from tracking <code>origin/master</code> to <code>lkgr</code>
-or vice versa.</p></div>
-</div>
-</div>
-<div class="sect1">
<h2 id="_conclusion">CONCLUSION</h2>
<div class="sectionbody">
<div class="paragraph"><p>Hopefully that gives you a good starting overview on Chromium development using
@@ -1564,7 +1587,7 @@
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
-Last updated 2014-04-10 21:30:33 PDT
+Last updated 2014-04-14 16:26:14 PDT
</div>
</div>
</body>
diff --git a/docs/man7/depot_tools_tutorial.7 b/docs/man7/depot_tools_tutorial.7
index d4ec51d..c8b65ad 100644
--- a/docs/man7/depot_tools_tutorial.7
+++ b/docs/man7/depot_tools_tutorial.7
@@ -2,12 +2,12 @@
.\" 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/10/2014
+.\" Date: 04/14/2014
.\" Manual: Chromium depot_tools Manual
-.\" Source: depot_tools bec7be9
+.\" Source: depot_tools e722300
.\" Language: English
.\"
-.TH "DEPOT_TOOLS_TUTORIAL" "7" "04/10/2014" "depot_tools bec7be9" "Chromium depot_tools Manual"
+.TH "DEPOT_TOOLS_TUTORIAL" "7" "04/14/2014" "depot_tools e722300" "Chromium depot_tools Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@@ -63,7 +63,7 @@
.sp -1
.IP \(bu 2.3
.\}
-TL;DR Walkthrough
+TL;DR
.RE
.sp
.RS 4
@@ -110,6 +110,17 @@
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
@@ -247,6 +258,33 @@
.RE
.\}
.sp
+.SH "TL;DR"
+.sp
+.if n \{\
+.RS 4
+.\}
+.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$\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
+.\}
+.sp
.SH "GETTING THE CODE"
.sp
Pick an empty directory and run one of the following:
@@ -298,16 +336,190 @@
.RS 4
.\}
.nf
-\fB$ gclient sync\fR \fB(1)\fR
+\fB$ gclient sync\fR
.fi
.if n \{\
.RE
.\}
.sp
.sp
-\fB1. \fRThis 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\&.
+.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
-.SH "TL;DR WALKTHROUGH"
+.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:
+.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\&.
+.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\&.
+.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
+.if n \{\
+.RE
+.\}
+.sp
+.sp
+This command will update all of your CLs to contain the latest code from their upstreams\&. It will also automatically clean up CLs which have been committed and a couple other nice things\&. See \fBgit-rebase-update\fR(1) for the full scoop\&.
+.sp
+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 with 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 conflicts is beyond the scope of this tutorial, but there are many good sources online (see the Prerequisites for some)\&.
+.sp
+Sometimes you\(cqre pretty certain that you\(cqve committed a certain branch, but git rebase\-update isn\(cqt able to tell that for sure\&. This is usually because your branch doesn\(cqt rebase cleanly\&. You could just delete the branch with git branch \-D <branch>, but you\(cqd like to double check the diff of your branch against its upstream before deleting it\&. If this is the case you can abort the rebase started by git rebase\-update, and then run \fBgit-squash-branch\fR(1) to flatten your branch into a single commit\&. When you run git rebase\-update 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-reflog\fR(1) to reset your branch back to where it was before\&. If the diff looks inconsequential, you can use git rebase \-\-skip to ignore it, and then git rebase\-update will clean it up for you\&.
+.sp
+Once you\(cqre done resolving all of the merge conflict, just run git rebase\-update, and it will pick up where it left off\&. Once the command has finished updating all of your branches, it will return you back to the branch you started on\&.
+.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
+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>\&.
+.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
+* \fB59a7cca\fR 2014\-03\-12 ~ a deleted file
+* \fB6bec695\fR (\:origin/master\:) 2014\-03\-11 ~ Add neat feature \fB<(frozen_changes)\fR
+* \fBd15a38a\fR 2014\-03\-11 ~ Epic README update
+* \fBd559894\fR (\:\fBmaster\fR\:) 2014\-03\-11 ~ Important upstream change
+| * \fB9c311fd\fR (\:\fBcool_feature\fR\:) 2014\-03\-11 ~ Respond to CL comments
+| | * \fB2a1eeb2\fR (\:\fBsubfeature\fR\:) 2014\-03\-11 ~ integrate with CoolService
+| | * \fBd777af6\fR 2014\-03\-11 ~ slick commenting action
+| |/
+| * \fB265803a\fR 2014\-03\-11 ~ another improvement \fB<(subfeature)\fR
+| * \fB6d831ac\fR (\:\fBspleen_tag\fR\:) 2014\-03\-11 ~ Refactor spleen
+| * \fB82e74ab\fR 2014\-03\-11 ~ Add widget
+|/
+* \fBd08c5b3\fR (\:\fBbogus_noparent\fR\:) 2014\-03\-11 ~ Wonderful beginnings \fB<(cool_feature)\fR
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.sp
+Note that this example repo is in dire need of a \fBgit-rebase-update\fR(1)!
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+\fB$ git map\-branches\fR
+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)\&.
+.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"
+.sp
+Now that you know how to manage \fIindependent\fR CLs, we\(cqll see how to manage \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 reviews)\&.
+.sp
+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 base the new one on (i\&.e\&. CL 1), and then run:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+\fB$ git new\-branch \-\-upstream_current <branch_name>\fR
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.sp
+This will make a new branch which tracks the \fIcurrent\fR branch as its upstream (as opposed to \fIorigin/master\fR)\&. All changes you commit to this branch will 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 branches nested in this fashion as you like\&.
+.sp
+\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-upstream\fR(1) and \fBgit-nav-downstream\fR(1)\&.
+.sp
+Sometimes when dealing with dependent CLs, it turns out that you accidentally based a branch on the wrong upstream, but since then you\(cqve committed changes to 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 dependent 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 that this can also be used to move a branch from tracking origin/master to lkgr or vice versa\&.
+.SH "EXAMPLE WALKTHROUGH"
.sp
This section will demo what a typical workflow looks like when writing, updating, and committing multiple CLs\&.
.sp
@@ -376,10 +588,10 @@
* \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 \&.\&.\&.
@@ -406,15 +618,15 @@
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 \{\
@@ -780,181 +992,6 @@
.sp
.sp
So there you have the basic flow\&. Note that you don\(cqt \fIhave\fR to do chromium development using these tools\&. Any git workflow is compatible, as long as git cl upload is able to upload good patches\&.
-.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:
-.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\&.
-.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\&.
-.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
-.if n \{\
-.RE
-.\}
-.sp
-.sp
-This command will update all of your CLs to contain the latest code from their upstreams\&. It will also automatically clean up CLs which have been committed and a couple other nice things\&. See \fBgit-rebase-update\fR(1) for the full scoop\&.
-.sp
-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 with 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 conflicts is beyond the scope of this tutorial, but there are many good sources online (see the Prerequisites for some)\&.
-.sp
-Sometimes you\(cqre pretty certain that you\(cqve committed a certain branch, but git rebase\-update isn\(cqt able to tell that for sure\&. This is usually because your branch doesn\(cqt rebase cleanly\&. You could just delete the branch with git branch \-D <branch>, but you\(cqd like to double check the diff of your branch against its upstream before deleting it\&. If this is the case you can abort the rebase started by git rebase\-update, and then run \fBgit-squash-branch\fR(1) to flatten your branch into a single commit\&. When you run git rebase\-update 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-reflog\fR(1) to reset your branch back to where it was before\&. If the diff looks inconsequential, you can use git rebase \-\-skip to ignore it, and then git rebase\-update will clean it up for you\&.
-.sp
-Once you\(cqre done resolving all of the merge conflict, just run git rebase\-update, and it will pick up where it left off\&. Once the command has finished updating all of your branches, it will return you back to the branch you started on\&.
-.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
-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>\&.
-.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
-* \fB59a7cca\fR 2014\-03\-12 ~ a deleted file
-* \fB6bec695\fR (\:origin/master\:) 2014\-03\-11 ~ Add neat feature \fB<(frozen_changes)\fR
-* \fBd15a38a\fR 2014\-03\-11 ~ Epic README update
-* \fBd559894\fR (\:\fBmaster\fR\:) 2014\-03\-11 ~ Important upstream change
-| * \fB9c311fd\fR (\:\fBcool_feature\fR\:) 2014\-03\-11 ~ Respond to CL comments
-| | * \fB2a1eeb2\fR (\:\fBsubfeature\fR\:) 2014\-03\-11 ~ integrate with CoolService
-| | * \fBd777af6\fR 2014\-03\-11 ~ slick commenting action
-| |/
-| * \fB265803a\fR 2014\-03\-11 ~ another improvement \fB<(subfeature)\fR
-| * \fB6d831ac\fR (\:\fBspleen_tag\fR\:) 2014\-03\-11 ~ Refactor spleen
-| * \fB82e74ab\fR 2014\-03\-11 ~ Add widget
-|/
-* \fBd08c5b3\fR (\:\fBbogus_noparent\fR\:) 2014\-03\-11 ~ Wonderful beginnings \fB<(cool_feature)\fR
-.fi
-.if n \{\
-.RE
-.\}
-.sp
-.sp
-Note that this example repo is in dire need of a \fBgit-rebase-update\fR(1)!
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
-\fB$ git map\-branches\fR
-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)\&.
-.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"
-.sp
-Now that you know how to manage \fIindependent\fR CLs, we\(cqll see how to manage \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 reviews)\&.
-.sp
-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 base the new one on (i\&.e\&. CL 1), and then run:
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
-\fB$ git new\-branch \-\-upstream_current <branch_name>\fR
-.fi
-.if n \{\
-.RE
-.\}
-.sp
-.sp
-This will make a new branch which tracks the \fIcurrent\fR branch as its upstream (as opposed to \fIorigin/master\fR)\&. All changes you commit to this branch will 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 branches nested in this fashion as you like\&.
-.sp
-\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-upstream\fR(1) and \fBgit-nav-downstream\fR(1)\&.
-.sp
-Sometimes when dealing with dependent CLs, it turns out that you accidentally based a branch on the wrong upstream, but since then you\(cqve committed changes to 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 dependent 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 that this can also be used to move a branch from tracking origin/master to lkgr or vice versa\&.
.SH "CONCLUSION"
.sp
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 tutorial or the man pages for the tools (see the index of all tools here: \fBdepot_tools\fR(7)), please feel free to ask\&.
diff --git a/docs/src/depot_tools_tutorial.demo.tldr.sh b/docs/src/depot_tools_tutorial.demo.walkthrough.sh
similarity index 100%
rename from docs/src/depot_tools_tutorial.demo.tldr.sh
rename to docs/src/depot_tools_tutorial.demo.walkthrough.sh
diff --git a/docs/src/depot_tools_tutorial.txt b/docs/src/depot_tools_tutorial.txt
index 5d08da4..6c81e68 100644
--- a/docs/src/depot_tools_tutorial.txt
+++ b/docs/src/depot_tools_tutorial.txt
@@ -16,11 +16,12 @@
* <<_setting_up,Setting up>>
* <<_getting_the_code,Getting the code>>
-* <<_tl_dr_walkthrough,TL;DR Walkthrough>>
+* <<_tl_dr,TL;DR>>
* <<_creating_uploading_a_cl,Creating / Uploading a CL>>
* <<_updating_the_code,Updating the code>>
* <<_managing_multiple_cls,Managing multiple CLs>>
* <<_managing_dependent_cls,Managing dependent CLs>>
+* <<_example_walkthrough,Example Walkthrough>>
Please refer to the manpages (or `--help` output) for details about any of the
commands mentioned in this tutorial.
@@ -145,6 +146,29 @@
[white]**$ git config --global color.ui true**
----
+TL;DR
+-----
+[postsubs="quotes"]
+----
+[white]**$** # get the code
+[white]**$** # In an empty directory:
+[white]**$ fetch {chromium,blink,...}**
+
+[white]**$** # Update third_party repos and run pre-compile hooks
+[white]**$ gclient sync**
+
+[white]**$** # Make a new change and upload it for review
+[white]**$ git new-branch branchname**
+[white]**$** # repeat: [edit, git add, git commit]
+[white]**$ git cl upload**
+
+[white]**$** # After change is reviewed, commit with the CQ
+[white]**$ git cl set_commit**
+[white]**$** # Note that the committed hash which lands will /not/ match the
+[white]**$** # commit hashes of your local branch.
+----
+
+
GETTING THE CODE
----------------
Pick an empty directory and run one of the following:
@@ -177,24 +201,13 @@
[postsubs="quotes"]
----
-[white]**$ gclient sync** <1>
+[white]**$ gclient sync**
----
-<1> This will pull all dependencies of the Chromium src checkout. You will need
+
+This will pull all dependencies of the Chromium src checkout. You will need
to run this any time you update the main src checkout.
-TL;DR WALKTHROUGH
------------------
-This section will demo what a typical workflow looks like when writing, updating,
-and committing multiple CLs.
-
-demo:tldr[]
-
-So there you have the basic flow. Note that you don't 'have' to do chromium
-development using these tools. Any git workflow is compatible, as long as
-`git cl upload` is able to upload good patches.
-
-
CREATING / UPLOADING A CL
-------------------------
NOTE: The remainder of the tutorial assumes that your current working directory
@@ -379,6 +392,18 @@
or vice versa.
+EXAMPLE WALKTHROUGH
+-------------------
+This section will demo what a typical workflow looks like when writing,
+updating, and committing multiple CLs.
+
+demo:walkthrough[]
+
+So there you have the basic flow. Note that you don't 'have' to do chromium
+development using these tools. Any git workflow is compatible, as long as
+`git cl upload` is able to upload good patches.
+
+
CONCLUSION
----------
Hopefully that gives you a good starting overview on Chromium development using
