Document how Gerrit uses Change-Id lines

Also deprecated the section in uploading changes describing how to
manually push new commits into existing changes.

Change-Id: I1c288c509a474017b9089e4cca9622911495564f
Signed-off-by: Shawn O. Pearce <sop@google.com>

5 files changed, 311 insertions, 57 deletions

diff --git a/Documentation/cmd-cherry-pick.txt b/Documentation/cmd-cherry-pick.txt
index ba7da0ed16..85599d476f 100644
--- a/Documentation/cmd-cherry-pick.txt
+++ b/Documentation/cmd-cherry-pick.txt
@@ -28,6 +28,11 @@ Change ids may be specified as either the change id (e.g. 1234)
 or as change id slash patch set number (e.g. 1234/8).  If the patch
 set number is not supplied, `/1` is assumed.
 
+The `\--close` command line option is now deprecated, as closing
+existing changes post cherry-pick is better handled simply by
+ensuring link:user-changeid.html[Change-Id lines] are present in
+each commit message.
+
 OBTAINING
 ---------
 To obtain the 'gerrit-cherry-pick' script use scp to copy it to
diff --git a/Documentation/cmd-hook-commit-msg.txt b/Documentation/cmd-hook-commit-msg.txt
index 5a7b2475af..1dfb08c3dc 100644
--- a/Documentation/cmd-hook-commit-msg.txt
+++ b/Documentation/cmd-hook-commit-msg.txt
@@ -11,25 +11,25 @@ DESCRIPTION
 A Git hook automatically invoked by `git commit`, and most other
 commit creation tools such as `git citool` or `git gui`.  The Gerrit
 Code Review supplied implementation of this hook is a short shell
-script which automatically inserts a globally unique `Change-Id`
-tag in the footer of a commit message.  When present, Gerrit uses
-this tag to track commits across cherry-picks and rebases.
+script which automatically inserts a globally unique Change-Id tag
+in the footer of a commit message.  When present, Gerrit uses this
+tag to track commits across cherry-picks and rebases.
 
 After the hook has been installed in the user's local Git repository
 for a project, the hook will modify a commit message such as:
 
-====
+----
   Improve foo widget by attaching a bar.
 
   We want a bar, because it improves the foo by providing more
   wizbangery to the dowhatimeanery.
 
   Signed-off-by: A. U. Thor <author@example.com>
-====
+----
 
 by inserting a new `Change-Id: ` line in the footer:
 
-====
+----
   Improve foo widget by attaching a bar.
 
   We want a bar, because it improves the foo by providing more
@@ -37,7 +37,7 @@ by inserting a new `Change-Id: ` line in the footer:
 
   Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
   Signed-off-by: A. U. Thor <author@example.com>
-====
+----
 
 The hook implementation is reasonably intelligent at inserting the
 Change-Id line before any Signed-off-by or Acked-by lines placed
@@ -58,6 +58,31 @@ local system:
 
   $ scp -P 29418 review.example.com:hooks/commit-msg .git/hooks
 
+SEE ALSO
+--------
+
+* link:user-changeid.html[Change-Id Lines]
+* link:http://www.kernel.org/pub/software/scm/git/docs/git-commit.html[git-commit(1)]
+* link:http://www.kernel.org/pub/software/scm/git/docs/githooks.html[githooks(5)]
+
+IMPLEMENTATION
+--------------
+
+The hook generates unique Change-Id lines by creating a virtual
+commit object within the local Git repository, and obtaining the
+SHA-1 hash from it.  Like any other Git commit, the following
+properties are included in the computation:
+
+* SHA-1 of the tree being committed
+* SHA-1 of the parent commit
+* Name, email address, timestamp of the author
+* Name, email address, timestamp of the committer
+* Proposed commit message (before Change-Id was inserted)
+
+Because the names of the tree and parent commit, as well as the
+committer timestamp are included in the hash computation, the output
+Change-Id is sufficiently unique.
+
 GERRIT
 ------
 Part of link:index.html[Gerrit Code Review]
diff --git a/Documentation/index.txt b/Documentation/index.txt
index 94c41040cc..bb94c7e5f8 100644
--- a/Documentation/index.txt
+++ b/Documentation/index.txt
@@ -7,6 +7,7 @@ User Guide
 * link:http://source.android.com/submit-patches/workflow[Default Workflow]
 * link:cmd-index.html[Command Line Tools]
 * link:user-upload.html[Uploading Changes]
+* link:user-changeid.html[Change-Id Lines]
 * link:user-signedoffby.html[Signed-off-by Lines]
 * link:access-control.html[Access Controls]
 
