documentation: Clean up command line documentation, examples

The formatting was pretty wrong after upgrading to a newer version
of AsciiDoc, so fix up most of the formatting, correct some order
of commands in the index, and make create-project conform to the
same format used by create-account and create-group.

Change-Id: I555969655ba135e549f0b8b5b02e5f3669a0b282

Documentation/cmd-cherry-pick.txt

@@ -9,10 +9,8 @@ SYNOPSIS
 --------
 [verse]
 'gerrit-cherry-pick' <remote> <changeid>...
-
+'gerrit-cherry-pick' --continue | --skip | --abort
-'gerrit-cherry-pick' \--continue | \--skip | \--abort
+'gerrit-cherry-pick' --close <remote>
-
-'gerrit-cherry-pick' \--close <remote>
 
 DESCRIPTION
 -----------
@@ -22,13 +20,13 @@ onto the current branch.
 
 If a merge failure prevents this from being completely automatic,
 you will be asked to resolve the conflict and restart the command
-with the `\--continue` option.
+with the `--continue` option.
 
 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
+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.
@@ -38,9 +36,11 @@ OBTAINING
 To obtain the 'gerrit-cherry-pick' script use scp, curl or wget to
 copy it to your local system:
 
+====
   $ scp -p -P 29418 john.doe@review.example.com:bin/gerrit-cherry-pick ~/bin/
 
   $ curl http://review.example.com/tools/bin/gerrit-cherry-pick
+====
 
 GERRIT
 ------

Documentation/cmd-create-account.txt

@@ -8,12 +8,12 @@ gerrit create-account - Create a new batch/role account.
 SYNOPSIS
 --------
 [verse]
-'ssh' -p <port> <host> 'gerrit create-account' \
+'ssh' -p <port> <host> 'gerrit create-account'
-[\--group <GROUP>] \
+  [--group <GROUP>]
-[\--full-name <FULLNAME>] \
+  [--full-name <FULLNAME>]
-[\--email <EMAIL>] \
+  [--email <EMAIL>]
-[\--ssh-key -|<KEY>] \
+  [--ssh-key - | <KEY>]
-<USERNAME>
+  <USERNAME>
 
 DESCRIPTION
 -----------
@@ -38,23 +38,23 @@ OPTIONS
 <USERNAME>::
 	Required; SSH username of the user account.
 
-\--ssh-key::
+--ssh-key::
 	Content of the public SSH key to load into the account's
 	keyring.  If `-` the key is read from stdin, rather than
 	from the command line.
 
-\--group::
+--group::
-	Name of the group to put the user into.  Multiple \--group
+	Name of the group to put the user into.  Multiple --group
 	options may be specified to add the user to multiple groups.
 
-\--full-name::
+--full-name::
 	Display name of the user account.
 +
