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
diff --git a/Documentation/cmd-cherry-pick.txt b/Documentation/cmd-cherry-pick.txt
index 0831d9d..568c872 100644
--- a/Documentation/cmd-cherry-pick.txt
+++ b/Documentation/cmd-cherry-pick.txt
@@ -9,10 +9,8 @@
--------
[verse]
'gerrit-cherry-pick' <remote> <changeid>...
-
-'gerrit-cherry-pick' \--continue | \--skip | \--abort
-
-'gerrit-cherry-pick' \--close <remote>
+'gerrit-cherry-pick' --continue | --skip | --abort
+'gerrit-cherry-pick' --close <remote>
DESCRIPTION
-----------
@@ -22,13 +20,13 @@
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 @@
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
------
diff --git a/Documentation/cmd-create-account.txt b/Documentation/cmd-create-account.txt
index ab5663c..ba6a03d 100644
--- a/Documentation/cmd-create-account.txt
+++ b/Documentation/cmd-create-account.txt
@@ -8,12 +8,12 @@
SYNOPSIS
--------
[verse]
-'ssh' -p <port> <host> 'gerrit create-account' \
-[\--group <GROUP>] \
-[\--full-name <FULLNAME>] \
-[\--email <EMAIL>] \
-[\--ssh-key -|<KEY>] \
-<USERNAME>
+'ssh' -p <port> <host> 'gerrit create-account'
+ [--group <GROUP>]
+ [--full-name <FULLNAME>]
+ [--email <EMAIL>]
+ [--ssh-key - | <KEY>]
+ <USERNAME>
DESCRIPTION
-----------
@@ -38,23 +38,23 @@
<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::
- Name of the group to put the user into. Multiple \--group
+--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
diff --git a/Documentation/cmd-create-group.txt b/Documentation/cmd-create-group.txt
index 1e46e14..d2f76ef 100644
--- a/Documentation/cmd-create-group.txt
+++ b/Documentation/cmd-create-group.txt
@@ -8,12 +8,12 @@
SYNOPSIS
--------
[verse]
-'ssh' -p <port> <host> 'gerrit create-group' \
-[\--owner <GROUP>] \
-[\--description <DESC>] \
-[\--member <USERNAME>] \
-[\--group <GROUP>] \
-<GROUP>
+'ssh' -p <port> <host> 'gerrit create-group'
+ [--owner <GROUP>]
+ [--description <DESC>]
+ [--member <USERNAME>]
+ [--group <GROUP>]
+ <GROUP>
DESCRIPTION
-----------
@@ -37,22 +37,22 @@
<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
-`\--description "\'A description string\'"`.
+('). This most likely requires double quoting the value, for example
+`--description "'A description string'"`.
-\--member::
- User name to become initial member of the group. Multiple \--member
+--member::
+ User name to become initial member of the group. Multiple --member
options may be specified to add more initial members.
-\--group::
- Group name to include in the group. Multiple \--group options may
+--group::
+ Group name to include in the group. Multiple --group options may
be specified to include more initial groups.
EXAMPLES
diff --git a/Documentation/cmd-create-project.txt b/Documentation/cmd-create-project.txt
index 180542a..2716038 100644
--- a/Documentation/cmd-create-project.txt
+++ b/Documentation/cmd-create-project.txt
@@ -8,18 +8,19 @@
SYNOPSIS
--------
[verse]
- 'ssh' -p <port> <host> 'gerrit create-project' \
- --name <NAME> \
- [--branch <REF>] \
- [\--owner <GROUP> ...] \
- [\--parent <NAME>] \
- [\--permissions-only] \
- [\--description <DESC>] \
- [\--submit-type <TYPE>] \
- [\--use-content-merge] \
- [\--use-contributor-agreements] \
- [\--use-signed-off-by] \
- [\--empty-commit]
+'ssh' -p <port> <host> 'gerrit create-project'
+ [--owner <GROUP> ... | -o <GROUP> ...]
+ [--parent <NAME> | -p <NAME> ]
+ [--permissions-only]
+ [--description <DESC> | -d <DESC>]
+ [--submit-type <TYPE> | -t <TYPE>]
+ [--use-contributor-agreements | --ca]
+ [--use-signed-off-by | --so]
+ [--use-content-merge]
+ [--require-change-id | --id]
+ [--branch <REF> | -b <REF>]
+ [--empty-commit]
+ { <NAME> | --name <NAME> }
DESCRIPTION
-----------
@@ -37,7 +38,7 @@
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 @@
OPTIONS
-------
-\--name::
- Required; name of the project to create. If name ends with
- `.git` the suffix will be automatically removed.
+<NAME>::
+ Required; name of the new project to create. If name ends
+ 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
-`\--description "\'A description string\'"`.
+('). This most likely requires double quoting the value, for example
+`--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 @@
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 @@
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
diff --git a/Documentation/cmd-flush-caches.txt b/Documentation/cmd-flush-caches.txt
index 573cd78..9b5bab8 100644
--- a/Documentation/cmd-flush-caches.txt
+++ b/Documentation/cmd-flush-caches.txt
@@ -8,8 +8,9 @@
SYNOPSIS
--------
[verse]
- 'ssh' -p <port> <host> 'gerrit flush-caches' \
- [\--all | \--list | \--cache <NAME> ...]
+'ssh' -p <port> <host> 'gerrit flush-caches' --all
+'ssh' -p <port> <host> 'gerrit flush-caches' --list
+'ssh' -p <port> <host> 'gerrit flush-caches' --cache <NAME> ...
DESCRIPTION
-----------
@@ -32,19 +33,19 @@
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.
diff --git a/Documentation/cmd-gsql.txt b/Documentation/cmd-gsql.txt
index 7fc8a9b..3c4f1b5 100644
--- a/Documentation/cmd-gsql.txt
+++ b/Documentation/cmd-gsql.txt
@@ -8,9 +8,9 @@
SYNOPSIS
--------
[verse]
- 'ssh' -p <port> <host> 'gerrit gsql' \
- [\--format \{PRETTY | JSON\}] \
- [\-c QUERY]
+'ssh' -p <port> <host> 'gerrit gsql'
+ [--format {PRETTY | JSON}]
+ [-c QUERY]
DESCRIPTION
-----------
@@ -20,7 +20,7 @@
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.
diff --git a/Documentation/cmd-hook-commit-msg.txt b/Documentation/cmd-hook-commit-msg.txt
index b21f5c0..3b06b06 100644
--- a/Documentation/cmd-hook-commit-msg.txt
+++ b/Documentation/cmd-hook-commit-msg.txt
@@ -56,9 +56,11 @@
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
--------
diff --git a/Documentation/cmd-index.txt b/Documentation/cmd-index.txt
index 8a6cb6d3..4f579bd 100644
--- a/Documentation/cmd-index.txt
+++ b/Documentation/cmd-index.txt
@@ -51,6 +51,24 @@
[[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 @@
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-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-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.
diff --git a/Documentation/cmd-ls-projects.txt b/Documentation/cmd-ls-projects.txt
index de8d5b5..0332c69 100644
--- a/Documentation/cmd-ls-projects.txt
+++ b/Documentation/cmd-ls-projects.txt
@@ -8,10 +8,10 @@
SYNOPSIS
--------
[verse]
- 'ssh' -p <port> <host> 'gerrit ls-projects'
- [--show-branch <BRANCH1> ...]
- [--tree]
- [--type {code | permissions | all}]
+'ssh' -p <port> <host> 'gerrit ls-projects'
+ [--show-branch <BRANCH> ...]
+ [--tree]
+ [--type {code | permissions | all}]
DESCRIPTION
-----------
@@ -31,27 +31,30 @@
OPTIONS
-------
-\--show-branch::
-\-b::
+--show-branch::
+-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::
-\-t::
+--tree::
+-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
- types are `code` (any project likely to contain user files),
- `permissions` (projects created with the --permissions-only
- flag), `all` (any type of project). If not specified,
- defaults to `code`.
+ Display only projects of the specified type. If not
+ specified, defaults to `code`. Supported types:
++
+--
+`code`:: Any project likely to contain user files.
+`permissions`:: Projects created with the `--permissions-only` flag.
+`all`:: Any type of project.
+--
EXAMPLES
--------
diff --git a/Documentation/cmd-query.txt b/Documentation/cmd-query.txt
index c8996eb..bdbe3e4 100644
--- a/Documentation/cmd-query.txt
+++ b/Documentation/cmd-query.txt
@@ -8,14 +8,14 @@
SYNOPSIS
--------
[verse]
- 'ssh' -p <port> <host> 'gerrit query' \
- [\--format {TEXT | JSON}] \
- [\--current-patch-set] \
- [\--patch-sets|--all-approvals] \
- [\--] \
- <query> \
- [limit:<n>] \
- [resume\_sortkey:<sortKey>]
+'ssh' -p <port> <host> 'gerrit query'
+ [--format {TEXT | JSON}]
+ [--current-patch-set]
+ [--patch-sets | --all-approvals]
+ [--]
+ <query>
+ [limit:<n>]
+ [resume_sortkey:<sortKey>]
DESCRIPTION
-----------
@@ -39,18 +39,23 @@
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 @@
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 @@
--------
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
diff --git a/Documentation/cmd-receive-pack.txt b/Documentation/cmd-receive-pack.txt
index ca96550..7e5ca09 100644
--- a/Documentation/cmd-receive-pack.txt
+++ b/Documentation/cmd-receive-pack.txt
@@ -8,7 +8,7 @@
SYNOPSIS
--------
[verse]
-git receive-pack [\--reviewer <address>] [\--cc <address>] <project>
+'git receive-pack' [--reviewer <address>] [--cc <address>] <project>
DESCRIPTION
-----------
@@ -24,11 +24,11 @@
<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 @@
+
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 @@
====
afterwards `.git/config` contains the following:
-====
- [remote "charlie"]
- url = ssh://review.example.com:29418/project
- push = HEAD:refs/for/master
- receivepack = git receive-pack --reviewer charlie@example.com --cc alice@example.com --cc bob@example.com
-====
+----
+[remote "charlie"]
+ url = ssh://review.example.com:29418/project
+ push = HEAD:refs/for/master
+ 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:
diff --git a/Documentation/cmd-replicate.txt b/Documentation/cmd-replicate.txt
index 7f88b47..02d8883 100644
--- a/Documentation/cmd-replicate.txt
+++ b/Documentation/cmd-replicate.txt
@@ -8,9 +8,9 @@
SYNOPSIS
--------
[verse]
-'ssh' -p <port> <host> 'gerrit replicate' \
-[\--url <PATTERN>] \
-\{\--all | <PROJECT> ...}
+'ssh' -p <port> <host> 'gerrit replicate'
+ [--url <PATTERN>]
+ {--all | <PROJECT> ...}
DESCRIPTION
-----------
@@ -32,13 +32,13 @@
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 @@
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 @@
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
- $ ssh -p 29418 review.example.com gerrit replicate tools/gerrit
+ $ 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
====
SEE ALSO
diff --git a/Documentation/cmd-review.txt b/Documentation/cmd-review.txt
index 5645f51..4c87c26 100644
--- a/Documentation/cmd-review.txt
+++ b/Documentation/cmd-review.txt
@@ -8,8 +8,13 @@
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' [\--project <PROJECT>] [\--message <MESSAGE>] [\--verified <N>] [\--code-review <N>] [\--abandon] [\--restore] [\--submit] {COMMIT | CHANGEID,PATCHSET}...
+'ssh' -p <port> <host> 'gerrit review'
+ [--project <PROJECT>]
+ [--message <MESSAGE>]
+ [--submit]
+ [--abandon | --restore]
+ [--verified <N>] [--code-review <N>]
+ {COMMIT | CHANGEID,PATCHSET}...
DESCRIPTION
-----------
@@ -19,7 +24,7 @@
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 @@
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::
-\--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::
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 @@
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 \
- --verified=+1 \
- --code-review=+2 \
- --submit \
- --project=this/project \
- $(git rev-list origin/master..HEAD)
+ $ ssh -p 29418 review.example.com gerrit review \
+ --verified +1 \
+ --code-review +2 \
+ --submit \
+ --project this/project \
+ $(git rev-list origin/master..HEAD)
====
SEE ALSO
diff --git a/Documentation/cmd-set-project-parent.txt b/Documentation/cmd-set-project-parent.txt
index 9e62c1c..9dd11d7 100644
--- a/Documentation/cmd-set-project-parent.txt
+++ b/Documentation/cmd-set-project-parent.txt
@@ -8,9 +8,9 @@
SYNOPSIS
--------
[verse]
-'ssh' -p <port> <host> 'gerrit set-project-parent' \
-[\--parent <NAME>] \
-<NAME> ...
+'ssh' -p <port> <host> 'gerrit set-project-parent'
+ [--parent <NAME>]
+ <NAME> ...
DESCRIPTION
-----------
@@ -29,8 +29,8 @@
OPTIONS
-------
-\--parent::
- Name of the parent to inherit through. If not specified,
+--parent::
+ Name of the parent to inherit through. If not specified,
the parent is set back to the default `All-Projects`.
EXAMPLES
diff --git a/Documentation/cmd-show-connections.txt b/Documentation/cmd-show-connections.txt
index 177a915..ad8dbfb 100644
--- a/Documentation/cmd-show-connections.txt
+++ b/Documentation/cmd-show-connections.txt
@@ -26,8 +26,8 @@
OPTIONS
-------
+--numeric::
-n::
-\--numeric::
Show client hostnames as IP addresses instead of DNS hostname.
DISPLAY
@@ -35,7 +35,7 @@
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::
diff --git a/Documentation/cmd-show-queue.txt b/Documentation/cmd-show-queue.txt
index 3e3638e..947cfb0 100644
--- a/Documentation/cmd-show-queue.txt
+++ b/Documentation/cmd-show-queue.txt
@@ -8,8 +8,8 @@
SYNOPSIS
--------
[verse]
-'ssh' -p <port> <host> 'ps'
'ssh' -p <port> <host> 'gerrit show-queue'
+'ssh' -p <port> <host> 'ps'
DESCRIPTION
-----------
diff --git a/Documentation/cmd-stream-events.txt b/Documentation/cmd-stream-events.txt
index fb54f67..bd23baa 100644
--- a/Documentation/cmd-stream-events.txt
+++ b/Documentation/cmd-stream-events.txt
@@ -32,11 +32,11 @@
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
------
diff --git a/Documentation/cmd-suexec.txt b/Documentation/cmd-suexec.txt
index 98a66ad..baffd53 100644
--- a/Documentation/cmd-suexec.txt
+++ b/Documentation/cmd-suexec.txt
@@ -8,28 +8,38 @@
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
-and permits executing any other command as any other registered user account.
+The suexec command can only be invoked by the magic user `Gerrit
+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
- coming from.
+
+--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
-or a key on this daemon's peer host key ring.
+Caller must be the magic user Gerrit Code Review using the SSH
+daemon's host key or a key on this daemon's peer host key ring.
SCRIPTING
---------
@@ -40,9 +50,13 @@
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 \
- 'Gerrit Code Review'@localhost suexec --as bob@example.com -- \
- gerrit approve --verified=+1 c0ff33
+ $ sudo -u gerrit ssh -p 29418 \
+ -i site_path/etc/ssh_host_rsa_key \
+ "Gerrit Code Review@localhost" \
+ suexec \
+ --as bob@example.com \
+ -- \
+ gerrit approve --verified +1 c0ff33
=====
GERRIT
diff --git a/gerrit-sshd/src/main/java/com/google/gerrit/sshd/commands/CreateProject.java b/gerrit-sshd/src/main/java/com/google/gerrit/sshd/commands/CreateProject.java
index 4496cf2..51b8eec 100644
--- a/gerrit-sshd/src/main/java/com/google/gerrit/sshd/commands/CreateProject.java
+++ b/gerrit-sshd/src/main/java/com/google/gerrit/sshd/commands/CreateProject.java
@@ -46,12 +46,12 @@
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 @@
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")
- private String projectName;
+ @Option(name = "--name", aliases = {"-n"}, metaVar = "NAME", usage = "name of project to be created (deprecated option)")
+ 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 @@
@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 @@
@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 @@
}
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());