diff --git a/Documentation/user-changeid.txt b/Documentation/user-changeid.txt
new file mode 100644
index 0000000000..eda4ca4545
--- /dev/null
+++ b/Documentation/user-changeid.txt
@@ -0,0 +1,162 @@
+Gerrit2 - Change-Ids
+====================
+
+Description
+-----------
+
+Gerrit Code Review sometimes relies upon Change-Id lines in the
+bottom of a commit message to uniquely identify a change across all
+drafts of it.  By including a unique Change-Id in the commit message,
+Gerrit can automatically associate a new version of a change back
+to its original review, even across cherry-picks and rebases.
+
+To be picked up by Gerrit, a Change-Id line must be in the bottom
+portion (last paragraph) of a commit message, and may be mixed
+together with the Signed-off-by, Acked-by, or other such footers.
+For example:
+
+----
+  $ git log -1
+  commit 29a6bb1a059aef021ac39d342499191278518d1d
+  Author: A. U. Thor <author@example.com>
+  Date: Thu Aug 20 12:46:50 2009 -0700
+
+      Improve foo widget by attaching a bar.
+
+      We want a bar, because it improves the foo by providing more
+      wizbangery to the dowhatimeanery.
+
+      Bug: #42
+      Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
+      Signed-off-by: A. U. Thor <author@example.com>
+      CC: R. E. Viewer <reviewer@example.com>
+----
+
+In the above example, `Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b`
+is the unique identity assigned to this change.  It does not match
+the commit name, `29a6...`, as the change may have been amended or
+rebased to address reviewer comments since its initial inception.
+
+To avoid confusion with commit names, Change-Ids typically are with
+an uppercase `I`.
+
+Creation
+--------
+
+Gerrit Code Review provides a standard 'commit-msg' hook which
+can be installed in the local Git repository to automatically
+create and insert a unique Change-Id line during `git commit`.
+To install the hook, copy it from Gerrit's SSH daemon:
+
+  $ scp -P 29418 review.example.com:hooks/commit-msg .git/hooks
+
+For more details, see link:cmd-hook-commit-msg.html[commit-msg].
+
+Change Upload
+--------------
+
+During upload by pushing to a `refs/for/\*` or `refs/heads/\*`
+branch, Gerrit will use the Change-Id line to:
+
+* Create a new change
++
+If this is the first time it has seen the Change-Id mentioned in
+the commit message, Gerrit will create a new change for review.
+
+* Update an existing change
++
+If Gerrit has seen this Change-Id before, but has not yet seen this
+new commit object, Gerrit will add the new commit as a new patch
+set on the existing change.
+
+* Close an existing change
++
+If Gerrit has seen this Change-Id before, and the commit is being
+pushed directly into a branch, the existing change is updated with
+the new commit, and the change is closed and marked as merged.
+
+If a Change-Id line is not present in the commit message, Gerrit will
+automatically generate its own Change-Id and display it on the web.
+This line can be manually copied and inserted into an updated commit
+message if additional revisions to a change are required.
+
+For more details on using git push to upload changes to Gerrit,
+see link:user-upload.html#push_create[creating changes by git push].
+
+Git Tasks
+---------
+
+[[new]]
+Creating a new commit
+~~~~~~~~~~~~~~~~~~~~~
+
+When creating a new commit, ensure the 'commit-msg' hook has been
+installed in your repository (see above), and don't put a Change-Id
+line in the commit message.  When you exit the editor, git will call
+the hook, which will automatically generate and insert a unique
+Change-Id line.  You can inspect the modified message after the
+commit is complete by executing `git show`.
+
+[[amend]]
+Amending a commit
+~~~~~~~~~~~~~~~~~
+
+When amending a commit with `git commit \--amend`, leave the
+Change-Id line unmodified in the commit message.  This will allow
+Gerrit to automatically update the change with the amended commit.
+
+[[rebase]]
+Rebasing a commit
+~~~~~~~~~~~~~~~~~
+
+When rebasing a commit, leave the Change-Id line unmodified in the
+commit message.  This will allow Gerrit to automatically update
+the change with the rebased commit.
+
+[[squash]]
+Squashing commits
+~~~~~~~~~~~~~~~~~
+
+When squashing several commits together, try to preserve only one
+Change-Id line, and remove the others from the commit message.
+When faced with multiple lines, try to preserve a line which was
+already uploaded to Gerrit Code Review, and thus has a corresponding
+change that reviewers have already examined and left comments on.
+If you aren't sure which lines Gerrit knows about, try copying and
+pasting the lines into the search box in the top-right.
+
+If Gerrit already knows about more than one Change-Id, pick one
+to keep in the squashed commit message, and manually abandon the
+other changes through the web interface.
+
+[[cherry-pick]]
+Cherry-picking a commit
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When cherry-picking a commit, leave the Change-Id line alone to
+have Gerrit treat the cherry-picked commit as a replacement for
+the existing change.  This can be very useful if the project has
+a fast-forward-only merge policy, and the submitter is downloading
+and cherry-picking individual changes prior to submission, such as
+by link:cmd-cherry-pick.html[gerrit-cherry-pick].
+
+Or, you may wish to delete the Change-Id line and force a new
+Change-Id to be generated automatically, thus creating an entirely
+new change record for review.  This may be useful when backporting
+a change from the current development branch to a maintenance
+release branch.
+
+[[update-old]]
+Updating an old commit
+~~~~~~~~~~~~~~~~~~~~~~
+
+If a commit was created before the availability of Change-Id support,
+or was created in a Git repository that was missing the 'commit-msg'
+hook, simply copy the "`Change-Id: I...`" line from the first line
+of the Description section of the change and amend it to the bottom
+of the commit message.  Any subsequent uploads of the commit will
+be automatically associated with the prior change.
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
diff --git a/Documentation/user-upload.txt b/Documentation/user-upload.txt
index 8161457a45..86193794a1 100644
--- a/Documentation/user-upload.txt
+++ b/Documentation/user-upload.txt
@@ -1,36 +1,36 @@
 Gerrit2 - Uploading Changes
 ===========================
 
