Add a basic tutorial for the tools in depot_tools.

docs/src/depot_tools_tutorial.txt

+depot_tools_tutorial(7)
+=======================
+
+NAME
+----
+depot_tools_tutorial - A tutorial introduction to the Chromium depot_tools git
+extensions.
+
+DESCRIPTION
+-----------
+
+The Chromium linkgit:depot_tools[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

[agable, 2014/04/04 23:34:12]

nit: two spaces? Really?

[iannucci, 2014/04/05 01:31:13]

Picky picky...

+Chromium using these tools. This will cover:
+
+* <<_setting_up,Setting up>>
+* <<_getting_the_code,Getting the code>>
+* <<_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>>
+
+Please refer to the manpages (or `--help` output) for details about any of the
+commands mentioned in this tutorial.
+
+[NOTE]
+If your platform does not support manpages (or you prefer something a bit more
+expressive than plain text) you can find all documentation in 'html' form in the
+`[DEPOT_TOOLS]/docs/html` folder.
+
+PREREQUISITES
+~~~~~~~~~~~~~
+This tutorial will assume some basic familarity with git terminology and basic
+premises. If you need to brush up on these, the following are very good
+resources:
+
+* link:http://git-scm.com/book[Pro Git book] - Pretty good overview of git to

[Ryan Tseng, 2014/04/05 00:51:20]

While a good resource, I wouldn't list it as the first link for a reader with
"little to moderate attention span".

I think a good "Pre-req" is:
* Read chapter 1 and 2 of the pro git book
* Lab 01 - 09 off gitimmersion.com
* (Optional) Intro sequence #1, #2, #4 of learnGitBranching

[iannucci, 2014/04/05 01:31:13]

I restructured this section a bit. PTAL.

+  bootstrap a working knowledge.
+* link:http://gitimmersion.com/[Git Immersion Tutorial] - An in-depth git
+  tutorial.
+* link:http://pcottle.github.io/learnGitBranching[pcottle's Visual Git
+  Branching] - An excellent interactive/graphical demo on how git handles
+  commits, branches, and shows the operations git performs on them.
+
+SETTING UP
+----------
+
+GET DEPOT TOOLS
+~~~~~~~~~~~~~~~
+
+ifdef::backend-xhtml11[]
+LINUX / MAC
+^^^^^^^^^^^
+endif::backend-xhtml11[]
+Clone the 'depot_tools' repository:
+
+[subs="quotes"]
+----
+[white]**$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools**
+----
+
+Add 'depot_tools' to the 'end' of your PATH and MANPATH (you will probably want
+to put this in your `~/.bashrc` or `~/.zshrc`).  Assuming you cloned
+'depot_tools' to `/path/to/depot_tools`:
+
+[postsubs="quotes"]
+----
+[white]**$ export PATH=$PATH:/path/to/depot_tools**
+[white]**$ export MANPATH=$MANPATH:/path/to/depot_tools/docs**  <1>
+----
+<1> Observe that this path is +depot_tools/+**+docs+**.
+
+// No need to show the Windows stuff on the manpage output.
+ifdef::backend-xhtml11[]
+WINDOWS
+^^^^^^^
+Download the 'depot_tools'
+link:https://src.chromium.org/svn/trunk/tools/depot_tools.zip[bundle] and
+extract it somewhere.
+
+[WARNING]
+*DO NOT* use drag-n-drop or copy-n-paste extract from Explorer, this will not
+extract the hidden ``.git'' folder which is necessary for 'depot_tools' to
+autoupdate itself. You can use ``Extract all...'' from the context menu though.
+
+Add 'depot_tools' to the 'end' of your PATH.  Assuming you unzipped the
+bundle to `C:\workspace\depot_tools`:
+
+With Administrator access: ::
+  *Control Panel -> System and Security -> System -> Advanced system settings*
++
+Modify the PATH system variable to include `C:\workspace\depot_tools`.
+
+Without Administrator access: ::
+  *Control Panel -> User Accounts -> User Accounts -> Change my environment variables*
++
+Add a PATH user variable: `%PATH%;C:\workspace\depot_tools`.
+
+From a `cmd.exe` shell, run the command `gclient` (without arguments).  On first
+run, gclient will install all the Windows-specific bits needed to work with the
+code, including msysgit and python.
+
+[NOTE]
+=====
+* If you run gclient from a non-cmd shell (e.g., cygwin, PowerShell), it
+  may appear to run properly, but msysgit, python, and other tools may not get
+  installed correctly.
+* If you see strange errors with the file system on the first run of gclient,
+  you may want to link:http://tortoisesvn.tigris.org/faq.html#cantmove2[disable
+  Windows Indexing].
+* If you are running Windows XP and see errors like ``The system cannot execute
+  the specified program'', try installing the
+  link:http://code.google.com/p/chromium/issues/detail?id=75886[``Microsoft
+  Visual C++ 2008 Redistributable Package''].
+=====
+endif::backend-xhtml11[]
+
+BOOTSTRAPPING CONFIGURATION
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you have never used git before, you’ll need to set some global git
+configurations; substitute your name and email address in the following
+commands:
+
+[subs="quotes,attributes"]
+----
+[white]**$ git config --global user.name ``John Doe''**
+[white]**$ git config --global user.email ``jdoe@email.com''**
+[white]**$ git config --global core.autocrlf false**
+[white]**$ git config --global core.filemode false**
+[white]**$** # and for fun!
+[white]**$ git config --global color.ui true**
+----
+
+GETTING THE CODE
+----------------
+Pick an empty directory and run one of the following:
+
+[subs="quotes"]
+----
+[white]**$ fetch chromium**  # Basic checkout for desktop Chromium
+[white]**$ fetch blink**     # Chromium code with blink checked out to tip-of-tree

