There are several ways to create a new project in Gerrit:
To be able to create new projects the global capability Create Project must be granted.
In addition, projects can be created manually.
Manual Project Creation
Create a Git repository under
git --git-dir=$base_path/new/project.git initTip
By tradition the repository directory name should have a
To also make this repository available over the anonymous git:// protocol, don’t forget to create a
Either restart the server, or flush the
ssh -p 29418 localhost gerrit flush-caches --cache project_list
The method Gerrit uses to submit a change to a project can be
modified by any project owner through the project console,
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
With this method no merge commits are produced. All merges must be handled 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
This is the default for a new project.
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 mergebehavior, or
git merge --ff.
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.
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
change.submitWholeTopicis 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.
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.
Allow content merges is enabled, Gerrit will try
to do a content merge when a path conflict occurs.
This setting defines the state of the project. A project can have the following states:
The project is active and users can see and modify the project according to their access rights on the project.
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
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.
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
create-new-change-for-all-not-in-target option provides a
convenience for selecting 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 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 in commit message option defines whether a
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 missing Change-Id
in commit message footer.
It is recommended to set this option and use a 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 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 in commit message option defines whether a
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 not Signed-off-by
author/committer/uploader in commit message footer.
There are several ways to create a new branch in a project:
To be able to create new branches the user must have the
Create Reference access
right. In addition, project owners and Gerrit administrators can create
new branches from the Web UI or via REST even without having the
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
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.
There are several ways to delete a branch:
in the Web UI under 'Projects' > 'List' > <project> > 'Branches'
via the Delete Branch REST endpoint
by using a git client to force push 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
Push access right with the
force option. In addition, project owners and Gerrit administrators
can delete branches from the Web UI or via REST even without having the
Force Push access right.
The default branch of a remote repository is defined by its
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
in the Web UI under 'Projects' > 'List' > <project> > 'Branches' or
via the Set HEAD REST endpoint
Part of Gerrit Code Review