-Gerrit supports three methods of uploading changes for review:
+Gerrit supports three methods of uploading changes:
 
 * Use `repo upload`, to create changes for review
 * Use `git push`, to create changes for review
 * Use `git push`, and bypass code review
 
-All three methods use SSH public key authentication, which must
+All three methods rely on SSH public key authentication, which must
 first be configured by the uploading user.
 
-SSH Authentication
-------------------
+SSH
+---
 
-Each user uploading changes to Gerrit must configure one
-or more SSH public keys.  The per-user SSH key list can be
-accessed over the web within Gerrit by `Settings` (or by visting
-`http://'hostname'/settings`) then accessing the `SSH Keys` tab.
+Each user uploading changes to Gerrit must configure one or more SSH
+public keys.  The per-user SSH key list can be accessed over the web
+within Gerrit by `Settings`, and then accessing the `SSH Keys` tab.
 
-To register a new SSH key for use with Gerrit, paste the contents
-of your `id_rsa.pub` or `id_dsa.pub` file into the text box and
-click the add button.
+[[configure_ssh]]
+Configuration
+~~~~~~~~~~~~~
 
-[NOTE]
-Gerrit only understands SSH version 2 public keys.  Keys may be
-supplied in either the OpenSSH format (key starts with `ssh-rsa`
-or `ssh-dss`) or the RFC 4716 format (file starts with `---- BEGIN
-SSH2 PUBLIC KEY ----`).
+To register a new SSH key for use with Gerrit, paste the contents of
+your `id_rsa.pub` or `id_dsa.pub` file into the text box and click
+the add button.  Gerrit only understands SSH version 2 public keys.
+Keys may be supplied in either the OpenSSH format (key starts with
+`ssh-rsa` or `ssh-dss`) or the RFC 4716 format (file starts with
+`---- BEGIN SSH2 PUBLIC KEY ----`).
 
-Typically your SSH keys are stored in your home directory, under
-`~/.ssh`.  If you don't have any keys yet, you can create a new
-one and protect it with a passphrase:
+Typically SSH keys are stored in your home directory, under `~/.ssh`.
+If you don't have any keys yet, you can create a new one and protect
+it with a passphrase:
 
 ====
   ssh-keygen -t rsa
@@ -44,15 +44,16 @@ and paste it into Gerrit's web interface:
 ====
 
 [TIP]
-Users who frequently use Gerrit to upload changes will also want
-to consider starting a `ssh-agent`, and adding their key to the
-list managed by the agent, to reduce the frequency of entering the
+Users who frequently upload changes will also want to consider
+starting a `ssh-agent`, and adding their private key to the list
+managed by the agent, to reduce the frequency of entering the
 key's passphrase.  Consult `man ssh-agent`, or your SSH client's
 documentation, for more details on configuration of the agent
 process and how to add the private key.
 
-[[test_ssh]]Testing Your SSH Connection
----------------------------------------
+[[test_ssh]]
+Testing Connections
+~~~~~~~~~~~~~~~~~~~
 
 To verify your SSH key is working correctly, try using an SSH client
 to connect to Gerrit's SSHD port.  By default Gerrit is running on
@@ -77,35 +78,19 @@ number from the second field:
   hostname 29418
 ====
 
