git-review: update documentation
Change-Id: I7d3b0d0e6c82d14ded8c75986c48fcb026b0f783
Reviewed-on: https://go-review.googlesource.com/1740
Reviewed-by: Russ Cox <rsc@golang.org>
diff --git a/git-review/doc.go b/git-review/doc.go
index 366828a..c3a37bb 100644
--- a/git-review/doc.go
+++ b/git-review/doc.go
@@ -33,14 +33,20 @@
submit = review submit
sync = review sync
-The commands are:
+All commands accept these global flags:
-change
+The -v flag prints all Git commands that make changes.
+
+The -n flag prints all commands that would be run, but does not run them.
+
+Descriptions of each command follow.
+
+Change
The change command creates and moves between Git branches and maintains the
pending commits on work branches.
- git review change [branchname]
+ git review change [-a] [-q] [branchname]
Given a branch name as an argument, the change command switches to the named
branch, creating it if necessary. If the branch is created and there are staged
@@ -51,28 +57,31 @@
staged changes in the current branch or, if there is already a pending change,
amends that change.
-TODO: document -q, -a
+The -q option skips the editing of an extant pending change's commit message.
-gofmt
+The -a option automatically adds any unstaged changes in tracked files during
+commit; it is equivalent to the 'git commit' -a option.
-The gofmt command applies the gofmt program to all files modified on the
-current work branch (TODO: is this right?).
+Gofmt
- git review gofmt [-a] [-c]
+The gofmt command applies the gofmt program to all files modified in the
+current work branch, both in the staging area (index) and the working tree
+(local directory).
-By default, the gofmt command leaves any formatting changes unstaged.
+ git review gofmt [-l]
-The -a option (TODO).
+The -l option causes the command to list the files that need reformatting but
+not reformat them. Otherwise, the gofmt command reformats modified files in
+place. That is, files in the staging area are reformatted in the staging area,
+and files in the working tree are reformatted in the working tree.
-The -c option (TODO).
-
-help
+Help
The help command displays basic usage instructions.
git review help
-hooks
+Hooks
The hooks command installs the Git hooks to enforce code review conventions.
@@ -85,19 +94,24 @@
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.
-hook-invoke
+The hooks command will not overwrite an existing hook.
+If it is not installing hooks, use 'git review hooks -v' for details.
+This hook installation is also done at startup by all other git review
+commands, except 'help'.
+
+Hook-Invoke
The hook-invoke command is an internal command that invokes the named Git hook.
- git review hook-invoke <hook>
+ git review hook-invoke <hook> [args]
It is run by the shell scripts installed by the "git review hooks" command.
-mail
+Mail
The mail command starts the code review process for the pending change.
- git mail [-f] [-r email] [-cc email]
+ git review mail [-f] [-r email] [-cc email]
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.
@@ -111,17 +125,20 @@
The mail command fails if there are staged changes that are not committed. The
-f flag overrides this behavior.
-pending
+The mail command assumes that the Gerrit remote is called 'origin'.
+
+Pending
The pending command prints to standard output the status of all pending changes
-and unstaged files in the local repository.
+and staged, unstaged, and untracked files in the local repository.
- git review [-l] pending
+ git review pending [-l]
The -l flag causes the command to use only locally available information.
-By default, it contacts the Gerrit server for code review information.
+By default, it fetches recent commits and code review information from the
+Gerrit server.
-submit
+Submit
The submit command pushes the pending change to the Gerrit server and tells
Gerrit to submit it to the master branch.
@@ -135,7 +152,9 @@
current branch to the submitted commit, if it can do so cleanly.
If not, it will prompt the user to run 'git review sync' manually.
-sync
+After a successful sync, the branch can be used to prepare a new change.
+
+Sync
The sync command updates the local repository.
diff --git a/git-review/review.go b/git-review/review.go
index 7097e8e..fa789ae 100644
--- a/git-review/review.go
+++ b/git-review/review.go
@@ -47,6 +47,11 @@
The review command is a wrapper for the git command that provides a simple
interface to the "single-commit feature branch" development model.
+See the full docs for details: https://godoc.org/golang.org/x/review/git-review
+
+The -v flag prints all Git commands that make changes.
+The -n flag prints all commands that would be run, but does not run them.
+
Available commands:
change [name]
@@ -54,9 +59,14 @@
with the staged changes. If a branch name is provided, check
out that branch (creating it if it does not exist).
Does not amend the existing commit when switching branches.
+ If -q is specified, skip the editing of an extant pending
+ change's commit message.
+ If -a is specified, automatically add any unstaged changes in
+ tracked files during commit.
gofmt [-l]
- Run gofmt on all tracked files in the staging area and the working tree.
+ Run gofmt on all tracked files in the staging area and the
+ working tree.
If -l is specified, list files that need formatting.
Otherwise, reformat files in place.
@@ -65,23 +75,28 @@
hooks
Install Git commit hooks for Gerrit and gofmt.
- Every other operation except help also does this, if they are not
- already installed.
+ Every other operation except help also does this,
+ if they are not already installed.
mail [-f] [-r reviewer,...] [-cc mail,...]
Upload change commit to the code review server and send mail
requesting a code review.
If -f is specified, upload even if there are staged changes.
+ The -r and -cc flags identify the email addresses of people to
+ do the code review and to be CC'ed about the code review.
+ Multiple addresses are given as a comma-separated list.
mail -diff
Show the changes but do not send mail or upload.
- pending [-r]
- Show local branches and their head commits.
- If -r is specified, show additional information from Gerrit.
+ pending [-l]
+ Show the status of all pending changes and staged, unstaged,
+ and untracked files in the local repository.
+ If -l is specified, only use locally available information.
submit
- Submit the completed change commit into the repository.
+ Push the pending change to the Gerrit server and tell Gerrit to
+ submit it to the master branch.
sync
Fetch changes from the remote repository and merge them into
