git-codereview: document multiple-commit workflow
Also document a few recent changes that hadn't been added yet.
For golang/go#13651.
Change-Id: I79ec381abf34a385f42df40ee8450b413e0a3b9a
Reviewed-on: https://go-review.googlesource.com/19561
Reviewed-by: Austin Clements <austin@google.com>
diff --git a/git-codereview/doc.go b/git-codereview/doc.go
index 153bd9a..2518c3d 100644
--- a/git-codereview/doc.go
+++ b/git-codereview/doc.go
@@ -6,13 +6,15 @@
Git-codereview manages the code review process for Git changes using a Gerrit
server.
-The git-codereview tool manages "change branches" in the local git repository.
-Each such branch tracks a single commit, or "pending change",
+The git-codereview tool manages ``change branches'' in the local git repository.
+Each such branch tracks a single commit, or ``pending change,''
that is reviewed using a Gerrit server; the Gerrit remote must be
-named 'origin' in the local git repo.
+named ``origin'' in the local git repo.
Modifications to the pending change are applied by amending the commit.
-This process implements the "single-commit feature branch" model.
+This process implements the ``single-commit feature branch'' model.
+Creating multiple-commit feature branches, for example to break a large
+change into a reviewable sequence, is also supported; see the discussion below.
Once installed as git-codereview, the tool's commands are available through git
either by running
@@ -36,6 +38,62 @@
submit = codereview submit
sync = codereview sync
+Single-Commit Work Branches
+
+For simple, unrelated changes, the typical usage of the git-codereview tool
+is to place each pending change in its own Git branch.
+In this workflow, the work branch contains
+either no pending change beyond origin/master (when there's no local work)
+or exactly one pending change beyond origin/master (the change being developed).
+
+When there is no pending change on the work branch,
+``git codereview change'' creates one by running ``git commit.''
+Otherwise, when there is already a pending change,
+``git codereview change'' revises it by running ``git commit --amend.''
+
+The ``git codereview mail'' and ``git codereview submit'' commands
+implicitly operate on the lone pending change.
+
+Multiple-Commit Work Branches
+
+Of course, it is not always feasible to put each pending change in a separate branch.
+A sequence of changes that build on one another is more easily
+managed as multiple commits on a single branch, and the git-codereview tool
+supports this workflow as well.
+To add a new pending change, invoke ``git commit'' directly,
+instead of ``git codereview change''.
+The git-codereview tool adjusts its behavior when there are
+multiple pending changes.
+
+The ``git codereview change'' command amends the top commit in the stack (HEAD).
+To amend a commit further down the stack, use Git's rebase support,
+for example by using ``git commit --fixup'' followed by ``git codereview rebase-work.''
+
+The ``git codereview mail'' command requires an explicit revision argument,
+but note that since ``git codereview mail'' is implemented as a ``git push,''
+any commits earlier in the stack are necessarily also mailed.
+
+The ``git codereview submit'' command also requires an explicit revision argument,
+and while earlier commits are necessarily still uploaded and mailed,
+only the named revision or revisions are submitted (merged into origin/master).
+In a single-commit work branch, a successful ``git codereview submit''
+effectively runs ``git codereview sync'' automatically.
+In a multiple-commit work branch, it does not, because
+the implied ``git rebase'' may conflict with the remaining pending commits.
+Instead it is necessary to run ``git codereview sync'' explicitly
+(when ready) after ``git codereview submit.''
+
+Reusing Work Branches
+
+Although one common practice is to create a new branch for each pending change,
+running ``git codereview submit'' (and possibly ``git codereview sync'')
+leaves the current branch ready for reuse with a future change.
+Some developers find it helpful to create a single work branch
+(``git change work'') and then do all work in that branch,
+possibly in the multiple-commit mode, never changing between branches.
+
+Command Details
+
All commands accept these global flags:
The -v flag prints all commands that make changes.
@@ -48,16 +106,16 @@
git codereview branchpoint
-The branchpoint command prints the commit hash of the most recent change
+The branchpoint command prints the commit hash of the most recent commit
on the current branch that is shared with the Gerrit server. This is the point
where local work branched from the published tree. The command is intended
-mainly for use in scripts. For example, "git diff $(git codereview branchpoint)"
-or "git log $(git codereview branchpoint)..HEAD".
+mainly for use in scripts. For example, ``git diff $(git codereview branchpoint)''
+or ``git log $(git codereview branchpoint)..HEAD''.
Change
The change command creates and moves between Git branches and maintains the
-pending commits on work branches.
+pending changes on work branches.
git codereview change [-a] [-q] [branchname]
@@ -72,7 +130,7 @@
The -q option skips the editing of an extant pending change's commit message.
-The -a option automatically adds any unstaged changes in tracked files during
+The -a option automatically adds any unstaged edits in tracked files during
commit; it is equivalent to the 'git commit' -a option.
Gofmt
@@ -103,14 +161,14 @@
The pre-commit hook checks that all Go code is formatted with gofmt and that
the commit is not being made directly to the master branch.
-The commit-msg hook adds the Gerrit "Change-Id" line to the commit message if
+The commit-msg hook adds the Gerrit ``Change-Id'' line to the commit message if
not present. It also checks that the message uses the convention established by
the Go project that the first line has the form, pkg/path: summary.
The hooks command will not overwrite an existing hook.
-If it is not installing hooks, use 'git codereview hooks -v' for details.
+If it is not installing hooks, use ``git codereview hooks -v'' for details.
This hook installation is also done at startup by all other git codereview
-commands, except 'help'.
+commands, except ``git codereview help''.
Hook-Invoke
@@ -118,13 +176,13 @@
git codereview hook-invoke <hook> [args]
-It is run by the shell scripts installed by the "git codereview hooks" command.
+It is run by the shell scripts installed by the ``git codereview hooks'' command.
Mail
The mail command starts the code review process for the pending change.
- git codereview mail [-f] [-r email] [-cc email]
+ git codereview mail [-f] [-r email] [-cc email] [revision]
It pushes the pending change commit in the current branch to the Gerrit code
review server and prints the URL for the change on the server.
@@ -140,45 +198,70 @@
from the git repository log to find email addresses of the form name@somedomain
and then, in case of ambiguity, using the reviewer who appears most often.
-The mail command fails if there are staged changes that are not committed.
+The mail command fails if there are staged edits that are not committed.
The -f flag overrides this behavior.
The mail command updates the tag <branchname>.mailed to refer to the
-commit that was most recently mailed, so running 'git diff <branchname>.mailed'
+commit that was most recently mailed, so running ``git diff <branchname>.mailed''
shows diffs between what is on the Gerrit server and the current directory.
+If there are multiple pending commits, the revision argument is mandatory.
+If no revision is specified, the mail command prints a short summary of
+the pending commits for use in deciding which to mail.
+
Pending
The pending command prints to standard output the status of all pending changes
and staged, unstaged, and untracked files in the local repository.
- git codereview pending [-l]
+ git codereview pending [-c] [-l] [-s]
+
+The -c flag causes the command to show pending changes only on the current branch.
The -l flag causes the command to use only locally available information.
By default, it fetches recent commits and code review information from the
Gerrit server.
+The -s flag causes the command to print abbreviated (short) output.
+
+Common shorter aliases include ``git p'' for ``git pending''
+and ``git pl'' for ``git pending -l'' (notably faster but without Gerrit information).
+
Rebase-work
The rebase-work command runs git rebase in interactive mode over pending changes.
-It is shorthand for "git rebase -i $(git codereview branchpoint)".
-It differs from plain "git rebase -i" in that the latter will try to incorporate
-new commits from the origin branch during the rebase, and git rebase-work
-does not.
+It is shorthand for ``git rebase -i $(git codereview branchpoint)''.
+It differs from plain ``git rebase -i'' in that the latter will try to incorporate
+new commits from the origin branch during the rebase;
+``git codereview rebase-work'' does not.
+
+In multiple-commit workflows, rebase-work is used so often
+that it can be helpful to alias it to ``git rw''.
Submit
The submit command pushes the pending change to the Gerrit server and tells
Gerrit to submit it to the master branch.
- git codereview submit
+ git codereview submit [-i | revision...]
The command fails if there are modified files (staged or unstaged) that are not
part of the pending change.
-After submitting the change, the change command tries to synchronize the
+The -i option causes the submit command to open a list of commits to submit
+in the configured text editor, similar to ``git rebase -i''.
+
+If multiple revisions are specified, the submit command submits each one in turn,
+stopping at the first failure.
+
+When run in a multiple-commit work branch,
+either the -i option or the revision argument is mandatory.
+If both are omitted, the submit command prints a short summary of
+the pending commits for use in deciding which to submit.
+
+After submitting the pending changes, the submit command tries to synchronize the
current branch to the submitted commit, if it can do so cleanly.
-If not, it will prompt the user to run 'git codereview sync' manually.
+If not, it will prompt the user to run ``git codereview sync'' manually.
After a successful sync, the branch can be used to prepare a new change.
@@ -188,9 +271,8 @@
git codereview sync
-It fetches changes from the remote repository and merges changes from the
-upstream branch to the current branch, rebasing the pending change, if any,
-onto those changes.
+It fetches commits from the remote repository and merges them from the
+upstream branch to the current branch, rebasing any pending changes.
*/
package main