-[TIP]
 If you are developing an automated tool to perform uploads to Gerrit,
 let the user supply the hostname or the web address for Gerrit,
 and obtain the port number on the fly from the `/ssh_info` URL.
 The returned output from this URL is always `'hostname' SP 'port'`,
-or `NOT_AVAILABLE` if the SSHD server isn't running.
-
-
-repo upload: Create Changes
----------------------------
-
-To upload changes to a project using `repo`, ensure the manifest's
-review field has been configured to point to the Gerrit server.
-Only the hostname or the web address needs to be given in the
-manifest file. During upload `repo` will automatically determine the
-correct port number by reading `http://'reviewhostname'/ssh_info`
-when its invoked.
-
-Each new commit uploaded by `repo upload` will be converted into
-a change record on the server.  Other users (e.g. project owners)
-who have configured Gerrit to notify them of new changes will be
-automatically sent an email message.  Additional notifications can
-be sent through command line options.
+or `NOT_AVAILABLE` if the SSHD server is not currently running.
 
-For more details on using `repo upload`, see `repo help upload`.
 
+git push
+--------
 
-[[push_create]]git push: Create Changes
----------------------------------------
+[[push_create]]
+Create Changes
+~~~~~~~~~~~~~~
 
 To create new changes for review, simply push into the project's
 magical `refs/for/'branch'` ref using any Git client tool:
@@ -177,8 +162,38 @@ branches, consider adding a custom remote block to your project's
 ====
 
 
-git push: Replace Changes
--------------------------
+[[push_replace]]
+Replace Changes
+~~~~~~~~~~~~~~~
+
+To add an additional patch set to a change, ensure Change-Id
+lines were created in the original commit messages, and just use
+`git push URL HEAD:refs/for/...` as <<push_create,described above>>.
+Gerrit Code Review will automatically match the commits back to
+their original changes by taking advantage of the Change-Id lines.
+
+If Change-Id lines are not present in the commit messages, consider
+amending the message and copying the line from the change's page
+on the web, and then using `git push` as described above.
+
+If Change-Id lines are not available, then the user must use the
+manual mapping technique described below.
+
+For more about Change-Ids, see link:user-changeid.html[Change-Id Lines].
+
+Manual Replacment Mapping
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.Deprecation Warning
+****
+The remainder of this section describes a manual method of replacing
+changes by matching each commit name to an existing change number.
+End-users should instead prefer to use Change-Id lines in their
+commit messages, as the process is then fully automated by Gerrit
+during normal uploads.
+
+See above for the preferred technique of replacing changes.
+****
 
 To add an additional patch set to a change, replacing it with an
 updated version of the same logical modification, send the new
@@ -225,8 +240,8 @@ won't do anything with it.  For this reason it is a good idea to
 always include the create change refspec when uploading replacements.
 
 
-git push: Bypass Review
------------------------
+Bypass Review
+~~~~~~~~~~~~~
 
 Changes (and annotated tags) can be pushed directly into a
 repository, bypassing the review process.  This is primarily useful
@@ -265,6 +280,52 @@ grant nothing at all.  This ensures that accidental pushes don't
 make undesired changes to the public repository.
 
 
+repo upload
+-----------
+
+repo is a multiple repository management tool, most commonly
+used by the Android Open Source Project.  For more details, see
+link:http://source.android.com/download/using-repo[using repo].
+
+[[repo_create]]
+Create Changes
+~~~~~~~~~~~~~~
+
+To upload changes to a project using `repo`, ensure the manifest's
+review field has been configured to point to the Gerrit server.
+Only the hostname or the web address needs to be given in the
+manifest file. During upload `repo` will automatically determine the
+correct port number by reading `http://'reviewhostname'/ssh_info`
+when its invoked.
+
+Each new commit uploaded by `repo upload` will be converted into
+a change record on the server.  Other users (e.g. project owners)
+who have configured Gerrit to notify them of new changes will be
+automatically sent an email message.  Additional notifications can
+be sent through command line options.
+
+For more details on using `repo upload`, see `repo help upload`.
+
+[[repo_replace]]
+Replace Changes
+~~~~~~~~~~~~~~~
+
+To replace changes, ensure Change-Id lines were created in the
+commit messages, and just use `repo upload` without the `\--replace`
+command line flag.  Gerrit Code Review will automatically match
+the commits back to their original changes by taking advantage of
+their Change-Id lines.
+
+If Change-Id lines are not present in the commit messages, consider
+amending the message and copying the line from the change's page
+on the web.
+
+If Change-Id lines are not available, then the user must use the much
+more manual mapping technique offered by `repo upload \--replace`.
+
+For more about Change-Ids, see link:user-changeid.html[Change-Id Lines].
+
+
 Gritty Details
 --------------