From 92437a01419e83f631c250619eea70b36bf8e116 Mon Sep 17 00:00:00 2001
From: "Shawn O. Pearce" <sop@google.com>
Date: Fri, 28 Aug 2009 20:30:26 -0700
Subject: [PATCH] gerrit approve: Add user documentation

Change-Id: I2ad1fa595b0075b8243151f55455fa6745dce598
Signed-off-by: Shawn O. Pearce <sop@google.com>
---
 Documentation/cmd-approve.txt | 87 +++++++++++++++++++++++++++++++++++
 Documentation/cmd-index.txt   |  3 ++
 2 files changed, 90 insertions(+)
 create mode 100644 Documentation/cmd-approve.txt

diff --git a/Documentation/cmd-approve.txt b/Documentation/cmd-approve.txt
new file mode 100644
index 0000000000..a81ce827ff
--- /dev/null
+++ b/Documentation/cmd-approve.txt
@@ -0,0 +1,87 @@
+gerrit approve
+==============
+
+NAME
+----
+gerrit approve - Approve one or more patch sets
+
+SYNOPSIS
+--------
+[verse]
+'ssh' -p <port> <host> 'gerrit approve' [\--project <PROJECT>] [\--message <MESSAGE>] {COMMIT | CHANGEID,PATCHSET}...
+
+DESCRIPTION
+-----------
+Updates the current user's approval status of the specified patch
+sets, sending out email notifications and updating the database.
+
+Patch sets should be specified as complete or abbreviated commit
+SHA-1s.  If the same commit is available in multiple projects the
+\--project option may be used to limit where Gerrit searches for
+the change to only the contents of the specified project.
+
+For current backward compatibility with user tools patch sets may
+also be specified in the legacy 'CHANGEID,PATCHSET' format, such as
+'8242,2'.  Support for this legacy format is planned to be removed
+in a future edition of Gerrit Code Review.  Use of commit SHA-1s
+is strongly encouraged.
+
+OPTIONS
+-------
+
+\--project::
+-p::
+	Name of the project the intended changes are contained
+	within.  This option must be supplied before the commit
+	SHA-1 in order to take effect.
+
+\--message::
+-m::
+	Optional cover letter to include as part of the message
+	sent to reviewers when the approval states are updated.
+
+\--help::
+-h::
+	Display site-specific usage information, including the
+	complete listing of supported approval categories and values.
+
+\--code-review::
+\--verified::
+	Set the approval category to the value 'N'.  The exact
+	option names supported and the range of values permitted
+	differs per site, check the output of \--help, or contact
+	your site administrator for further details.
+
+ACCESS
+------
+Any user who has configured an SSH key.
+
+SCRIPTING
+---------
+This command is intended to be used in scripts.
+
+EXAMPLES
+--------
+
+Approve the change with commit c0ff33 as "Verified +1"
+=====
+	$ ssh -p 29418 review.example.com gerrit approve --verified=+1 c0ff33
+=====
+
+Mark the unmerged commits both "Verified +1" and "Code Review +2":
+====
+	$ ssh -p 29418 review.example.com gerrit approve \
+	--verified=+1 \
+	--code-review=+2 \
+	--project=this/project \
+	$(git rev-list origin/master..HEAD)
+====
+
+SEE ALSO
+--------
+
+* link:access-control.html[Access Controls]
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
diff --git a/Documentation/cmd-index.txt b/Documentation/cmd-index.txt
index bab82e1b34..9d07877a89 100644
--- a/Documentation/cmd-index.txt
+++ b/Documentation/cmd-index.txt
@@ -57,6 +57,9 @@ link:cmd-receive-pack.html[git receive-pack]::
 Also implements the magic associated with uploading commits for
 review.  See link:user-upload.html#push_create[Creating Changes].
 
+link:cmd-approve.html[gerrit approve]::
+	Approve a patch set from the command line.
+
 link:cmd-ls-projects.html[gerrit ls-projects]::
 	List projects visible to the caller.