opendev/gerrit
Code Issues Proposed changes
4b1ff15c1a
gerrit/Documentation/cmd-create-project.txt
Luca Milanesio d12c6b4a72 Align SSH create-project with REST API 
The way REST API and SSH command manage the creation of the project
is on paper aligned: they both should accept either owner group name or
UUID.

Align the way group UUID is parsed with its REST API counterpart so
that SSH and REST commands would do the same thing with the same
parameters.

Before this change, a create-project over SSH with a user:username UUID
failed while it was successful as REST API.

Bug: Issue 8389
Change-Id: Ieb04f758ea17fe30bbdae0f801c1b45e2afc0847
2018-03-10 01:01:35 +00:00

224 lines
7.2 KiB
Plaintext
Raw Blame History

= gerrit create-project
== NAME
gerrit create-project - Create a new hosted project
== SYNOPSIS
[verse]
--
_ssh_ -p <port> <host> _gerrit create-project_
[--owner <GROUP> ... | -o <GROUP> ...]
[--parent <NAME> | -p <NAME> ]
[--suggest-parents | -S ]
[--permissions-only]
[--description <DESC> | -d <DESC>]
[--submit-type <TYPE> | -t <TYPE>]
[--use-contributor-agreements | --ca]
[--use-signed-off-by | --so]
[--use-content-merge]
[--create-new-change-for-all-not-in-target]
[--require-change-id | --id]
[[--branch <REF> | -b <REF>] ...]
[--empty-commit]
[--max-object-size-limit <N>]
[--plugin-config <PARAM> ...]
{ <NAME> }
--
== DESCRIPTION
Creates a new bare Git repository under `gerrit.basePath`, using
the project name supplied. The newly created repository is empty
(has no commits), but is registered in the Gerrit database so that
the initial commit may be uploaded for review, or initial content
can be pushed directly into a branch.
If replication is enabled, this command also connects to each of
the configured remote systems over SSH and uses command line git
on the remote system to create the empty repository.
== ACCESS
Caller must be a member of the privileged 'Administrators' group,
or have been granted
link:access-control.html#capability_createProject[the 'Create Project' global capability].
== SCRIPTING
This command is intended to be used in scripts.
== OPTIONS
<NAME>::
Required; name of the new project to create. If name ends
with `.git` the suffix will be automatically removed.
--branch::
-b::
Name of the initial branch(es) in the newly created project.
Several branches can be specified on the command line.
If several branches are specified then the first one becomes HEAD
of the project. If none branches are specified then default value
('master') is used.
--owner::
-o::
Identifier of the group(s) which will initially own this repository.
This can be:
* the UUID of the group
* the legacy numeric ID of the group
* the name of the group if it is unique
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`
in gerrit.config.
--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`.
--suggest-parents::
-S::
Suggest parent candidates. This option cannot be used with
other arguments. Print out a list of projects that are
already parents to other projects, thus it can help the user
find a suitable parent for the new project.
--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::
-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'"`.
--submit-type::
-t::
Action used by Gerrit to submit an approved change to its
destination branch. Supported options are:
+
* FAST_FORWARD_ONLY: produces a strictly linear history.
* MERGE_IF_NECESSARY: create a merge commit when required.
* REBASE_IF_NECESSARY: rebase the commit when required.
* REBASE_ALWAYS: always rebase the commit including dependencies.
* MERGE_ALWAYS: always create a merge commit.
* CHERRY_PICK: always cherry-pick the commit.
+
Defaults to MERGE_IF_NECESSARY unless
link:config-gerrit.html#repository.name.defaultSubmitType[
repository.<name>.defaultSubmitType] is set to a different value.
For more details see link:project-configuration.html#submit_type[
Submit Types].
--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::
--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::
--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.
--create-new-change-for-all-not-in-target::
--ncfa:
If enabled, a new change is created for every commit that is not in
the target branch. If the pushed commit is a merge commit, this flag is
ignored for that push. To avoid accidental creation of a large number
of open changes, this option also does not accept merge commits in the
commit chain.
Disabled by default.
--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.
--max-object-size-limit::
Define maximum Git object size for this project. Pushes containing an
object larger than this limit will be rejected. This can be used to
further limit the global
link:config-gerrit.html#receive.maxObjectSizeLimit[receive.maxObjectSizeLimit]
and cannot be used to increase that globally set limit.
+
Common unit suffixes of 'k', 'm', or 'g' are supported.
--plugin-config::
A plugin configuration parameter that should be set for this
project. The plugin configuration parameter must be specified in
the format '<plugin-name>.<parameter-name>=<value>'. Only
parameters that are explicitly declared by a plugin can be set.
Multiple `--plugin-config` options can be specified to set multiple
plugin parameters.
== EXAMPLES
Create a new project called `tools/gerrit`:
----
$ 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 tool.git --description "'Tools used by build system'"
----
Note that it is necessary to quote the description twice. The local
shell needs double quotes around the value to ensure the single quotes
are passed through SSH as-is to the remote Gerrit server, which uses
the single quotes to delimit the value.
== REPLICATION
If the replication plugin is installed, the plugin will attempt to
perform remote repository creation by a Bourne shell script:
----
mkdir -p '/base/project.git' && cd '/base/project.git' && git init --bare && git update-ref HEAD refs/heads/master
----
For this to work successfully the remote system must be able to run
arbitrary shell scripts, and must have `git` in the user's PATH
environment variable. Administrators could also run this command line
by hand to establish a new empty repository.
A custom extension or plugin may also be developed to implement the
NewProjectCreatedListener extension point and handle custom logic
for remote repository creation.
== SEE ALSO
* link:project-configuration.html[Project Configuration]
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------
View Git Blame Copy Permalink