-Names containing spaces should be quoted in single quotes (\').
+Names containing spaces should be quoted in single quotes (').
 This most likely requires double quoting the value, for example
-`\--full-name "\'A description string\'"`.
+`--full-name "'A description string'"`.
 
-\--email::
+--email::
 	Preferred email address for the user account.
 
 EXAMPLES

Documentation/cmd-create-group.txt

@@ -8,12 +8,12 @@ gerrit create-group - Create a new account group.
 SYNOPSIS
 --------
 [verse]
-'ssh' -p <port> <host> 'gerrit create-group' \
+'ssh' -p <port> <host> 'gerrit create-group'
-[\--owner <GROUP>] \
+  [--owner <GROUP>]
-[\--description <DESC>] \
+  [--description <DESC>]
-[\--member <USERNAME>] \
+  [--member <USERNAME>]
-[\--group <GROUP>] \
+  [--group <GROUP>]
-<GROUP>
+  <GROUP>
 
 DESCRIPTION
 -----------
@@ -37,22 +37,22 @@ OPTIONS
 <GROUP>::
 	Required; name of the new group.
 
-\--owner, -o::
+--owner, -o::
 	Name of the owning group. If not specified the group will be self-owning.
 
-\--description, -d::
+--description, -d::
 	Description of group.
 +
 Description values containing spaces should be quoted in single quotes
-(\').  This most likely requires double quoting the value, for example
+(').  This most likely requires double quoting the value, for example
-`\--description "\'A description string\'"`.
+`--description "'A description string'"`.
 
-\--member::
+--member::
-	User name to become initial member of the group.  Multiple \--member
+	User name to become initial member of the group.  Multiple --member
 	options may be specified to add more initial members.
 
-\--group::
+--group::
-	Group name to include in the group.  Multiple \--group options may
+	Group name to include in the group.  Multiple --group options may
 	be specified to include more initial groups.
 
 EXAMPLES

Documentation/cmd-create-project.txt

@@ -8,18 +8,19 @@ gerrit create-project - Create a new hosted project
 SYNOPSIS
 --------
 [verse]
- 'ssh' -p <port> <host> 'gerrit create-project' \
+'ssh' -p <port> <host> 'gerrit create-project'
- --name <NAME> \
+  [--owner <GROUP> ... | -o <GROUP> ...]
- [--branch <REF>] \
+  [--parent <NAME> | -p <NAME> ]
- [\--owner <GROUP> ...] \
+  [--permissions-only]
- [\--parent <NAME>] \
+  [--description <DESC> | -d <DESC>]
- [\--permissions-only] \
+  [--submit-type <TYPE> |  -t <TYPE>]
- [\--description <DESC>] \
+  [--use-contributor-agreements | --ca]
- [\--submit-type <TYPE>] \
+  [--use-signed-off-by | --so]
- [\--use-content-merge] \
+  [--use-content-merge]
- [\--use-contributor-agreements] \
+  [--require-change-id | --id]
- [\--use-signed-off-by] \
+  [--branch <REF> | -b <REF>]
- [\--empty-commit]
+  [--empty-commit]
+  { <NAME> | --name <NAME> }
 
 DESCRIPTION
 -----------
@@ -37,7 +38,7 @@ on the remote system to create the empty repository.
 ACCESS
 ------
 Caller must be a member of any of the groups defined by
-repository.*.createGroup in gerrit.config.
+`repository.*.createGroup` in gerrit.config.
 
 If there is no such declaration, caller is required to be a member
 of the privileged 'Administrators' group.
@@ -48,43 +49,53 @@ This command is intended to be used in scripts.
 
 OPTIONS
 -------
-\--name::
+<NAME>::
-	Required; name of the project to create.  If name ends with
+	Required; name of the new project to create.  If name ends
-	`.git` the suffix will be automatically removed.
+	with `.git` the suffix will be automatically removed.
 
-\--branch::
+--name::
+-n::
+	Deprecated alias for the <NAME> argument. This option may
+	be removed in a future release.
+
+--branch::
+-b::
 	Name of the initial branch in the newly created project.
 	Defaults to 'master'.
 
-\--owner::
+--owner::
+-o::
 	Name of the group(s) which will initially own this repository.
 	The specified group(s) must already be defined within Gerrit.
 	Several groups can be specified on the command line.
 +
-Defaults to what is specified by repository.*.ownerGroup
+Defaults to what is specified by `repository.*.ownerGroup`
 in gerrit.config. If no such declaration(s) exist,
-repository.*.createGroup will be used. If they don't exist,
+`repository.*.createGroup` will be used. If they don't exist,
 `Administrators` will be used.
 
-\--parent::
+--parent::
+-p::
 	Name of the parent project to inherit access rights
 	through. If not specified, the parent is set to the default
 	project `All-Projects`.
 
-\--permissions-only::
+--permissions-only::
 	Create the project only to serve as a parent for other
 	projects.  The new project's Git repository will be
 	initialized to have 'HEAD' point to 'refs/meta/config'.
 
-\--description::
+--description::
+-d::
 	Initial description of the project.  If not specified,
 	no description is stored.
 +
 Description values containing spaces should be quoted in single quotes
-(\').  This most likely requires double quoting the value, for example
+(').  This most likely requires double quoting the value, for example
-`\--description "\'A description string\'"`.
+`--description "'A description string'"`.
 
-\--submit-type::
+--submit-type::
+-t::
 	Action used by Gerrit to submit an approved change to its
 	destination branch.  Supported options are:
 +
@@ -97,24 +108,32 @@ Description values containing spaces should be quoted in single quotes
 Defaults to MERGE_IF_NECESSARY.  For more details see
 link:project-setup.html#submit_type[Change Submit Actions].
 
-\--use-content-merge::
+--use-content-merge::
 	If enabled, Gerrit will try to perform a 3-way merge of text
 	file content when a file has been modified by both the
 	destination branch and the change being submitted.  This
 	option only takes effect if submit type is not
 	FAST_FORWARD_ONLY.  Disabled by default.
 
-\--use-contributor-agreements::
+--use-contributor-agreements::
+--ca::
 	If enabled, authors must complete a contributor agreement
 	on the site before pushing any commits or changes to this
 	project.  Disabled by default.
 
-\--use-signed-off-by::
+--use-signed-off-by::
+--so:
 	If enabled, each change must contain a Signed-off-by line
 	from either the author or the uploader in the commit message.
 	Disabled by default.
 
-\--empty-commit:
+--require-change-id::
+--id::
+	Require a valid link:user-changeid.html[Change-Id] footer
+	in any commit uploaded for review. This does not apply to
+	commits pushed directly to a branch or tag.
+
+--empty-commit::
 	Creates an initial empty commit for the Git repository of the
 	project that is newly created.
 
@@ -124,13 +143,13 @@ EXAMPLES
 Create a new project called `tools/gerrit`:
 
 ====
-	$ ssh -p 29418 review.example.com gerrit create-project --name tools/gerrit.git
+	$ ssh -p 29418 review.example.com gerrit create-project tools/gerrit.git
 ====
 
 Create a new project with a description:
 
 ====
-	$ ssh -p 29418 review.example.com gerrit create-project --name tool.git --description "'Tools used by build system'"
+	$ ssh -p 29418 review.example.com gerrit create-project tool.git --description "'Tools used by build system'"
 ====
 
 Note that it is necessary to quote the description twice.  The local

Documentation/cmd-flush-caches.txt

@@ -8,8 +8,9 @@ gerrit flush-caches - Flush some/all server caches from memory
 SYNOPSIS
 --------
 [verse]
- 'ssh' -p <port> <host> 'gerrit flush-caches' \
+'ssh' -p <port> <host> 'gerrit flush-caches' --all
- [\--all | \--list | \--cache <NAME> ...]
+'ssh' -p <port> <host> 'gerrit flush-caches' --list
+'ssh' -p <port> <host> 'gerrit flush-caches' --cache <NAME> ...
 
 DESCRIPTION
 -----------
@@ -32,19 +33,19 @@ This command is intended to be used in scripts.
 
 OPTIONS
 -------
-\--all::
+--all::
 	Flush all known caches.  This is like applying a big hammer,
 	it will force everything out, potentially more than was
-	necessary for the change made.	This option automatically
+	necessary for the change made. This option automatically
 	skips flushing potentially dangerous caches such as
 	"web_sessions".  To flush one of these caches, the caller
 	must specifically name them on the command line, e.g. pass
-	`\--cache=web_sessions`.
+	`--cache web_sessions`.
 
-\--list::
+--list::
 	Show a list of the caches.
 
-\--cache=<NAME>::
+--cache <NAME>::
 	Flush only the cache called <NAME>.  May be supplied more
 	than once to flush multiple caches in a single command
 	execution.

Documentation/cmd-gsql.txt

@@ -8,9 +8,9 @@ gerrit gsql - Administrative interface to active database
 SYNOPSIS
 --------
 [verse]
- 'ssh' -p <port> <host> 'gerrit gsql' \
+'ssh' -p <port> <host> 'gerrit gsql'
- [\--format \{PRETTY | JSON\}] \
+  [--format {PRETTY | JSON}]
- [\-c QUERY]
+  [-c QUERY]
 
 DESCRIPTION
 -----------
@@ -20,7 +20,7 @@ are supported, including SELECT, UPDATE, INSERT, DELETE and ALTER.
 
 OPTIONS
 -------
-\--format::
+--format::
 	Set the format records are output in.  In PRETTY (the
 	default) records are displayed in a tabular output suitable
 	for reading by a human on a sufficiently wide terminal.

Documentation/cmd-hook-commit-msg.txt

@@ -56,9 +56,11 @@ OBTAINING
 To obtain the 'commit-msg' script use scp, wget or curl to copy it
 to your local system:
 
+====
   $ scp -p -P 29418 john.doe@review.example.com:hooks/commit-msg .git/hooks/
 
   $ curl http://review.example.com/tools/hooks/commit-msg
+====
 
 SEE ALSO
 --------

Documentation/cmd-index.txt

@@ -51,6 +51,24 @@ see link:user-upload.html#test_ssh[Testing Your SSH Connection].
 [[user_commands]]User Commands
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+'gerrit approve'::
+	'Deprecated alias for `gerrit review`.'
+
+link:cmd-ls-projects.html[gerrit ls-projects]::
+	List projects visible to the caller.
+
+link:cmd-query.html[gerrit query]::
+	Query the change database.
+
+'gerrit receive-pack'::
+	'Depreated alias for `git receive-pack`.'
+
+link:cmd-review.html[gerrit review]::
+	Verify, approve and/or submit a patch set from the command line.
+
+link:cmd-stream-events.html[gerrit stream-events]::
+	Monitor events occuring in real time.
+
 git upload-pack::
 	Standard Git server side command for client side `git fetch`.
 
@@ -60,24 +78,6 @@ 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-review.html[gerrit approve]::
-	Alias for 'gerrit review'.
-
-link:cmd-ls-projects.html[gerrit ls-projects]::
-	List projects visible to the caller.
-
-link:cmd-query.html[gerrit query]::
-	Query the change database.
-
-link:cmd-review.html[gerrit review]::
-	Verify, approve and/or submit a patch set from the command line.
-
-link:cmd-stream-events.html[gerrit stream-events]::
-	Monitor events occuring in real time.
-
-gerrit receive-pack::
-	Legacy alias for `git receive-pack`.
-
 [[admin_commands]]Adminstrator Commands
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -96,6 +96,9 @@ link:cmd-flush-caches.html[gerrit flush-caches]::
 link:cmd-gsql.html[gerrit gsql]::
 	Administrative interface to active database.
 
+link:cmd-replicate.html[gerrit replicate]::
+	Manually trigger replication, to recover a node.
+
 link:cmd-set-project-parent.html[gerrit set-project-parent]::
 	Change the project permissions are inherited from.
 
@@ -108,9 +111,6 @@ link:cmd-show-connections.html[gerrit show-connections]::
 link:cmd-show-queue.html[gerrit show-queue]::
 	Display the background work queues, including replication.
 
-link:cmd-replicate.html[gerrit replicate]::
-	Manually trigger replication, to recover a node.
-
 link:cmd-kill.html[kill]::
 	Kills a scheduled or running task.
 

Documentation/cmd-ls-projects.txt

@@ -8,10 +8,10 @@ gerrit ls-projects - List projects visible to caller
 SYNOPSIS
 --------
 [verse]
- 'ssh' -p <port> <host> 'gerrit ls-projects'
+'ssh' -p <port> <host> 'gerrit ls-projects'
- [--show-branch <BRANCH1> ...]
+  [--show-branch <BRANCH> ...]
- [--tree]
+  [--tree]
- [--type {code | permissions | all}]
+  [--type {code | permissions | all}]
 
 DESCRIPTION
 -----------
@@ -31,27 +31,30 @@ This command is intended to be used in scripts.
 
 OPTIONS
 -------
-\--show-branch::
+--show-branch::
-\-b::
+-b::
 	Branch for which the command will display the sha of each project.
-	The command may have multiple \--show-branch parameters, in this case
+	The command may have multiple --show-branch parameters, in this case
 	sha will be shown for each of the branches.
 	If the user does not have READ access to some branch or the branch does not
-	exist then stub (forty '\-' symbols) is shown.
+	exist then stub (40 `-` symbols) is shown.
 	If the user does not have access to any branch in the project then the
 	whole project is not shown.
 
-\--tree::
+--tree::
-\-t::
+-t::
 	Displays project inheritance in a tree-like format.
 	This option does not work together with the show-branch option.
 
 --type::
-	Display only projects of the specified type. Supported
+	Display only projects of the specified type.  If not
-	types are `code` (any project likely to contain user files),
+	specified, defaults to `code`. Supported types:
-	`permissions` (projects created with the --permissions-only
++
-	flag), `all` (any type of project).  If not specified,
+--
-	defaults to `code`.
+`code`:: Any project likely to contain user files.
+`permissions`:: Projects created with the `--permissions-only` flag.
+`all`:: Any type of project.
+--
 
 EXAMPLES
 --------

Documentation/cmd-query.txt

@@ -8,14 +8,14 @@ gerrit query - Query the change database
 SYNOPSIS
 --------
 [verse]
- 'ssh' -p <port> <host> 'gerrit query' \
+'ssh' -p <port> <host> 'gerrit query'
- [\--format {TEXT | JSON}] \
+  [--format {TEXT | JSON}]
- [\--current-patch-set] \
+  [--current-patch-set]
- [\--patch-sets|--all-approvals] \
+  [--patch-sets | --all-approvals]
- [\--] \
+  [--]
- <query> \
+  <query>
- [limit:<n>] \
+  [limit:<n>]
- [resume\_sortkey:<sortKey>]
+  [resume_sortkey:<sortKey>]
 
 DESCRIPTION
 -----------
@@ -39,18 +39,23 @@ multiple levels of quoting required.
 
 OPTIONS
 -------
-\--current-patch-set::
+--format::
+	Formatting method for the results. TEXT is the default,
+	presenting a human readable display. JSON creates one line
+	per matching record, with embedded LFs escaped.
+
+--current-patch-set::
 	Include information about the current patch set in the results.
 
-\--patch-sets::
+--patch-sets::
 	Include information about all patch sets.  If combined with
-	the \--current-patch-set flag then the current patch set
+	the --current-patch-set flag then the current patch set
 	information will be output twice, once in each field.
 
-\--all-approvals::
+--all-approvals::
 	Include information about all patch sets along with the
 	approval information for each patch set.  If combined with
-	the \--current-patch-set flag then the current patch set
+	the --current-patch-set flag then the current patch set
 	information will be output twice, once in each field.
 
 limit:<n>::
@@ -59,7 +64,7 @@ limit:<n>::
 	than one limit: operator is provided, the smallest limit
 	will be used to cut the result set.
 
-resume\_sortkey:<sortKey>::
+resume_sortkey:<sortKey>::
 	Resume results from this sort key.  Callers should pass
 	the sortKey of the last change of the prior result set to
 	resume a prior query.  This is actually a query operator,
@@ -77,20 +82,20 @@ EXAMPLES
 --------
 
 Find the 2 most recent open changes in the tools/gerrit project:
------
+====
   $ ssh -p 29418 review.example.com gerrit query --format=JSON status:open project:tools/gerrit limit:2
   {"project":"tools/gerrit", ...}
   {"project":"tools/gerrit", ..., sortKey:"000e6aee00003e26", ...}
   {"type":"stats","rowCount":2,"runningTimeMilliseconds:15}
------
+====
 
 Resume the same query and obtain the final results:
------
+====
   $ ssh -p 29418 review.example.com gerrit query --format=JSON status:open project:tools/gerrit limit:2 resume_sortkey:000e6aee00003e26
   {"project":"tools/gerrit", ...}
   {"project":"tools/gerrit", ...}
   {"type":"stats","rowCount":1,"runningTimeMilliseconds:15}
------
+====
 
 
 SCHEMA

Documentation/cmd-receive-pack.txt

@@ -8,7 +8,7 @@ git-receive-pack - Receive what is pushed into the repository
 SYNOPSIS
 --------
 [verse]
-git receive-pack [\--reviewer <address>] [\--cc <address>] <project>
+'git receive-pack' [--reviewer <address>] [--cc <address>] <project>
 
 DESCRIPTION
 -----------
@@ -24,11 +24,11 @@ OPTIONS
 <project>::
 	The remote repository that will receive the pushed objects,
 	and create (or update) changes.  Within Gerrit Code Review
-	this is the name of a project.	The optional leading `/`
+	this is the name of a project.  The optional leading `/`
 	and or trailing `.git` suffix will be removed, if supplied.
 
-\--re <address>::
+--reviewer <address>::
-\--reviewer <address>::
+--re <address>::
 	Automatically add <address> as a reviewer to any change
 	created or updated by the pushed commit objects.  These
 	changes will appear in the reviewer's dashboard, and will
@@ -38,10 +38,10 @@ May be specified more than once to request multiple reviewers.
 +
 This is a Gerrit Code Review specific extension.
 
-\--cc <address>::
+--cc <address>::
 	Carbon-copy <address> on the created or updated changes,
 	but don't request them to perform a review.  Like with
-	\--reviewer the changes will appear in the CC'd user's
+	--reviewer the changes will appear in the CC'd user's
 	dashboard, and will be emailed to them.
 +
 May be specified more than once to specify multiple CCs.
@@ -82,12 +82,12 @@ Configure a push macro to perform the last action:
 ====
 
 afterwards `.git/config` contains the following:
-====
+----
-	[remote "charlie"]
+[remote "charlie"]
-		url = ssh://review.example.com:29418/project
+  url = ssh://review.example.com:29418/project
-		push = HEAD:refs/for/master
+  push = HEAD:refs/for/master
-		receivepack = git receive-pack --reviewer charlie@example.com --cc alice@example.com --cc bob@example.com
+  receivepack = git receive-pack --reviewer charlie@example.com --cc alice@example.com --cc bob@example.com
-====
+----
 
 and now sending a new change for review to charlie, CC'ing both
 alice and bob is much easier:

Documentation/cmd-replicate.txt

@@ -8,9 +8,9 @@ gerrit replicate - Manually trigger replication, to recover a node
 SYNOPSIS
 --------
 [verse]
-'ssh' -p <port> <host> 'gerrit replicate' \
+'ssh' -p <port> <host> 'gerrit replicate'
-[\--url <PATTERN>] \
+  [--url <PATTERN>]
-\{\--all | <PROJECT> ...}
+  {--all | <PROJECT> ...}
 
 DESCRIPTION
 -----------
@@ -32,13 +32,13 @@ replication run for all projects against that URL will update it.
   pack files to the destinations.
 +
 If the local server is repacked, and then the resulting pack files
-are sent to remote peers using `rsync -a \--delete-after`, there
+are sent to remote peers using `rsync -a --delete-after`, there
 is a chance that the rsync missed a change that was added during
 the rsync data transfer, and the rsync will remove that changes's
 data from the remote, even though the automatic replication pushed
 it there in parallel to the rsync.
 +
-Its a good idea to run replicate with `\--all` to ensure all
+Its a good idea to run replicate with `--all` to ensure all
 projects are consistent after the rsync is complete.
 
 * After deleting a ref by hand.
@@ -60,10 +60,10 @@ This command is intended to be used in scripts.
 
 OPTIONS
 -------
-\--all::
+--all::
 	Schedule replicating for all projects.
 
-\--url=<PATTERN>::
+--url <PATTERN>::
 	Replicate only to replication destinations whose URL
 	contains the substring <PATTERN>.  This can be useful to
 	replicate only to a previously down node, which has been
@@ -74,21 +74,21 @@ EXAMPLES
 Replicate every project, to every configured remote:
 
 ====
-	$ ssh -p 29418 review.example.com gerrit replicate --all
+  $ ssh -p 29418 review.example.com gerrit replicate --all
 ====
 
 Replicate only to `srv2` now that it is back online:
 
 ====
-	$ ssh -p 29418 review.example.com gerrit replicate --url=srv2 --all
+  $ ssh -p 29418 review.example.com gerrit replicate --url srv2 --all
 ====
 
 Replicate only the `tools/gerrit` project, after deleting a ref
 locally by hand:
 
 ====
-	$ git --git-dir=/home/git/tools/gerrit.git update-ref -d refs/changes/00/100/1
+  $ git --git-dir=/home/git/tools/gerrit.git update-ref -d refs/changes/00/100/1
-	$ ssh -p 29418 review.example.com gerrit replicate tools/gerrit
+  $ ssh -p 29418 review.example.com gerrit replicate tools/gerrit
 ====
 
 SEE ALSO

Documentation/cmd-review.txt

@@ -8,8 +8,13 @@ gerrit review - Verify, approve and/or submit one or more patch sets
 SYNOPSIS
 --------
 [verse]
-'ssh' -p <port> <host> 'gerrit approve' [\--project <PROJECT>] [\--message <MESSAGE>] [\--verified <N>] [\--code-review <N>] [\--abandon] [\--restore] [\--submit]  {COMMIT | CHANGEID,PATCHSET}...
+'ssh' -p <port> <host> 'gerrit review'
-'ssh' -p <port> <host> 'gerrit review' [\--project <PROJECT>] [\--message <MESSAGE>] [\--verified <N>] [\--code-review <N>] [\--abandon] [\--restore] [\--submit]  {COMMIT | CHANGEID,PATCHSET}...
+  [--project <PROJECT>]
+  [--message <MESSAGE>]
+  [--submit]
+  [--abandon | --restore]
+  [--verified <N>] [--code-review <N>]
+  {COMMIT | CHANGEID,PATCHSET}...
 
 DESCRIPTION
 -----------
@@ -19,7 +24,7 @@ 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
+--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
@@ -31,42 +36,42 @@ is strongly encouraged.
 OPTIONS
 -------
 
-\--project::
+--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::
+--message::
 -m::
 	Optional cover letter to include as part of the message
 	sent to reviewers when the approval states are updated.
 
-\--help::
+--help::
 -h::
 	Display site-specific usage information, including the
 	complete listing of supported approval categories and values.
 
-\--code-review::
+--abandon::
-\--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.
-
-\--abandon::
 	Abandon the specified patch set(s).
 	(option is mutually exclusive with --submit and --restore)
 
-\--restore::
+--restore::
 	Restore the specified abandonned patch set(s).
 	(option is mutually exclusive with --abandon)
 
-\--submit::
+--submit::
 -s::
 	Submit the specified patch set(s) for merging.
 	(option is mutually exclusive with --abandon)
 
+--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.
@@ -80,25 +85,25 @@ EXAMPLES
 
 Approve the change with commit c0ff33 as "Verified +1"
 =====
-	$ ssh -p 29418 review.example.com gerrit review --verified=+1 c0ff33
+	$ ssh -p 29418 review.example.com gerrit review --verified +1 c0ff33
 =====
 
 Append the message "Build Successful". Notice two levels of quoting is
 required, one for the local shell, and another for the argument parser
 inside the Gerrit server:
 =====
-	$ ssh -p 29418 review.example.com gerrit review -m '"Build Successful"'
+	$ ssh -p 29418 review.example.com gerrit review -m '"Build Successful"' c0ff33
 =====
 
 Mark the unmerged commits both "Verified +1" and "Code Review +2" and
 submit them for merging:
 ====
-	$ ssh -p 29418 review.example.com gerrit review \
+  $ ssh -p 29418 review.example.com gerrit review \
-	--verified=+1 \
+    --verified +1 \
-	--code-review=+2 \
+    --code-review +2 \
-	--submit \
+    --submit \
-	--project=this/project \
+    --project this/project \
-	$(git rev-list origin/master..HEAD)
+    $(git rev-list origin/master..HEAD)
 ====
 
 SEE ALSO

Documentation/cmd-set-project-parent.txt

@@ -8,9 +8,9 @@ gerrit set-project-parent - Change the project permissions are inherited from.
 SYNOPSIS
 --------
 [verse]
-'ssh' -p <port> <host> 'gerrit set-project-parent' \
+'ssh' -p <port> <host> 'gerrit set-project-parent'
-[\--parent <NAME>] \
+  [--parent <NAME>]
-<NAME> ...
+  <NAME> ...
 
 DESCRIPTION
 -----------
@@ -29,8 +29,8 @@ This command is intended to be used in scripts.
 
 OPTIONS
 -------
-\--parent::
+--parent::
-	Name of the parent to inherit through.	If not specified,
+	Name of the parent to inherit through. If not specified,
 	the parent is set back to the default `All-Projects`.
 
 EXAMPLES

Documentation/cmd-show-connections.txt

@@ -26,8 +26,8 @@ Intended for interactive use only.
 
 OPTIONS
 -------
+--numeric::
 -n::
-\--numeric::
 	Show client hostnames as IP addresses instead of DNS hostname.
 
 DISPLAY
@@ -35,7 +35,7 @@ DISPLAY
 
 Session::
 	Unique session identifier on this server.  Session
-	identifiers have a period of 2\^32-1 and start from a
+	identifiers have a period of 2^32-1 and start from a
 	random value.
 
 Start::

Documentation/cmd-show-queue.txt

@@ -8,8 +8,8 @@ gerrit show-queue - Display the background work queues, including replication
 SYNOPSIS
 --------
 [verse]
-'ssh' -p <port> <host> 'ps'
 'ssh' -p <port> <host> 'gerrit show-queue'
+'ssh' -p <port> <host> 'ps'
 
 DESCRIPTION
 -----------

Documentation/cmd-stream-events.txt

@@ -32,11 +32,11 @@ This command is intended to be used in scripts.
 EXAMPLES
 --------
 
------
+====
   $ ssh -p 29418 review.example.com gerrit stream-events
   {"type":"comment-added",change:{"project":"tools/gerrit", ...}, ...}
   {"type":"comment-added",change:{"project":"tools/gerrit", ...}, ...}
------
+====
 
 SCHEMA
 ------

Documentation/cmd-suexec.txt

@@ -8,28 +8,38 @@ suexec - Execute a command as any registered user account
 SYNOPSIS
 --------
 [verse]
-'ssh' -p <port> 'Gerrit Code Review'@localhost -i <private host key> 'suexec' \--as <EMAIL> [\--from HOST:PORT] [\--] [COMMAND]
+'ssh' -p <port>
+  -i SITE_PATH/etc/ssh_host_rsa_key
+  '"Gerrit Code Review@localhost"'
+  'suexec'
+  --as <EMAIL>
+  [--from HOST:PORT]
+  [--]
+  [COMMAND]
 
 DESCRIPTION
 -----------
-The suexec command can only be invoked by the magic user Gerrit Code Review
+The suexec command can only be invoked by the magic user `Gerrit
-and permits executing any other command as any other registered user account.
+Code Review` and permits executing any other command as any other
+registered user account.
 
 OPTIONS
 -------
 
-\--as::
+--as::
 	Email address of the user you want to impersonate.
-\--from::
+
-	Hostname and port of the machine you want to impersonate the command
+--from::
-	coming from.
+	Hostname and port of the machine you want to impersonate
+	the command coming from.
+
 COMMAND::
 	Gerrit command you want to run.
 
 ACCESS
 ------
-Caller must be the magic user Gerrit Code Review using the SSH daemon's host key
+Caller must be the magic user Gerrit Code Review using the SSH
-or a key on this daemon's peer host key ring.
+daemon's host key or a key on this daemon's peer host key ring.
 
 SCRIPTING
 ---------
@@ -40,9 +50,13 @@ EXAMPLES
 
 Approve the change with commit c0ff33 as "Verified +1" as user bob@example.com
 =====
-	$ sudo -u gerrit ssh -p 29418 -i site_path/etc/ssh_host_rsa_key \
+  $ sudo -u gerrit ssh -p 29418 \
-	'Gerrit Code Review'@localhost suexec --as bob@example.com -- \
+    -i site_path/etc/ssh_host_rsa_key \
-	gerrit approve --verified=+1 c0ff33
+    "Gerrit Code Review@localhost" \
+    suexec \
+    --as bob@example.com \
+    -- \
+    gerrit approve --verified +1 c0ff33
 =====
 
 GERRIT

gerrit-sshd/src/main/java/com/google/gerrit/sshd/commands/CreateProject.java

@@ -46,12 +46,12 @@ import org.eclipse.jgit.lib.PersonIdent;
 import org.eclipse.jgit.lib.RefUpdate;
 import org.eclipse.jgit.lib.Repository;
 import org.eclipse.jgit.lib.RefUpdate.Result;
+import org.kohsuke.args4j.Argument;
 import org.kohsuke.args4j.Option;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import java.io.IOException;
-import java.io.PrintWriter;
 import java.util.ArrayList;
 import java.util.HashSet;
 import java.util.List;
@@ -61,8 +61,14 @@ import java.util.Set;
 final class CreateProject extends BaseCommand {
   private static final Logger log = LoggerFactory.getLogger(CreateProject.class);
 
-  @Option(name = "--name", required = true, aliases = {"-n"}, metaVar = "NAME", usage = "name of project to be created")
+  @Option(name = "--name", aliases = {"-n"}, metaVar = "NAME", usage = "name of project to be created (deprecated option)")
-  private String projectName;
+  void setProjectNameFromOption(String name) {
+    if (projectName != null) {
+      throw new IllegalArgumentException("NAME already supplied");
+    } else {
+      projectName = name;
+    }
+  }
 
   @Option(name = "--owner", aliases = {"-o"}, usage = "owner(s) of project")
   private List<AccountGroup.UUID> ownerIds;
@@ -73,7 +79,7 @@ final class CreateProject extends BaseCommand {
   @Option(name = "--permissions-only", usage = "create project for use only as parent")
   private boolean permissionsOnly;
 
-  @Option(name = "--description", aliases = {"-d"}, metaVar = "DESC", usage = "description of project")
+  @Option(name = "--description", aliases = {"-d"}, metaVar = "DESCRIPTION", usage = "description of project")
   private String projectDescription = "";
 
   @Option(name = "--submit-type", aliases = {"-t"}, usage = "project submit type\n"
@@ -99,6 +105,16 @@ final class CreateProject extends BaseCommand {
   @Option(name = "--empty-commit", usage = "to create initial empty commit")
   private boolean createEmptyCommit;
 
+  private String projectName;
+  @Argument(index = 0, metaVar="NAME", usage="name of project to be created")
+  void setProjectNameFromArgument(String name) {
+    if (projectName != null) {
+      throw new IllegalArgumentException("--name already supplied");
+    } else {
+      projectName = name;
+    }
+  }
+
   @Inject
   private GitRepositoryManager repoManager;
 
@@ -242,6 +258,10 @@ final class CreateProject extends BaseCommand {
   }
 
   private void validateParameters() throws Failure {
+    if (projectName == null || projectName.isEmpty()) {
+      throw new Failure(1, "fatal: Argument NAME is required");
+    }
+
     if (projectName.endsWith(Constants.DOT_GIT_EXT)) {
       projectName = projectName.substring(0, //
           projectName.length() - Constants.DOT_GIT_EXT.length());