Add a tutorial / walkthrough for pure-git workflow.
TBR=agable@chromium.org, szager@chromium.org
BUG=261743
Review URL: https://codereview.chromium.org/225433003
git-svn-id: svn://svn.chromium.org/chrome/trunk/tools/depot_tools@263164 0039d316-1c4b-4281-b951-d872f2087c98
diff --git a/docs/src/.gitignore b/docs/src/.gitignore
index b207b71..61d00c7 100644
--- a/docs/src/.gitignore
+++ b/docs/src/.gitignore
@@ -1,3 +1,5 @@
git
asciidoc
-__*.txt
\ No newline at end of file
+demo_repo
+ansi2html
+__*.txt
diff --git a/docs/src/_footer.txt b/docs/src/_footer.txt
index 1f7bdd4..b3c5d04 100644
--- a/docs/src/_footer.txt
+++ b/docs/src/_footer.txt
@@ -1,7 +1,7 @@
CHROMIUM DEPOT_TOOLS
--------------------
-Part of the chromium linkgit:depot_tools[1] suite. These tools are meant to
+Part of the chromium linkgit:depot_tools[7] suite. These tools are meant to
assist with the development of chromium and related projects. Download the tools
from link:{sys3:git config remote.origin.url}[here].
diff --git a/docs/src/_helper_prefix.txt b/docs/src/_helper_prefix.txt
new file mode 100644
index 0000000..55de7e7
--- /dev/null
+++ b/docs/src/_helper_prefix.txt
@@ -0,0 +1 @@
+A tutorial for these tools can be found at linkgit:depot_tools_tutorial[7].
diff --git a/docs/src/common_demo_functions.sh b/docs/src/common_demo_functions.sh
new file mode 100755
index 0000000..f2f54c8
--- /dev/null
+++ b/docs/src/common_demo_functions.sh
@@ -0,0 +1,79 @@
+#!/bin/bash
+
+REMOTE=$(pwd)/demo_repo
+
+unset GIT_DIR
+
+# Helper functions
+set_user() {
+ export GIT_AUTHOR_EMAIL="$1@chromium.org"
+ export GIT_AUTHOR_NAME="$1"
+ export GIT_COMMITTER_EMAIL="$1@chromium.org"
+ export GIT_COMMITTER_NAME="$1"
+}
+set_user 'local'
+
+
+# increment time by X seconds
+TIME=1397119976
+tick() {
+ TIME=$[$TIME + $1]
+ export GIT_COMMITTER_DATE="$TIME +0000"
+ export GIT_AUTHOR_DATE="$TIME +0000"
+}
+tick 0
+
+# a commit
+c() {
+ silent git commit --allow-empty -m "$1"
+ tick 10
+}
+
+praw() {
+ echo -e "\x1B[37;1m$ $@\x1B[m"
+}
+
+# print a visible command (but don't run it)
+pcommand() {
+ praw "$(python -c '\
+ import sys, pipes; \
+ print " ".join(map(pipes.quote, sys.argv[1:]))' "$@")"
+}
+
+# run a visible command
+run() {
+ pcommand "$@"
+ "$@"
+}
+
+comment() {
+ echo "# $@"
+}
+
+# run a silent command
+silent() {
+ if [[ $DEBUG ]]
+ then
+ "$@"
+ else
+ "$@" > /dev/null 2> /dev/null
+ fi
+}
+
+# add a file with optionally content
+add() {
+ local CONTENT=$2
+ if [[ ! $CONTENT ]]
+ then
+ CONTENT=$(python -c 'import random, string; \
+ print "".join(random.sample(string.lowercase, 16))')
+ fi
+ echo "$CONTENT" > $1
+ silent git add $1
+}
+
+# Add a special callout marker at the given line offset to indicate to
+# filter_demo_output.py to add a callout at that offset.
+callout() {
+ echo -e "\x1b[${1}c"
+}
diff --git a/docs/src/demo_repo.sh b/docs/src/demo_repo.sh
new file mode 100755
index 0000000..a07a47e
--- /dev/null
+++ b/docs/src/demo_repo.sh
@@ -0,0 +1,43 @@
+#!/bin/bash
+
+. common_demo_functions.sh
+
+TDIR=$(mktemp --tmpdir -d demo_repo.XXXXXXXXXX)
+trap "rm -rf $TDIR" EXIT
+
+cd $TDIR
+silent git clone "$REMOTE" .
+silent git reset --hard stage_1
+silent git update-ref refs/remotes/origin/master stage_1
+silent git tag -d $(git tag -l 'stage_*')
+silent git checkout origin/master
+silent git branch -d master
+silent git config color.ui always
+
+if [[ ! "$BLANK_DEMO" ]]
+then
+ silent git new-branch cool_feature
+
+ c "Add widget"
+ c "Refactor spleen"
+ silent git tag spleen_tag
+
+ c "another improvement"
+
+ silent git new-branch --upstream_current subfeature
+ c "slick commenting action"
+ c "integrate with CoolService"
+
+ silent git checkout cool_feature
+ c "Respond to CL comments"
+
+ silent git new-branch fixit
+ c "Epic README update"
+ c "Add neat feature"
+
+ silent git new-branch --upstream_current frozen_branch
+ c "a deleted file"
+ c "modfile"
+ c "FREEZE.unindexed"
+fi
+
diff --git a/docs/src/depot_tools_tutorial.demo.tldr.sh b/docs/src/depot_tools_tutorial.demo.tldr.sh
new file mode 100755
index 0000000..27ff22e
--- /dev/null
+++ b/docs/src/depot_tools_tutorial.demo.tldr.sh
@@ -0,0 +1,155 @@
+#!/bin/bash
+BLANK_DEMO=1
+. demo_repo.sh
+
+trunc() {
+ echo ... truncated output ...
+}
+
+trunc_command() {
+ pcommand "$@"
+ trunc
+}
+
+WS=build/whitespace_file.txt
+add_ws() {
+ praw cat '>>' $WS '<<EOF'
+ echo -e "$1"
+ echo EOF
+ echo -e "$1" >> $WS
+}
+
+ed_ws() {
+ echo -ne "\x1B[37;1m$ echo -e "
+ echo -n "'$1'"
+ echo -e " | ed $WS\x1B[m"
+ echo -e "$1" | ed $WS
+}
+
+# needs an extra echo afterwards
+map() {
+ run git map
+ echo
+}
+
+ED1='/Banana\ns/Banana/Kuun\nwq'
+
+ADD1="
+\"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."
+
+ED2='/Kuun\ns/Kuun/Kun\nwq'
+
+ADD2="
+There was an poignant pause."
+
+ADD3="
+CHAPTER 3:
+Mr. Usagi felt that something wasn't right. Shortly after the Domo-Kun left he
+began feeling sick."
+
+trunc_command fetch chromium
+pcommand cd src
+
+comment "(only on linux)"
+trunc_command ./build/install-build-deps.sh
+
+comment "Pull in all dependencies for HEAD"
+trunc_command gclient sync
+
+comment "Let's fix something!"
+run git new-branch fix_typo
+ed_ws "$ED1"
+run git commit -am 'Fix terrible typo.'
+map
+run git status
+trunc_command git cl upload -r domo@chromium.org --send-mail
+
+comment "While we wait for feedback, let's do something else."
+run git new-branch chap2
+run git map-branches
+add_ws "$ADD1"
+run git status
+
+comment "Someone on the code review pointed out that our typo-fix has a typo :("
+comment "We're still working on 'chap2' but we really want to land"
+comment "'fix_typo', so let's switch over and fix it."
+run git freeze
+run git checkout fix_typo 2>&1
+ed_ws "$ED2"
+run git upstream-diff --wordwise
+run git commit -am 'Fix typo for good!'
+trunc_command git cl upload
+
+comment "Since we got lgtm, let the CQ land it."
+pcommand git cl set_commit
+map
+
+comment "Switch back to where we were using the nav* commands (for fun..."
+comment "git checkout would work here too)"
+run git map-branches
+run git nav-upstream 2>&1
+pcommand git nav-downstream
+git nav-downstream --pick 0 2>&1
+run git map-branches
+
+comment "Now we can pick up on chapter2 where we left off."
+run git thaw
+run git diff
+add_ws "$ADD2"
+run git diff
+run git commit -am 'Finish chapter 2'
+map
+trunc_command git cl upload -r domo@chromium.org --send-mail
+
+comment "We poke a committer until they lgtm :)"
+pcommand git cl set_commit
+
+comment "While that runs through the CQ, let's get started on chapter 3."
+comment "Since we know that chapter 3 depends on chapter 2, we'll track the"
+comment "current chapter2 branch."
+run git new-branch --upstream_current chap3
+add_ws "$ADD3"
+run git commit -am 'beginning of chapter 3'
+map
+
+comment "We haven't updated the code in a while, so let's do that now."
+pcommand git rebase-update
+echo Fetching origin
+git fetch origin 2>&1 | grep -v 'stage'
+silent git update-ref refs/remotes/origin/master stage_2
+silent git tag -d $(git tag -l 'stage_*')
+git rebase-update --no_fetch
+
+comment "Well look at that. The CQ landed our typo and chapter2 branches "
+comment "already and git rebase-update cleaned them up for us."
+trunc_command gclient sync
+map
+
+comment "Someone on IRC mentions that they actually landed a chapter 3 already!"
+comment "We should pull their changes before continuing. Brace for"
+comment "a code conflict!"
+pcommand git rebase-update
+echo Fetching origin
+git fetch origin 2>&1 | grep -v 'stage'
+silent git tag -d $(git tag -l 'stage_*')
+echo Rebasing: chap2
+silent git rebase-update
+echo ... lots of output, it\'s a conflict alright :\(...
+run git diff
+
+comment "Oh, well, that's not too bad. In fact... that's a terrible chapter 3!"
+praw \$EDITOR "$WS"
+echo "... /me deletes bad chapter 3 ..."
+silent git checkout --theirs -- "$WS"
+run git add "$WS"
+run git diff --cached
+
+comment "Much better"
+run git rebase --continue
+run git rebase-update
+silent git tag -d $(git tag -l 'stage_*')
+trunc_command gclient sync
+map
+trunc_command git cl upload
diff --git a/docs/src/depot_tools_tutorial.txt b/docs/src/depot_tools_tutorial.txt
new file mode 100644
index 0000000..5d08da4
--- /dev/null
+++ b/docs/src/depot_tools_tutorial.txt
@@ -0,0 +1,408 @@
+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
+Chromium using these tools. This will cover:
+
+* <<_setting_up,Setting up>>
+* <<_getting_the_code,Getting the code>>
+* <<_tl_dr_walkthrough,TL;DR Walkthrough>>
+* <<_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 assumes basic familiarity with git terminology and concepts. If you
+need to brush up on these, the following are very good resources:
+
+* link:http://think-like-a-git.net/[Think like (a) Git] - A lighthearted
+ overview of git. If you're sorta-familiar with git, but not 'comfortable' with
+ it, then give this a look.
+* 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.
+* link:http://git-scm.com/book[Pro Git book] - ``The'' book for learning git
+ from basics to advanced concepts. A bit dry, but very through.
+
+If you've tried these out and are still having some trouble getting started,
+there are 'many' other resources online which should help. If you're 'really'
+**'really'** stuck, then chat up one of the Chromium infrastructure team
+members for some pointers.
+
+Litmus Test::
+ If you know what `git add`, `git status`, `git commit` do and you know
+ 'essentially' what `git rebase` does, then you should know enough to follow
+ along.
+
+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
+[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.
+
+
+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
+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 its upstream (`origin/master`),
+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
+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
+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
+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
+rebase-update` 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 `git branch
+-D <branch>`, 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 `git rebase-update`, 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 about your branch being fully committed, you can use
+linkgit:git-reflog[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.
+
+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]. Unlike `git branch -m <old>
+<new>`, this tool will correctly preserve the upstream relationships of your
+branch compared to its downstreams.
+
+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 'independent' CLs, 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 an extra argument. First, `git checkout` the branch
+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 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
+linkgit:git-reparent-branch[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.
+
+
+CONCLUSION
+----------
+Hopefully that gives you a good starting overview on Chromium development using
+'depot_tools'. If you 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 feel free to 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:
diff --git a/docs/src/filter_demo_output.py b/docs/src/filter_demo_output.py
new file mode 100755
index 0000000..5f0fd3e
--- /dev/null
+++ b/docs/src/filter_demo_output.py
@@ -0,0 +1,137 @@
+#!/usr/bin/env python
+# Copyright 2014 The Chromium Authors. All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
+
+import collections
+import os
+import re
+import sys
+
+from xml.sax.saxutils import escape
+
+from cStringIO import StringIO
+
+if not os.path.exists('ansi2html'):
+ print 'You must run ./make_docs.sh once before running this script.'
+ sys.exit(1)
+
+# This dependency is pulled in by make_docs.sh
+# if it doesn't exist, run ./make_docs.sh first
+sys.path.insert(0, 'ansi2html')
+
+import ansi2html # pylint: disable=F0401, W0611
+import ansi2html.converter # pylint: disable=F0401, W0611
+
+def simpleXML(string):
+ BRIGHT = 1
+ DIM = 2
+ NORMAL = 22
+ RESET = 0
+ ESC_RE = re.compile('(\x1B\\[[^m]*?)m')
+
+ ret = StringIO()
+ boldstate = False
+
+ for tok in ESC_RE.split(string):
+ if not tok:
+ continue
+ if tok[0] == '\x1b':
+ codes = map(int, filter(bool, tok[2:].split(';')))
+ if not codes:
+ codes = [RESET]
+ for code in codes:
+ # only care about Bright
+ if code == BRIGHT and boldstate is False:
+ boldstate = True
+ ret.write('<emphasis role="strong">')
+ elif code in (DIM, NORMAL, RESET) and boldstate:
+ boldstate = False
+ ret.write('</emphasis>')
+ else:
+ ret.write(escape(tok))
+
+ if boldstate:
+ ret.write('</emphasis>')
+
+ return ret.getvalue()
+
+
+def main():
+ ansi2html.converter.SCHEME['custom'] = (
+ "#000000", "#e42e16", "#19c518", "#e7e71c", "#492ee1",
+ "#d338d3", "#33d6e5", "#ffffff",
+ )
+
+ backend = sys.argv[1]
+ output = sys.stdin.read().rstrip()
+
+ callout_re = re.compile('\x1b\[(\d+)c\n')
+ callouts = collections.defaultdict(int)
+ for i, line in enumerate(output.splitlines(True)):
+ m = callout_re.match(line)
+ if m:
+ callouts[i + int(m.group(1)) - len(callouts)] += 1
+
+ output = callout_re.sub('', output)
+
+ w = sys.stdout.write
+
+ callout_counter = 1
+ if backend == 'xhtml11':
+ preamble = (
+ '</p></div><div class="listingblock"><div class="content"><pre><code>'
+ )
+ postamble = '</code></pre></div></div><p><div class="paragraph">'
+ c = ansi2html.Ansi2HTMLConverter(inline=True, scheme='custom')
+
+ in_code = False
+ body = c.convert(output, full=False)
+ for i, line in enumerate(body.splitlines()):
+ if line.startswith('# '):
+ if in_code:
+ w(postamble)
+ in_code = False
+ w(line[1:])
+ else:
+ if not in_code:
+ w(preamble)
+ in_code = True
+ ext = ''
+ for _ in xrange(callouts[i]):
+ if not ext:
+ ext += '</span>'
+ ext += ' <b><%d></b>' % callout_counter
+ callout_counter += 1
+ if ext:
+ ext += '<span>'
+ w(line + ext + '\n')
+ if in_code:
+ w(postamble)
+ else:
+ preamble = '</simpara><literallayout class="monospaced">'
+ postamble = '</literallayout><simpara>'
+
+ in_code = False
+ body = simpleXML(output)
+ for i, line in enumerate(body.splitlines()):
+ if line.startswith('# '):
+ if in_code:
+ w(postamble)
+ in_code = False
+ w(line[1:])
+ else:
+ if not in_code:
+ w(preamble)
+ in_code = True
+ ext = ''
+ for _ in xrange(callouts[i]):
+ ext += ' <emphasis role="strong">(%d)</emphasis>' % callout_counter
+ callout_counter += 1
+ w(line + ext + '\n')
+ if in_code:
+ w(postamble)
+
+
+if __name__ == '__main__':
+ main()
diff --git a/docs/src/git-freeze.demo.1.sh b/docs/src/git-freeze.demo.1.sh
new file mode 100755
index 0000000..13db046
--- /dev/null
+++ b/docs/src/git-freeze.demo.1.sh
@@ -0,0 +1,23 @@
+#!/bin/sh
+. demo_repo.sh
+
+add deleted_file
+add unstaged_deleted_file
+add modified_file
+c "demo changes"
+
+add added_file_with_unstaged_changes
+echo bob >> added_file_with_unstaged_changes
+
+add added_file
+echo bob >> modified_file
+silent git rm deleted_file
+rm unstaged_deleted_file
+touch unadded_file
+
+run git status --short
+run git freeze
+run git status --short
+run git log -n 2 --stat
+run git thaw
+run git status --short
diff --git a/docs/src/git-freeze.txt b/docs/src/git-freeze.txt
index 1e2e253..4a53832 100644
--- a/docs/src/git-freeze.txt
+++ b/docs/src/git-freeze.txt
@@ -28,50 +28,7 @@
EXAMPLE
-------
-
-[subs="specialcharacters,quotes,attributes"]
-----
-[white]**$ git status --short**
-[green]##A## added_file
-[green]##A##{zwsp}[red]##M## added_file_with_unstaged_changes
-[green]##D## deleted_file
- [red]##M## modified_file
- [red]##D## unstaged_deleted_file
-[red]##??## unadded_file
-[white]**$ git freeze**
-[white]**$ git status --short**
-[white]**$ git log -n 2 --stat**
-[yellow]##commit 182eccae8e385acba21c9ff2713e98ff4b7e17cd##
-Author: Robert Iannucci <iannucci@chromium.org>
-Date: Thu Mar 13 17:42:37 2014 -0700
-
- FREEZE.unindexed
-
- added_file_with_unstaged_changes | 3 [green]##\+\+##{zwsp}[red]##-##
- modified_file | 4 [green]##\+\+\+##{zwsp}[red]##-##
- unadded_file | 3 [green]##\+\+\+##
- unstaged_deleted_file | 1 [red]##-##
- 4 files changed, 8 insertions(\+), 3 deletions(-)
-
-[yellow]##commit ce07bdc49a61f54e6142b4bba5cc517cf6802bd4##
-Author: Robert Iannucci <iannucci@chromium.org>
-Date: Thu Mar 13 17:42:37 2014 -0700
-
- FREEZE.indexed
-
- added_file | 3 [green]##\+\+\+##
- added_file_with_unstaged_changes | 1 [green]##\+##
- deleted_file | 1 [red]##-##
- 3 files changed, 4 insertions(+), 1 deletion(-)
-[white]**$ git thaw**
-[white]**$ git status --short**
-[green]##A## added_file
-[green]##A##{zwsp}[red]##M## added_file_with_unstaged_changes
-[green]##D## deleted_file
- [red]##M## modified_file
- [red]##D## unstaged_deleted_file
-[red]##??## unadded_file
-----
+demo:1[]
SEE ALSO
--------
diff --git a/docs/src/git-map-branches.demo.1.sh b/docs/src/git-map-branches.demo.1.sh
new file mode 100755
index 0000000..7afc5ff
--- /dev/null
+++ b/docs/src/git-map-branches.demo.1.sh
@@ -0,0 +1,7 @@
+#!/bin/sh
+. demo_repo.sh
+
+silent git branch no_upstream HEAD~
+
+run git map-branches
+
diff --git a/docs/src/git-map-branches.txt b/docs/src/git-map-branches.txt
index e5d53de..a925e9c 100644
--- a/docs/src/git-map-branches.txt
+++ b/docs/src/git-map-branches.txt
@@ -35,18 +35,7 @@
assuming that the `frozen_changes` branch was currently checked out, running
'git map-branches' would result in an output like:
-[subs="quotes"]
-----
-[white]**$ git map-branches**
-[red]#origin/master#
- [green]#cool_feature#
- [green]#subfeature#
- [aqua]#frozen_changes *#
- [green]#master#
-[fuchsia]#{NO UPSTREAM}#
- [green]#bogus_noparent#
- [aqua]#duplicate_cool_feature_no_upstream#
-----
+demo:1[]
include::_aliases.txt[]
@@ -61,4 +50,4 @@
include::_footer.txt[]
-// vim: ft=asciidoc:
\ No newline at end of file
+// vim: ft=asciidoc:
diff --git a/docs/src/git-map.demo.1.sh b/docs/src/git-map.demo.1.sh
new file mode 100755
index 0000000..bc3106a
--- /dev/null
+++ b/docs/src/git-map.demo.1.sh
@@ -0,0 +1,3 @@
+#!/bin/sh
+. demo_repo.sh
+run git map
diff --git a/docs/src/git-map.txt b/docs/src/git-map.txt
index a5b498b..bce7e61 100644
--- a/docs/src/git-map.txt
+++ b/docs/src/git-map.txt
@@ -51,26 +51,7 @@
-------
Running 'git map' would result in an output something like:
-
-[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)**
-----
+demo:1[]
As you can see, the structure of the commit history is visible, particularly
what the parents of each commit are. In order to see the 'upstream'
@@ -83,4 +64,4 @@
include::_footer.txt[]
-// vim: ft=asciidoc:
\ No newline at end of file
+// vim: ft=asciidoc:
diff --git a/docs/src/git-nav-downstream.demo.1.sh b/docs/src/git-nav-downstream.demo.1.sh
new file mode 100755
index 0000000..ba22243
--- /dev/null
+++ b/docs/src/git-nav-downstream.demo.1.sh
@@ -0,0 +1,12 @@
+#!/bin/sh
+. demo_repo.sh
+
+silent git checkout origin/master
+
+run git map-branches
+pcommand git nav-downstream
+git nav-downstream --pick 0 2>&1
+run git map-branches
+run git nav-downstream 2>&1
+run git map-branches
+
diff --git a/docs/src/git-nav-downstream.txt b/docs/src/git-nav-downstream.txt
index 9a41e0c..725017e 100644
--- a/docs/src/git-nav-downstream.txt
+++ b/docs/src/git-nav-downstream.txt
@@ -21,33 +21,7 @@
EXAMPLE
-------
-
-[subs="quotes,attributes"]
-----
-[white]**$ git map-branches**
-[red]**origin/master *{zwsp}**
- [green]#cool_feature#
- [green]#subfeature#
- [green]#frozen_changes#
- [green]#master#
-[fuchsia]#{NO UPSTREAM}#
- [green]#bogus_noparent#
-[white]**$ git nav-downstream**
-
-Please select a downstream branch
- 0. cool_feature
- 1. frozen_changes
- 2. master
-Selection (0-2)[0]: 0
-[white]**$ git map-branches**
-[red]##origin/master##
- [aqua]**cool_feature *{zwsp}**
- [green]#subfeature#
- [green]#frozen_changes#
- [green]#master#
-[fuchsia]#{NO UPSTREAM}#
- [green]#bogus_noparent#
-----
+demo:1[]
include::_aliases.txt[]
diff --git a/docs/src/git-nav-upstream.demo.1.sh b/docs/src/git-nav-upstream.demo.1.sh
new file mode 100755
index 0000000..9869106
--- /dev/null
+++ b/docs/src/git-nav-upstream.demo.1.sh
@@ -0,0 +1,12 @@
+#!/bin/sh
+. demo_repo.sh
+
+silent git checkout subfeature
+
+run git map-branches
+run git nav-upstream 2>&1
+run git map-branches
+callout 3
+run git nav-upstream 2>&1
+run git map-branches
+
diff --git a/docs/src/git-nav-upstream.txt b/docs/src/git-nav-upstream.txt
index c6010a9..5213bc1 100644
--- a/docs/src/git-nav-upstream.txt
+++ b/docs/src/git-nav-upstream.txt
@@ -19,27 +19,9 @@
EXAMPLE
-------
-
-[subs="quotes,attributes"]
-----
-[white]**$ git map-branches**
-[red]##origin/master##
- [green]#cool_feature#
- [aqua]**subfeature *{zwsp}**
- [green]#frozen_changes#
- [green]#master#
-[fuchsia]#{NO UPSTREAM}#
- [green]#bogus_noparent#
-[white]**$ git nav-upstream**
-[white]**$ git map-branches**
-[red]##origin/master##
- [aqua]**cool_feature *{zwsp}**
- [green]#subfeature#
- [green]#frozen_changes#
- [green]#master#
-[fuchsia]#{NO UPSTREAM}#
- [green]#bogus_noparent#
-----
+demo:1[]
+1. Note that being in a 'detached HEAD' state is OK. You'll just want to create
+a linkgit:git-new-branch[1] from here.
include::_aliases.txt[]
diff --git a/docs/src/git-new-branch.demo.1.sh b/docs/src/git-new-branch.demo.1.sh
new file mode 100755
index 0000000..5b5ac49
--- /dev/null
+++ b/docs/src/git-new-branch.demo.1.sh
@@ -0,0 +1,12 @@
+#!/bin/sh
+. demo_repo.sh
+
+run git map-branches
+run git new-branch independent_cl
+run git map-branches
+run git new-branch --upstream subfeature nested_cl
+callout 3
+run git map-branches
+run git checkout cool_feature
+run git new-branch --upstream_current cl_depends_on_cool_feature
+run git map-branches
diff --git a/docs/src/git-new-branch.txt b/docs/src/git-new-branch.txt
index b8cc285..a9f104f 100644
--- a/docs/src/git-new-branch.txt
+++ b/docs/src/git-new-branch.txt
@@ -56,42 +56,10 @@
EXAMPLE
-------
+demo:1[]
-[subs="specialcharacters,quotes,attributes,callouts"]
-----
-[white]**$ git map-branches**
-[red]#origin/master#
- [green]#cool_feature#
- [green]#subfeature#
- [aqua]#frozen_changes *#
-[white]**$ git new-branch independent_cl**
-[white]**$ git map-branches**
-[red]#origin/master#
- [green]#cool_feature#
- [green]#subfeature#
- [green]#frozen_changes#
- [aqua]#independent_cl *#
-[white]**$ git new-branch --upstream subfeature nested_cl**
-[white]**$ git map-branches**
-[red]#origin/master#
- [green]#cool_feature#
- [aqua]#subfeature# <1>
- [aqua]#nested_cl *#
- [green]#frozen_changes#
- [green]#independent_cl#
-[white]**$ git checkout cool_feature**
-[white]**$ git new-branch --upstream_current cl_depends_on_cool_feature**
-[white]**$ git map-branches**
-[red]#origin/master#
- [aqua]#cool_feature#
- [aqua]#cl_depends_on_cool_feature *#
- [green]#subfeature#
- [green]#nested_cl#
- [green]#frozen_changes#
- [green]#independent_cl#
-----
-<1> Note that both branches are cyan because they are currently the same
-'commit' object. See linkgit::git-map-branches[1] for more detail.
+1. Note that both branches are cyan because they are currently the same
+'commit' object. See linkgit:git-map-branches[1] for more detail.
include::_aliases.txt[]
diff --git a/docs/src/git-squash-branch.demo.1.sh b/docs/src/git-squash-branch.demo.1.sh
new file mode 100755
index 0000000..8d83a03
--- /dev/null
+++ b/docs/src/git-squash-branch.demo.1.sh
@@ -0,0 +1,12 @@
+#!/bin/sh
+. demo_repo.sh
+
+run git map
+echo
+
+# since these are all empty commits, pretend there's something there
+pcommand git squash-branch -m "cool squash demo"
+git squash-branch -m "cool squash demo" > /dev/null 2> /dev/null
+c "cool squash demo"
+
+run git map
diff --git a/docs/src/git-squash-branch.txt b/docs/src/git-squash-branch.txt
index 1401a02..fe7850c 100644
--- a/docs/src/git-squash-branch.txt
+++ b/docs/src/git-squash-branch.txt
@@ -39,41 +39,8 @@
EXAMPLE
-------
+demo:1[]
-[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)**
-[white]**$ git squash-branch "cool squash demo"**
-[white]**$ git map**
-[white blue-background]##*##{zwsp}[blue-background red]** 2c81508 ** [green]##(##{zwsp}[aqua]**frozen_changes**{zwsp}[green]##)## [yellow]##2014-03-22## \~ cool squash demo
-* [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)**
-----
include::_aliases.txt[]
diff --git a/docs/src/make_docs.sh b/docs/src/make_docs.sh
index ac8ab42..2a59b5d 100755
--- a/docs/src/make_docs.sh
+++ b/docs/src/make_docs.sh
@@ -41,7 +41,25 @@
fi
echo Asciidoc up to date at $ASCIIDOC_HASH \($BRANCH\)
-export PATH=`pwd`/asciidoc:$PATH
+# We pull ansi2hash to convert demo script output
+BRANCH=1.0.6
+ANSI2HTML_HASH=6282ab7a24a5a7eab2e0b23bb0055234c533a6e9
+if [[ ! -d ansi2html || $(git -C ansi2html rev-parse HEAD) != $ANSI2HTML_HASH ]]
+then
+ echo Cloning ansi2html
+ rm -rf ansi2html
+ git clone --single-branch --branch $BRANCH --depth 1 \
+ https://github.com/ralphbean/ansi2html.git 2> /dev/null
+ curl https://bitbucket.org/gutworth/six/raw/a875ac34c777fe801569c6c5299bf1a35aa578cd/six.py > \
+ ansi2html/ansi2html/six.py
+ ed ansi2html/ansi2html/converter.py <<EOF
+/version_str
+s/pkg.*$/'cool version bro'
+wq
+EOF
+fi
+
+echo ansi2html up to date at $ANSI2HTML_HASH \($BRANCH\)
# We pull git to get its documentation toolchain
BRANCH=v1.9.0
@@ -105,9 +123,23 @@
wq
EOF
+ cat >> git/Documentation/asciidoc.conf <<EOF
+
+[macros]
+(?su)[\\\\]?(?P<name>demo):(?P<target>\S*?)\[\]=
+
+[demo-inlinemacro]
+{sys3:cd $(pwd); ./{docname}.demo.{target}.sh | python filter_demo_output.py {backend} }
+EOF
+
fi
echo Git up to date at $GITHASH \($BRANCH\)
+if [[ ! -d demo_repo ]]
+then
+ ./prep_demo_repo.sh
+fi
+
# build directory files for 'essential' and 'helper' sections of the depot_tools
# manpage.
for category in helper essential
@@ -130,6 +162,7 @@
echo -n -
done
echo
+ cat _${category}_prefix.txt 2> /dev/null || true
echo
fi
@@ -145,9 +178,10 @@
} > __${category}.txt
done
-JOBS=0
+JOBS=1
HTML_TARGETS=()
-MAN_TARGETS=()
+MAN1_TARGETS=()
+MAN7_TARGETS=()
for x in *.txt *.css
do
TO="git/Documentation/$x"
@@ -155,22 +189,30 @@
then
echo \'$x\' differs
cp $x "$TO"
- fi
- # Exclude files beginning with _ from the target list. This is useful to have
- # includable snippet files.
- if [[ ${x:0:1} != _ && ${x:(-4)} == .txt ]]
- then
- HTML_TARGETS+=("${x%%.txt}.html")
- if [[ ${x:0:3} == git ]]
+ # Exclude files beginning with _ from the target list. This is useful to
+ # have includable snippet files.
+ if [[ ${x:0:1} != _ && ${x:(-4)} == .txt ]]
then
- MAN1_TARGETS+=("${x%%.txt}.1")
- else
- MAN7_TARGETS+=("${x%%.txt}.7")
+ HTML_TARGETS+=("${x%%.txt}.html")
+ if [[ ! "$NOMAN" ]]
+ then
+ if [[ ${x:0:3} == git ]]
+ then
+ MAN1_TARGETS+=("${x%%.txt}.1")
+ else
+ MAN7_TARGETS+=("${x%%.txt}.7")
+ fi
+ fi
+ JOBS=$[$JOBS + 2]
fi
- JOBS=$[$JOBS + 2]
fi
done
+if [[ ${#HTML_TARGETS} == 0 && ${#MAN1_TARGETS} == 0 && ${#MAN7_TARGETS} == 0 ]]
+then
+ exit
+fi
+
VER="v$(git rev-parse --short HEAD)"
if [[ ! -f git/version ]] || ! cmp --silent git/version <(echo "$VER")
then
@@ -203,4 +245,4 @@
do
echo Copying ../man7/$x
cp "git/Documentation/$x" ../man7
-done
\ No newline at end of file
+done
diff --git a/docs/src/prep_demo_repo.sh b/docs/src/prep_demo_repo.sh
new file mode 100755
index 0000000..241097c
--- /dev/null
+++ b/docs/src/prep_demo_repo.sh
@@ -0,0 +1,103 @@
+#!/bin/bash
+
+NO_AUTOPREP=True
+. common_demo_functions.sh
+
+rm -rf $REMOTE
+mkdir -p $REMOTE
+cd $REMOTE
+
+set_user "remote"
+
+silent git init
+
+WS=build/whitespace_file.txt
+
+mkdir build
+cat > "$WS" <<EOF
+Copyright 2014 The Chromium Authors. All rights reserved.
+Use of this useless file is governed by a BSD-style license that can be
+found in the LICENSE file.
+
+
+This file is used for making non-code changes to trigger buildbot cycles. Make
+any modification below this line.
+
+=====================================================================
+
+Let's make a story. Add one sentence for every commit:
+
+CHÄPTER 1:
+It was a dark and blinky night; the rain fell in torrents -- except at
+occasional intervals, when it was checked by a violent gust of wind which
+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-Banana.
+
+"What took you so long?", inquired his wife.
+
+Silence. Oblivious to his silence, she continued, "Did Mr. Usagi enjoy the
+waffles you brought him?" "You know him, he's not one to forego a waffle,
+no matter how burnt," he snickered.
+
+The pause was filled with the sound of compile errors.
+
+CHAPTER 2:
+The jelly was as dark as night, and just as runny.
+The Domo-Kun shuddered, remembering the way Mr. Usagi had speared his waffles
+with his fork, watching the runny jelly spread and pool across his plate,
+like the blood of a dying fawn. \"It reminds me of that time --\" he started, as
+his wife cut in quickly: \"-- please. I can't bear to hear it.\". A flury of
+images coming from the past flowed through his mind.
+EOF
+git add "$WS"
+
+c "Always output seccomp error messages to stderr"
+c "ozone: evdev: Filter devices by path"
+c "ContentView->ContentViewCore in ContentViewRenderView"
+c "linux_aura: Use system configuration for middle clicking the titlebar."
+c "[fsp] Add requestUnmount() method together with the request manager."
+c "don't use glibc-specific execinfo.h on uclibc builds"
+c "Make ReflectorImpl use mailboxes"
+
+git tag stage_1
+
+c "Change the Pica load benchmark to listen for the polymer-ready event"
+c "Remove AMD family check for the flapper crypto accelerator."
+c "Temporarily CHECK(trial) in ChromeRenderProcessObserver::OnSetFieldTrialGroup."
+
+echo -e '/Banana\ns/Banana/Kun\nwq' | silent ed "$WS"
+git add "$WS"
+set_user 'local'
+c "Fix terrible typo."
+
+set_user 'remote'
+c "Revert 255617, due to it not tracking use of the link doctor page properly."
+
+cat >> "$WS" <<EOF
+
+"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.
+
+There was an poignant pause.
+EOF
+git add "$WS"
+set_user 'local'
+c 'Finish chapter 2'
+
+git tag stage_2
+
+cat >> "$WS" <<EOF
+
+CHAPTER 3:
+Hilariousness! This chapter is awesome!
+EOF
+git add "$WS"
+set_user 'remote'
+c "Add best chapter2 ever!"
+
+c "Ensure FS is exited for all not-in-same-page navigations."
+c "Refactor data interchange format."