Overhaul the README files a bit.

README.git-cl.md

Index: README.git-cl.md
diff --git a/README.git-cl.md b/README.git-cl.md
new file mode 100644
index 0000000000000000000000000000000000000000..54e59734fc8c450f9e7dd832a35b80a77f88052f
--- /dev/null
+++ b/README.git-cl.md
@@ -0,0 +1,99 @@
+# git-cl
+
+The git-cl README describes the git-cl command set. This document describes how
+code review and git work together in general, intended for people familiar with
+git but unfamiliar with the code review process supported by Rietveld and
+Gerrit.
+
+
+## Reitveld concepts and terms
+
+A Rietveld review is for discussion of a single change or patch. You upload a
+proposed change, the reviewer comments on your change, and then you can upload a
+revised version of your change. Rietveld stores the history of uploaded patches
+as well as the comments, and can compute diffs in between these patches. The
+history of a patch is very much like a small branch in git, but since Rietveld
+is VCS-agnostic the concepts don't map perfectly. The identifier for a single
+review+patches+comments in Rietveld is called an `issue`.
+
+Rietveld provides a basic uploader that understands git. This program is used by
+git-cl, and is included in the git-cl repo as upload.py.
+
+
+## Basic interaction with git
+
+The fundamental problem you encounter when you try to mix git and code review is
+that with git it's nice to commit code locally, while during a code review
+you're often requested to change something about your code. There are a few
+different ways you can handle this workflow with git:
+
+1. Rewriting a single commit. Say the origin commit is O, and you commit your
+   initial work in a commit A, making your history like O--A. After review
+   comments, you commit --amend, effectively erasing A and making a new commit
+   A', so history is now O--A'. (Equivalently, you can use git reset --soft or
+   git rebase -i.)
+2. Writing follow-up commits. Initial work is again in A, and after review
+   comments, you write a new commit B so your history looks like O--A--B. When
+   you upload the revised patch, you upload the diff of O..B, not A..B; you
+   always upload the full diff of what you're proposing to change.
+
+The Rietveld patch uploader just takes arguments to `git diff`, so either of the
+above workflows work fine.  If all you want to do is upload a patch, you can use
+the upload.py provided by Rietveld with arguments like this:
+
+    upload.py --server server.com <args to "git diff">
+
+The first time you upload, it creates a new issue; for follow-ups on the same
+issue, you need to provide the issue number:
+
+    upload.py --server server.com --issue 1234 <args to "git diff">
+
+
+## git-cl to the rescue
+
+git-cl simplifies the above in the following ways:
+
+1. `git cl config` puts a persistent --server setting in your .git/config.
+2. The first time you upload an issue, the issue number is associated with the
+   current *branch*.  If you upload again, it will upload on the same issue.
+   (Note that this association is tied to a branch, not a commit, which means
+   you need a separate branch per review.)
+3. If your branch is _tracking_ (in the `git checkout --track` sense) another
+   one (like origin/master), calls to `git cl upload` will diff against that
+   branch by default.  (You can still pass arguments to `git diff` on the
+   command line, if necessary.)
+
+In the common case, this means that calling simply `git cl upload` will always
+upload the correct diff to the correct place.
+
+
+## Patch series
+
+The above is all you need to know for working on a single patch.
+
+Things get much more complicated when you have a series of commits that you want
+to get reviewed. Say your history looks like O--A--B--C. If you want to upload
+that as a single review, everything works just as above.
+
+But what if you upload each of A, B, and C as separate reviews? What if you
+then need to change A?
+
+1. One option is rewriting history: write a new commit A', then use git rebase
+   -i to insert that diff in as O--A--A'--B--C as well as squash it. This is
+   sometimes not possible if B and C have touched some lines affected by A'.
+2. Another option, and the one espoused by software like topgit, is for you to
+   have separate branches for A, B, and C, and after writing A' you merge it
+   into each of those branches. (topgit automates this merging process.)  This
+   is also what is recommended by git-cl, which likes having different branch
+   identifiers to hang the issue number off of.  Your history ends up looking
+   like:
+
+       O---A---B---C
+            \   \   \
+             A'--B'--C'
+
+   Which is ugly, but it accurately tracks the real history of your work, can be
+   thrown away at the end by committing A+A' as a single `squash` commit.
+
+In practice, this comes up pretty rarely. Suggestions for better workflows are
+welcome.