[Ryan Tseng, 2014/04/05 00:51:20]

Blink (is a proper noun)

[iannucci, 2014/04/05 01:31:13]

Done.

+[white]**$ fetch android**   # Chromium checkout for Android platform
+[white]**$ fetch ios**       # Chromium checkout for iOS platform
+----
+
+When the `fetch` tool completes you should have the following in your working
+directory:
+
+[subs="quotes"]
+----
+[white]**.gclient**   # A configuration file for you source checkout
+[white]**src/**       # Top-level Chromium source checkout.
+----
+
+If you are on linux, then you'll need to run:
+
+[subs="specialcharacters,quotes"]
+----
+[white]**$ cd src && ./build/install-build-deps.sh**
+----
+
+And finally:
+
+[postsubs="quotes"]
+----
+[white]**$ gclient sync** <1>
+----
+<1> This will pull all dependencies of the Chromium src checkout. You will need
+to run this any time you update the main src checkout.
+
+
+CREATING / UPLOADING A CL
+-------------------------
+NOTE: The remainder of the tutorial assumes that your current working directory
+is the `src/` folder mentioned in <<_getting_the_code,Getting the code>>.
+
+Each CL corresponds exactly with a single branch in git. Any time you want to
+begin a new CL, just:
+
+[subs="specialcharacters,quotes"]
+----
+[white]**$ git new-branch <branch_name>**
+----
+
+This will create and checkout a new branch named `branch_name` which will track
+the default upstream (which is `origin/master`). See linkgit:git-new-branch[1]
+for more features, such as the ability to track 'LKGR'.
+
+Commit as many changes as you like to this branch. When you want to upload it
+for review, run:
+
+[subs="quotes"]
+----
+[white]**$ git cl upload**
+----
+
+This will take the diff of your branch against it's upstream (`origin/master`),

[agable, 2014/04/04 23:18:58]

its

[iannucci, 2014/04/05 01:31:13]

Done.

+and will post it to the link:https://codereview.chromium.org[Chromium code
+review site].
+
+
+UPDATING THE CODE
+-----------------
+Inevitably, you'll want to pull in changes from the main Chromium repo. This is
+pretty easy with 'depot_tools':
+
+[subs="quotes"]
+----
+[white]**$ git rebase-update**
+----
+
+This command will update all of your CLs to contain the latest code from their

[Ryan Tseng, 2014/04/05 00:51:20]

'Like "svn update", this command will....'

If we want to draw analogies to svn, might as well go all the way and state
their closest equivalence

[iannucci, 2014/04/05 01:31:13]

Erg, I'd rather not. I'm not really doing that anywhere else in the tutorial
(except mentioning it once in the paragraph below).

+upstreams. It will also automatically clean up CLs which have been committed and
+a couple other nice things :). See linkgit:git-rebase-update[1] for the full

[agable, 2014/04/04 23:34:12]

ditch smiley

[iannucci, 2014/04/05 01:31:13]

:(

+scoop.
+
+One thing to look out for are 'merge conflicts'. 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

[Ryan Tseng, 2014/04/05 00:51:20]

"Rebase" isn't really in my vocabulary when i was new to git.  From SVN, "update
all your branches for you" seems more intuitive.

Of course if you assume git knowledge, just saying "This command will fetch and
then rebase all of your branches for you" will make sense and be sufficient.

[iannucci, 2014/04/05 01:31:13]

They'll have to learn what rebasing is. Is the previous paragraph not enough of
a hand-wave summary?

+encounters a merge conflict in one, it will halt and leave you in a rebase
+conflict state (see linkgit:git-rebase[1]). Resolving `git rebase` merge
+conflicts is beyond the scope of this tutorial, but there are many good sources
+online (see the <<_prerequisites,Prerequisites>> for some).
+
+Sometimes you're pretty certain that you've committed a certain branch, but `git

[agable, 2014/04/04 23:34:12]

This is a poorly constructed sentence: "Sometimes, but, and." Refactor.

[iannucci, 2014/04/05 01:31:13]

PTAL

+rebase-update` isn't able to tell that because your branch doesn't rebase
+cleanly, and 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, and
+then run linkgit:git-squash-branch[1] to flatten your branch into a single
+commit. When you run `git rebase-update` again, you'll get a (hopefully) much
+smaller / saner diff. If it turns out you were wrong, you can use
+linkgit:git-reflog[1] to reset your branch back to where it was.
+
+Once you're 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.
+
+[NOTE]
+Running `git rebase-update` will update all your branches, but it will not
+automatically run `gclient sync` to update your dependencies.
+
+
+MANAGING MULTIPLE CLS
+---------------------
+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>`.
+
+Once you start to have more than one CL at a time, it can be easy to lose your
+bearings. Fortunately, 'depot_tools' has two tools to help you out:
+
+[subs="specialcharacters,quotes,attributes"]
+----
+[white]**$ git map**
+[white blue-background]##*##{zwsp}[blue-background red]** 7dcfe47       ** [green]##(##{zwsp}[aqua]**frozen_changes**{zwsp}[green]##)## [yellow]##2014-03-12## \~ FREEZE.unindexed
+* [red]**4b0c180**        [yellow]##2014-03-12## \~ modfile
+* [red]**59a7cca**        [yellow]##2014-03-12## \~ a deleted file
+* [red]**6bec695**        [green]##(##{zwsp}[red]##origin/master##{zwsp}[green]##)## [yellow]##2014-03-11## \~ Add neat feature    [white]**<(frozen_changes)**
+* [red]**d15a38a**        [yellow]##2014-03-11## \~ Epic README update
+* [red]**d559894**        [green]##(##{zwsp}[lime]**master**{zwsp}[green]##)## [yellow]##2014-03-11## \~ Important upstream change
+[red]##|## * [red]**9c311fd**      [green]##(##{zwsp}[lime]**cool_feature**{zwsp}[green]##)## [yellow]##2014-03-11## \~ Respond to CL comments
+[red]##|## [green]##|## * [red]**2a1eeb2**    [green]##(##{zwsp}[lime]**subfeature**{zwsp}[green]##)## [yellow]##2014-03-11## \~ integrate with CoolService
+[red]##|## [green]##|## * [red]**d777af6**    [yellow]##2014-03-11## \~ slick commenting action
+[red]##|## [green]##|/##
+[red]##|## * [red]**265803a**      [yellow]##2014-03-11## \~ another improvement    [white]**<(subfeature)**
+[red]##|## * [red]**6d831ac**      [green]##(##{zwsp}[fuchsia]**spleen_tag**{zwsp}[green]##)## [yellow]##2014-03-11## \~ Refactor spleen
+[red]##|## * [red]**82e74ab**      [yellow]##2014-03-11## \~ Add widget
+[red]##|/##
+* [red]**d08c5b3**        [green]##(##{zwsp}[lime]**bogus_noparent**{zwsp}[green]##)## [yellow]##2014-03-11## ~ Wonderful beginnings    [white]**<(cool_feature)**
+----
+Note that this example repo is in dire need of a linkgit:git-rebase-update[1]!
+
+[subs="quotes"]
+----
+[white]**$ git map-branches**
+[red]#origin/master#
+  [green]#cool_feature#
+    [green]#subfeature#
+  [aqua]#frozen_changes *#
+  [green]#master#
+----
+
+linkgit:git-map[1]::
+  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.
+
+linkgit:git-map-branches[1]::
+  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).
+
+Additionally, sometimes you need to switch between branches, but you've got work
+in progress. You could use linkgit:git-stash[1], but that can be tricky to
+manage because you need to remember which branches you stashed what changes on.
+Helpfully 'depot_tools' includes two tools which can greatly assist in case:
+
+linkgit:git-freeze[1] 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
+linkgit:git-thaw[1] to get your work-in-progress changes back to what they were.
+
+Another useful tool is linkgit:git-rename-branch[1]. No, I'm not going to

[agable, 2014/04/04 23:34:12]

dry humor

[iannucci, 2014/04/05 01:31:13]

Done.

+explain what it does.
+
+Finally, take a look at linkgit:git-upstream-diff[1]. This will show you the
+combined diff for all the commits on your branch against the upstream tracking
+branch. This is 'exactly' 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).
+
+MANAGING DEPENDENT CLS
+----------------------
+Now that you know how to manage <<_managing_multiple_cls,'independent' CLs>>,

[agable, 2014/04/04 23:34:12]

No need to reference previous section.

[iannucci, 2014/04/05 01:31:13]

Done.

+we'll see how to manage 'dependent' 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).
+
+Like all of the other CLs we've created, we use linkgit:git-new-branch[1], but
+this time with a (not very surprising) twist. First, `git checkout` the branch

[agable, 2014/04/04 23:34:12]

with a twist? Really?

[iannucci, 2014/04/05 01:31:13]

*sigh*

+you want to base the new one on (i.e. CL 1), and then run:
+
+[subs="specialcharacters,quotes"]
+----
+[white]**$ git new-branch --upstream_current <branch_name>**
+----
+
+This will make a new branch which tracks the 'current' branch as its upstream
+(as opposed to 'origin/master'). 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.
+
+linkgit:git-map[1] and linkgit:git-map-branches[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:
+linkgit:git-nav-upstream[1] and linkgit:git-nav-downstream[1].
+
+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 'another' branch off of that one. Or say that you have two

[agable, 2014/04/04 23:34:12]

"Or say that you..." is a bad construction; it does not parallel the previous
sentence.

[iannucci, 2014/04/05 01:31:13]

Done.

+independent CLs that would actually be much better off as dependent CLs. Not to

[agable, 2014/04/04 23:34:12]

"Not to worry..." -> "This can be fixed by..." or something.

[iannucci, 2014/04/05 01:31:13]

Done.

+worry, because you can just check out the offending branch and use
+linkgit:git-reparent-branch[1] to move it around the tree.
+
+
+CONCLUSION
+----------
+Well that wraps up the whirlwind tour of the 'depot_tools' helper tools. If you

[agable, 2014/04/04 23:34:12]

This paragraph is too cute. You're a teacher, not a tour guide.

[iannucci, 2014/04/05 01:31:13]

Done.

+have questions which weren't answered by this tutorial or the man pages for the
+tools (see the index of all tools here: linkgit:depot_tools[7]), please ask :).
+
+
+GLOSSARY
+--------
+
+CL::
+  A 'change-list'. This is a diff which you would like to commit to the
+  codebase.
+
+DEPS::
+  A file in the chromium checkout which `gclient sync` uses to determine what
+  dependencies to pull in. This file also contains 'hooks'.
+
+LKGR::
+  Last Known Good Revision. This is a linkgit:git-tag[1] which tracks the last
+  version of `origin/master` which has passed the full set of testing on the
+  link:http://build.chromium.org[main Chromium waterfall].
+
+include::_footer.txt[]
+
+// vim: ft=asciidoc: