Add git_docs folder to depot_tools.

Includes trial documentation for git-freeze and git-thaw, as well as a
make_docs.sh script which generates man and html documentation from the input
asciidoc files, using git 1.9's documentation toolchain.

R=szager@chromium.org, agable@chromium.org
BUG=261738

Review URL: https://codereview.chromium.org/196133007

git-svn-id: svn://svn.chromium.org/chrome/trunk/tools/depot_tools@257214 0039d316-1c4b-4281-b951-d872f2087c98

git_docs/.gitignore

+git
\ No newline at end of file

git_docs/_footer.txt

+CHROMIUM DEPOT_TOOLS
+--------------------
+Part of the chromium depot_tools 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].

git_docs/git-freeze.txt

+git-freeze(1)
+=============
+
+NAME
+----
+git-freeze - Freeze all changes on a branch (indexed and unindexed)
+
+SYNOPSIS
+--------
+[verse]
+'git freeze'
+
+DESCRIPTION
+-----------
+
+`git freeze` works a lot like `git stash`, in that it stores the current changes
+in your working copy and index 'somewhere'. Unlike `git stash`, `git freeze`
+stores those changes on your current branch. This effectively allows you to
+'pause' development of a branch, work on something else, and then come back to
+exactly the same working state later (by running `git thaw`).
+
+`git freeze` will make up to 2 commits on your branch. A commit with the message
+`FREEZE.indexed` will contain all changes which you’ve added to your index (like
+with 'git add', 'git mv', 'git rm', etc.). A commit with the message
+`FREEZE.unindexed` will contain all changes which were not in your index at the
+time you ran git freeze (freshly modified files, new files, etc.).
+
+SEE ALSO
+--------
+linkgit:git-thaw[1]
+
+include::_footer.txt[]

git_docs/git-thaw.txt

+git-thaw(1)
+=============
+
+NAME
+----
+git-thaw - Un-freeze all changes on a frozen branch.
+
+SYNOPSIS
+--------
+[verse]
+'git thaw'
+
+DESCRIPTION
+-----------
+
+`git thaw` takes a frozen branch (as made by linkgit:git-freeze[1]), and returns
+it to the status that it was in before it was frozen.
+
+If you freeze a branch multiple times (i.e. change files, freeze, change files,
+freeze), `git thaw` will thaw all of the freezes.
+
+SEE ALSO
+--------
+linkgit:git-freeze[1]
+
+include::_footer.txt[]

git_docs/make_docs.sh

+#!/bin/bash -e
+shopt -s nullglob
+
+cd $(dirname "$0")
+
+# Script which takes all the asciidoc git-*.txt files in this directory, renders
+# them to html + manpage format using git 1.9's doc toolchain, then puts
+# them in depot_tools to be committed.
+
+ensure_in_path() {
+  local CMD=$1
+  local PTH=$(which "$CMD")
+  if [[ ! $PTH ]]
+  then
+    echo Must have "$CMD" on your PATH!
+    exit 1
+  else
+    echo Using \'$PTH\' for ${CMD}.
+  fi
+}
+
+ensure_in_path xmlto
+ensure_in_path asciidoc
+
+DFLT_CATALOG_PATH="/usr/local/etc/xml/catalog"
+if [[ ! $XML_CATALOG_FILES && -f "$DFLT_CATALOG_PATH" ]]
+then
+  # Default if you install doctools with homebrew on mac
+  export XML_CATALOG_FILES="$DFLT_CATALOG_PATH"
+  echo Using \'$DFLT_CATALOG_PATH\' for \$XML_CATALOG_FILES.
+fi
+
+# We pull git to get its documentation toolchain
+BRANCH=v1.9.0
+GITHASH=5f95c9f850b19b368c43ae399cc831b17a26a5ac
+if [[ ! -d git || $(git -C git rev-parse HEAD) != $GITHASH ]]
+then
+  echo Cloning git
+  rm -rf git
+  git clone --single-branch --branch $BRANCH --depth 1 \
+    https://kernel.googlesource.com/pub/scm/git/git.git  2> /dev/null
+
+  # Replace the 'source' and 'package' strings.
+  ed git/Documentation/asciidoc.conf <<EOF
+  H
+  81
+  s/Git/depot_tools
+  +2
+  s/Git Manual/Chromium depot_tools Manual
+  wq
+EOF
+fi
+echo Git up to date at $GITHASH \($BRANCH\)
+
+HTML_TARGETS=()
+MAN_TARGETS=()
+for x in *.txt
+do
+  TO="git/Documentation/$x"
+  if [[ ! -f "$TO" ]] || ! cmp --silent "$x" "$TO"
+  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} != _ ]]
+  then
+    HTML_TARGETS+=("${x%%.txt}.html")
+    MAN_TARGETS+=("${x%%.txt}.1")
+  fi
+done
+
+VER="v$(git rev-parse --short HEAD)"
+if [[ ! -f git/version ]] || ! cmp --silent git/version <(echo "$VER")
+then
+  echo Version changed, cleaning.
+  echo "$VER" > git/version
+  (cd git/Documentation && make clean)
+fi
+
+# This export is so that asciidoc sys snippets which invoke git run relative to
+# depot_tools instead of the git clone.
+(
+  export GIT_DIR="$(git rev-parse --git-dir)" &&
+  cd git/Documentation &&
+  make -j"$[${#MAN_TARGETS} + ${#HTML_TARGETS}]" "${MAN_TARGETS[@]}" "${HTML_TARGETS[@]}"
+)
+
+mkdir htmlout 2> /dev/null || true
+for x in "${HTML_TARGETS[@]}"
+do
+  echo Copying htmlout/$x
+  cp "git/Documentation/$x" htmlout
+done
+
+for x in "${MAN_TARGETS[@]}"
+do
+  echo Copying ../man1/$x
+  cp "git/Documentation/$x" ../man1
+done
\ No newline at end of file

man1/git-freeze.1

+'\" t
+.\"     Title: git-freeze
+.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\"      Date: 03/13/2014
+.\"    Manual: Chromium depot_tools Manual
+.\"    Source: depot_tools f48b2c2
+.\"  Language: English
+.\"
+.TH "GIT\-FREEZE" "1" "03/13/2014" "depot_tools f48b2c2" "Chromium depot_tools Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+git-freeze \- Freeze all changes on a branch (indexed and unindexed)
+.SH "SYNOPSIS"
+.sp
+.nf
+\fIgit freeze\fR
+.fi
+.sp
+.SH "DESCRIPTION"
+.sp
+git freeze works a lot like git stash, in that it stores the current changes in your working copy and index \fIsomewhere\fR\&. Unlike git stash, git freeze stores those changes on your current branch\&. This effectively allows you to \fIpause\fR development of a branch, work on something else, and then come back to exactly the same working state later (by running git thaw)\&.
+.sp
+git freeze will make up to 2 commits on your branch\&. A commit with the message FREEZE\&.indexed will contain all changes which you\(cqve added to your index (like with \fIgit add\fR, \fIgit mv\fR, \fIgit rm\fR, etc\&.)\&. A commit with the message FREEZE\&.unindexed will contain all changes which were not in your index at the time you ran git freeze (freshly modified files, new files, etc\&.)\&.
+.SH "SEE ALSO"
+.sp
+\fBgit-thaw\fR(1)
+.SH "CHROMIUM DEPOT_TOOLS"
+.sp
+Part of the chromium depot_tools suite\&. These tools are meant to assist with the development of chromium and related projects\&. Download the tools from \m[blue]\fBhere\fR\m[]\&\s-2\u[1]\d\s+2\&.
+.SH "NOTES"
+.IP " 1." 4
+here
+.RS 4
+\%https://chromium.googlesource.com/chromium/tools/depot_tools.git
+.RE

man1/git-thaw.1

+'\" t
+.\"     Title: git-thaw
+.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\"      Date: 03/13/2014
+.\"    Manual: Chromium depot_tools Manual
+.\"    Source: depot_tools f48b2c2
+.\"  Language: English
+.\"
+.TH "GIT\-THAW" "1" "03/13/2014" "depot_tools f48b2c2" "Chromium depot_tools Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+git-thaw \- Un\-freeze all changes on a frozen branch\&.
+.SH "SYNOPSIS"
+.sp
+.nf
+\fIgit thaw\fR
+.fi
+.sp
+.SH "DESCRIPTION"
+.sp
+git thaw takes a frozen branch (as made by \fBgit-freeze\fR(1)), and returns it to the status that it was in before it was frozen\&.
+.sp
+If you freeze a branch multiple times (i\&.e\&. change files, freeze, change files, freeze), git thaw will thaw all of the freezes\&.
+.SH "SEE ALSO"
+.sp
+\fBgit-freeze\fR(1)
+.SH "CHROMIUM DEPOT_TOOLS"
+.sp
+Part of the chromium depot_tools suite\&. These tools are meant to assist with the development of chromium and related projects\&. Download the tools from \m[blue]\fBhere\fR\m[]\&\s-2\u[1]\d\s+2\&.
+.SH "NOTES"
+.IP " 1." 4
+here
+.RS 4
+\%https://chromium.googlesource.com/chromium/tools/depot_tools.git
+.RE