Documentation/project-configuration.txt

= Gerrit Code Review - Project Configuration

[[project-creation]]
== Project Creation

There are several ways to create a new project in Gerrit:

- in the Web UI under 'Projects' > 'Create Project'
- via the link:rest-api-projects.html#create-project[Create Project]
  REST endpoint
- via the link:cmd-create-project.html[create-project] SSH command

To be able to create new projects the global capability
link:access-control.html#capability_createProject[Create Project] must
be granted.

In addition, projects can be created link:#manual_project_creation[
manually].

[[manual_project_creation]]
=== Manual Project Creation

. Create a Git repository under `gerrit.basePath`:
+
----
  git --git-dir=$base_path/new/project.git init
----
+
[TIP]
By tradition the repository directory name should have a `.git`
suffix.
+
To also make this repository available over the anonymous git://
protocol, don't forget to create a `git-daemon-export-ok` file:
+
----
  touch $base_path/new/project.git/git-daemon-export-ok
----

. Register Project
+
Either restart the server, or flush the `project_list` cache:
+
----
  ssh -p 29418 localhost gerrit flush-caches --cache project_list
----

[[project_options]]
== Project Options

[[submit_type]]
=== Submit Type

See details at link:config-project-config.html#submit-type[submit type].

[[project-state]]
=== State

See details at link:config-project-config.html#project-section[project section].


=== Use target branch when determining new changes to open

The `create-new-change-for-all-not-in-target` option provides a
convenience for selecting link:user-upload.html#base[the merge base]
by setting it automatically to the target branch's tip so you can
create new changes for all commits not in the target branch.

This option is disabled if the tip of the push is a merge commit.

This option also only works if there are no merge commits in the
commit chain, in such cases it fails warning the user that such
pushes can only be performed by manually specifying
link:user-upload.html#base[bases]

This option is useful if you want to push a change to your personal
branch first and for review to another branch for example. Or in cases
where a commit is already merged into a branch and you want to create
a new open change for that commit on another branch.

[[require-change-id]]
=== Require Change-Id

The `Require Change-Id in commit message` option defines whether a
link:user-changeid.html[Change-Id] in the commit message is required
for pushing a commit for review. If this option is set, trying to push
a commit for review that doesn't contain a Change-Id in the commit
message fails with link:error-missing-changeid.html[missing Change-Id
in commit message footer].

It is recommended to set this option and use a
link:user-changeid.html#create[commit-msg hook] (or other client side
tooling like EGit) to automatically generate Change-Id's for new
commits. This way the Change-Id is automatically in place when changes
are reworked or rebased and uploading new patch sets gets easy.

If this option is not set, commits can be uploaded without a Change-Id,
but then users have to remember to copy the assigned Change-Id from the
change screen and insert it manually into the commit message when they
want to upload a second patch set.

=== Maximum Git Object Size Limit

This option defines the maximum allowed Git object size that
receive-pack will accept. If an object is larger than the given size
the pack-parsing will abort and the push operation will fail.

With this option users can be prevented from uploading commits that
contain files which are too large.

Normally the link:config-gerrit.html#receive.maxObjectSizeLimit[maximum
Git object size limit] is configured globally for a Gerrit server. At
the project level, the maximum Git object size limit can be further
reduced, but not extended. The displayed effective limit shows the
maximum Git object size limit that is actually used on the project.

The defined maximum Git object size limit is inherited by any child
project.

[[require-signed-off-by]]
=== Require Signed-off-by

The `Require Signed-off-by in commit message` option defines whether a
link:user-signedoffby.html[Signed-off-by] line in the commit message is
required for pushing a commit. If this option is set, trying to push a
commit that doesn't contain a Signed-off-by line in the commit message
fails with link:error-not-signed-off-by.html[not Signed-off-by
author/committer/uploader in commit message footer].

[[branch-admin]]
== Branch Administration

[[branch-creation]]
=== Branch Creation

There are several ways to create a new branch in a project:

- in the Web UI under 'Projects' > 'List' > <project> > 'Branches'
- via the link:rest-api-projects.html#create-branch[Create Branch]
  REST endpoint
- via the link:cmd-create-branch.html[create-branch] SSH command
- by using a git client to push a commit to a non-existing branch

To be able to create new branches the user must have the
link:access-control.html#category_create[Create Reference] access
right.

When using the Web UI, the REST endpoint or the SSH command it is only
possible to create branches on commits that already exist in the
repository.

If a branch name does not start with `refs/` it is automatically
prefixed with `refs/heads/`.

The starting revision for a new branch can be any valid SHA-1
expression, as long as it resolves to a commit. Abbreviated SHA-1s
are not supported.

[[branch-deletion]]
=== Branch Deletion

There are several ways to delete a branch:

- in the Web UI under 'Projects' > 'List' > <project> > 'Branches'
- via the link:rest-api-projects.html#delete-branch[Delete Branch]
  REST endpoint
- by using a git client
+
----
  $ git push origin --delete refs/heads/<branch-to-delete>
----
+
another method, by force pushing nothing to an existing branch:
+
----
  $ git push --force origin :refs/heads/<branch-to-delete>
----

To be able to delete branches, the user must have the
link:access-control.html#category_delete[Delete Reference] or the
link:access-control.html#category_push[Push] access right with the
`force` option.

[[default-branch]]
=== Default Branch

The default branch of a remote repository is defined by its `HEAD`.
For convenience reasons, when the repository is cloned Git creates a
local branch for this default branch and checks it out.

Project owners can set `HEAD`

- in the Web UI under 'Projects' > 'List' > <project> > 'Branches' or
- via the link:rest-api-projects.html#set-head[Set HEAD] REST endpoint


GERRIT
------
Part of link:index.html[Gerrit Code Review]

SEARCHBOX
---------