Documentation/cmd-create-project.txt

= 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), and the initial content may either be uploaded for
review, or pushed directly to 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
	link:project-configuration.html#default-branch[HEAD] of the project.
	If none branches are specified then link:config-gerrit.html#gerrit.defaultBranch[host-level default]
	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:config-project-config.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
---------