From 477692458caf7feea1ce5066a5813397562a00e8 Mon Sep 17 00:00:00 2001 From: "Shawn O. Pearce" Date: Tue, 14 Jun 2011 16:40:48 -0700 Subject: [PATCH] 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 | 12 +-- Documentation/cmd-create-account.txt | 26 +++--- Documentation/cmd-create-group.txt | 28 +++---- Documentation/cmd-create-project.txt | 83 ++++++++++++------- Documentation/cmd-flush-caches.txt | 15 ++-- Documentation/cmd-gsql.txt | 8 +- Documentation/cmd-hook-commit-msg.txt | 2 + Documentation/cmd-index.txt | 42 +++++----- Documentation/cmd-ls-projects.txt | 33 ++++---- Documentation/cmd-query.txt | 41 +++++---- Documentation/cmd-receive-pack.txt | 24 +++--- Documentation/cmd-replicate.txt | 22 ++--- Documentation/cmd-review.txt | 53 ++++++------ Documentation/cmd-set-project-parent.txt | 10 +-- Documentation/cmd-show-connections.txt | 4 +- Documentation/cmd-show-queue.txt | 2 +- Documentation/cmd-stream-events.txt | 4 +- Documentation/cmd-suexec.txt | 38 ++++++--- .../gerrit/sshd/commands/CreateProject.java | 28 ++++++- 19 files changed, 272 insertions(+), 203 deletions(-) diff --git a/Documentation/cmd-cherry-pick.txt b/Documentation/cmd-cherry-pick.txt index 0831d9d7a9..568c8729d6 100644 --- a/Documentation/cmd-cherry-pick.txt +++ b/Documentation/cmd-cherry-pick.txt @@ -9,10 +9,8 @@ SYNOPSIS -------- [verse] 'gerrit-cherry-pick' ... - -'gerrit-cherry-pick' \--continue | \--skip | \--abort - -'gerrit-cherry-pick' \--close +'gerrit-cherry-pick' --continue | --skip | --abort +'gerrit-cherry-pick' --close 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 ------ diff --git a/Documentation/cmd-create-account.txt b/Documentation/cmd-create-account.txt index ab5663c512..ba6a03ddb0 100644 --- a/Documentation/cmd-create-account.txt +++ b/Documentation/cmd-create-account.txt @@ -8,12 +8,12 @@ gerrit create-account - Create a new batch/role account. SYNOPSIS -------- [verse] -'ssh' -p 'gerrit create-account' \ -[\--group ] \ -[\--full-name ] \ -[\--email ] \ -[\--ssh-key -|] \ - +'ssh' -p 'gerrit create-account' + [--group ] + [--full-name ] + [--email ] + [--ssh-key - | ] + DESCRIPTION ----------- @@ -38,23 +38,23 @@ OPTIONS :: 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 1e46e14e19..d2f76efa07 100644 --- a/Documentation/cmd-create-group.txt +++ b/Documentation/cmd-create-group.txt @@ -8,12 +8,12 @@ gerrit create-group - Create a new account group. SYNOPSIS -------- [verse] -'ssh' -p 'gerrit create-group' \ -[\--owner ] \ -[\--description ] \ -[\--member ] \ -[\--group ] \ - +'ssh' -p 'gerrit create-group' + [--owner ] + [--description ] + [--member ] + [--group ] + DESCRIPTION ----------- @@ -37,22 +37,22 @@ OPTIONS :: 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 180542a771..2716038571 100644 --- a/Documentation/cmd-create-project.txt +++ b/Documentation/cmd-create-project.txt @@ -8,18 +8,19 @@ gerrit create-project - Create a new hosted project SYNOPSIS -------- [verse] - 'ssh' -p 'gerrit create-project' \ - --name \ - [--branch ] \ - [\--owner ...] \ - [\--parent ] \ - [\--permissions-only] \ - [\--description ] \ - [\--submit-type ] \ - [\--use-content-merge] \ - [\--use-contributor-agreements] \ - [\--use-signed-off-by] \ - [\--empty-commit] +'ssh' -p 'gerrit create-project' + [--owner ... | -o ...] + [--parent | -p ] + [--permissions-only] + [--description | -d ] + [--submit-type | -t ] + [--use-contributor-agreements | --ca] + [--use-signed-off-by | --so] + [--use-content-merge] + [--require-change-id | --id] + [--branch | -b ] + [--empty-commit] + { | --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:: - Required; name of the project to create. If name ends with - `.git` the suffix will be automatically removed. +:: + 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 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 @@ 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 diff --git a/Documentation/cmd-flush-caches.txt b/Documentation/cmd-flush-caches.txt index 573cd78936..9b5bab8024 100644 --- a/Documentation/cmd-flush-caches.txt +++ b/Documentation/cmd-flush-caches.txt @@ -8,8 +8,9 @@ gerrit flush-caches - Flush some/all server caches from memory SYNOPSIS -------- [verse] - 'ssh' -p 'gerrit flush-caches' \ - [\--all | \--list | \--cache ...] +'ssh' -p 'gerrit flush-caches' --all +'ssh' -p 'gerrit flush-caches' --list +'ssh' -p 'gerrit flush-caches' --cache ... 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=:: +--cache :: Flush only the cache called . 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 7fc8a9bfcd..3c4f1b52df 100644 --- a/Documentation/cmd-gsql.txt +++ b/Documentation/cmd-gsql.txt @@ -8,9 +8,9 @@ gerrit gsql - Administrative interface to active database SYNOPSIS -------- [verse] - 'ssh' -p 'gerrit gsql' \ - [\--format \{PRETTY | JSON\}] \ - [\-c QUERY] +'ssh' -p 'gerrit gsql' + [--format {PRETTY | JSON}] + [-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. diff --git a/Documentation/cmd-hook-commit-msg.txt b/Documentation/cmd-hook-commit-msg.txt index b21f5c0ea8..3b06b06ef6 100644 --- a/Documentation/cmd-hook-commit-msg.txt +++ b/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 -------- diff --git a/Documentation/cmd-index.txt b/Documentation/cmd-index.txt index 8a6cb6d3bc..4f579bd81e 100644 --- a/Documentation/cmd-index.txt +++ b/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. diff --git a/Documentation/cmd-ls-projects.txt b/Documentation/cmd-ls-projects.txt index de8d5b5b2a..0332c69ed9 100644 --- a/Documentation/cmd-ls-projects.txt +++ b/Documentation/cmd-ls-projects.txt @@ -8,10 +8,10 @@ gerrit ls-projects - List projects visible to caller SYNOPSIS -------- [verse] - 'ssh' -p 'gerrit ls-projects' - [--show-branch ...] - [--tree] - [--type {code | permissions | all}] +'ssh' -p 'gerrit ls-projects' + [--show-branch ...] + [--tree] + [--type {code | permissions | all}] DESCRIPTION ----------- @@ -31,27 +31,30 @@ This command is intended to be used in scripts. 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 c8996ebd24..bdbe3e4505 100644 --- a/Documentation/cmd-query.txt +++ b/Documentation/cmd-query.txt @@ -8,14 +8,14 @@ gerrit query - Query the change database SYNOPSIS -------- [verse] - 'ssh' -p 'gerrit query' \ - [\--format {TEXT | JSON}] \ - [\--current-patch-set] \ - [\--patch-sets|--all-approvals] \ - [\--] \ - \ - [limit:] \ - [resume\_sortkey:] +'ssh' -p 'gerrit query' + [--format {TEXT | JSON}] + [--current-patch-set] + [--patch-sets | --all-approvals] + [--] + + [limit:] + [resume_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::: @@ -59,7 +64,7 @@ limit::: than one limit: operator is provided, the smallest limit will be used to cut the result set. -resume\_sortkey::: +resume_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 diff --git a/Documentation/cmd-receive-pack.txt b/Documentation/cmd-receive-pack.txt index ca965508dd..7e5ca09b2e 100644 --- a/Documentation/cmd-receive-pack.txt +++ b/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
] [\--cc
] +'git receive-pack' [--reviewer
] [--cc
] DESCRIPTION ----------- @@ -24,11 +24,11 @@ OPTIONS :: 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
:: -\--reviewer
:: +--reviewer
:: +--re
:: Automatically add
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
:: +--cc
:: Carbon-copy
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"] - 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 7f88b47c0c..02d8883cef 100644 --- a/Documentation/cmd-replicate.txt +++ b/Documentation/cmd-replicate.txt @@ -8,9 +8,9 @@ gerrit replicate - Manually trigger replication, to recover a node SYNOPSIS -------- [verse] -'ssh' -p 'gerrit replicate' \ -[\--url ] \ -\{\--all | ...} +'ssh' -p 'gerrit replicate' + [--url ] + {--all | ...} 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=:: +--url :: Replicate only to replication destinations whose URL contains the substring . 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 - $ 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 5645f5137f..4c87c26b9e 100644 --- a/Documentation/cmd-review.txt +++ b/Documentation/cmd-review.txt @@ -8,8 +8,13 @@ gerrit review - Verify, approve and/or submit one or more patch sets SYNOPSIS -------- [verse] -'ssh' -p 'gerrit approve' [\--project ] [\--message ] [\--verified ] [\--code-review ] [\--abandon] [\--restore] [\--submit] {COMMIT | CHANGEID,PATCHSET}... -'ssh' -p 'gerrit review' [\--project ] [\--message ] [\--verified ] [\--code-review ] [\--abandon] [\--restore] [\--submit] {COMMIT | CHANGEID,PATCHSET}... +'ssh' -p 'gerrit review' + [--project ] + [--message ] + [--submit] + [--abandon | --restore] + [--verified ] [--code-review ] + {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:: -\--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 @@ 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 \ - --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 9e62c1cdd3..9dd11d7d3c 100644 --- a/Documentation/cmd-set-project-parent.txt +++ b/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 'gerrit set-project-parent' \ -[\--parent ] \ - ... +'ssh' -p 'gerrit set-project-parent' + [--parent ] + ... DESCRIPTION ----------- @@ -29,8 +29,8 @@ This command is intended to be used in scripts. 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 177a915124..ad8dbfb6b8 100644 --- a/Documentation/cmd-show-connections.txt +++ b/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:: diff --git a/Documentation/cmd-show-queue.txt b/Documentation/cmd-show-queue.txt index 3e3638e48e..947cfb0fcc 100644 --- a/Documentation/cmd-show-queue.txt +++ b/Documentation/cmd-show-queue.txt @@ -8,8 +8,8 @@ gerrit show-queue - Display the background work queues, including replication SYNOPSIS -------- [verse] -'ssh' -p 'ps' 'ssh' -p 'gerrit show-queue' +'ssh' -p 'ps' DESCRIPTION ----------- diff --git a/Documentation/cmd-stream-events.txt b/Documentation/cmd-stream-events.txt index fb54f67edb..bd23baa186 100644 --- a/Documentation/cmd-stream-events.txt +++ b/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 ------ diff --git a/Documentation/cmd-suexec.txt b/Documentation/cmd-suexec.txt index 98a66ad33b..baffd536e8 100644 --- a/Documentation/cmd-suexec.txt +++ b/Documentation/cmd-suexec.txt @@ -8,28 +8,38 @@ suexec - Execute a command as any registered user account SYNOPSIS -------- [verse] -'ssh' -p 'Gerrit Code Review'@localhost -i 'suexec' \--as [\--from HOST:PORT] [\--] [COMMAND] +'ssh' -p + -i SITE_PATH/etc/ssh_host_rsa_key + '"Gerrit Code Review@localhost"' + 'suexec' + --as + [--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 @@ 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 \ - '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 4496cf2254..51b8eec950 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.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") - 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 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());