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

The method Gerrit uses to submit a change to a project can be
modified by any project owner through the project console, `Projects` >
`List` > my/project. In general, a submitted change is only merged if all
its dependencies are also submitted, with exceptions documented below.
The following submit types are supported:

[[fast_forward_only]]
* Fast Forward Only
+
With this method Gerrit does not create merge commits on submitting a
change. Merge commits may still be submitted, but they must be created
on the client prior to uploading to Gerrit for review.
+
To submit a change, the change must be a strict superset of the
destination branch.  That is, the change must already contain the
tip of the destination branch at submit time.

[[merge_if_necessary]]
* Merge If Necessary
+
This is the default for new projects, unless overridden by a global
link:config-gerrit.html#repository.name.defaultSubmitType[`defaultSubmitType` option].
+
If the change being submitted is a strict superset of the destination
branch, then the branch is fast-forwarded to the change.  If not,
then a merge commit is automatically created.  This is identical
to the classical `git merge` behavior, or `git merge --ff`.

[[always_merge]]
* Always Merge
+
Always produce a merge commit, even if the change is a strict
superset of the destination branch.  This is identical to the
behavior of `git merge --no-ff`, and may be useful if the
project needs to follow submits with `git log --first-parent`.

[[cherry_pick]]
* Cherry Pick
+
Always cherry pick the patch set, ignoring the parent lineage
and instead creating a brand new commit on top of the current
branch head.
+
When cherry picking a change, Gerrit automatically appends onto the
end of the commit message a short summary of the change's approvals,
and a URL link back to the change on the web.  The committer header
is also set to the submitter, while the author header retains the
original patch set author.
+
Note that Gerrit ignores dependencies between changes when using this
submit type unless
link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`]
is enabled and depending changes share the same topic. So generally
submitters must remember to submit changes in the right order when using this
submit type. If all you want is extra information in the commit message,
consider using the Rebase Always submit strategy.

[[rebase_if_necessary]]
* Rebase If Necessary
+
If the change being submitted is a strict superset of the destination
branch, then the branch is fast-forwarded to the change.  If not,
then the change is automatically rebased and then the branch is
fast-forwarded to the change.
+
When Gerrit tries to do a merge, by default the merge will only
succeed if there is no path conflict.  A path conflict occurs when
the same file has also been changed on the other side of the merge.

[[rebase_always]]
* Rebase Always
+
Basically, the same as Rebase If Necessary, but it creates a new patchset even
if fast forward is possible AND like Cherry Pick it ensures footers such as
Change-Id, Reviewed-On, and others are present in resulting commit that is
merged.
+
Thus, Rebase Always can be considered similar to Cherry Pick, but with
the important distinction that Rebase Always does not ignore dependencies.

[[content_merge]]
=== Allow content merges

If `Allow content merges` is enabled, Gerrit will try
to do a content merge when a path conflict occurs.

[[project-state]]
=== State

This setting defines the state of the project. A project can have the
following states:

- `Active`:
+
The project is active and users can see and modify the project according
to their access rights on the project.

- `Read Only`:
+
The project is read only and all modifying operations on it are
disabled. E.g. this means that pushing to this project fails for all
users even if they have push permissions assigned on it.
+
Setting a project to this state is an easy way to temporary close a
project, as you can keep all write access rights in place and they will
become active again as soon as the project state is set back to
`Active`.
+
This state also makes sense if a project was moved to another location.
In this case all new development should happen in the new project and
you want to prevent that somebody accidentally works on the old
project, while keeping the old project around for old references.

- `Hidden`:
+
The project is hidden and only visible to project owners. Other users
are not able to see the project even if they have read permissions
granted on the project.

=== 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
---------