Documentation/intro-project-owner.txt

:linkattrs:
= Project Owner Guide

This is a Gerrit guide that is dedicated to project owners. It
explains the many possibilities that Gerrit provides to customize the
workflows for a project.

[[project-owner]]
== What is a project owner?

Being project owner means that you own a project in Gerrit.
Technically this is expressed by having the
link:access-control.html#category_owner[Owner] access right on
`+refs/*+` on that project. As project owner you have the permission to
edit the access control list and the project settings of the project.
It also means that you should get familiar with these settings so that
you can adapt them to the needs of your project.

Being project owner means being responsible for the administration of
a project. This requires having a deeper knowledge of Gerrit than the
average user. Normally per team there should be 2 to 3 persons, who
have a certain level of Git/Gerrit knowledge, assigned as project
owners. It normally doesn't make sense that everyone in a team is
project owner. For normal team members it is sufficient to be committer
or contributor.

[[access-rights]]
== Access Rights

As a project owner you can edit the access control list of your
project. This allows you to grant permissions on the project to
different groups.

Gerrit comes with a rich set of permissions which allow a very
fine-grained control over who can do what on a project. Access
control is one of the most powerful Gerrit features but it is also a
rather complex topic. This guide will only highlight the most
important aspects of access control, but the link:access-control.html[
Access Control] chapter explains all the details.

[[edit-access-rights]]
=== Editing Access Rights

To see the access rights of your project

- go to the Gerrit Web UI
- click on the `BROWSE` > `Repositories` menu entry
- find your project in the project list and click on it
- click on the `Access` menu entry

By clicking on the `Edit` button the access rights become editable and
you may save any changes by clicking on the `Save Changes` button.
Optionally you can provide a `Commit Message` to explain the reasons
for changing the access rights.

The access rights are stored in the project's Git repository in a
special branch called `refs/meta/config`. On this branch there is a
`project.config` file which contains the access rights. More
information about this storage format can be found in the
link:config-project-config.html[Project Configuration File Format]
chapter. What is important to know is that by looking at the history
of the `project.config` file on the `refs/meta/config` branch you can
always see how the access rights were changed and by whom. If a good
commit message is provided you can also see from the history why the
access rights were modified.

If a Git browser such as gitweb is configured for the Gerrit server you
can find a link to the history of the `project.config` file in the
Web UI. Otherwise you may inspect the history locally. If you have
cloned the repository you can do this by executing the following
commands:

----
  $ git fetch ssh://localhost:29418/project refs/meta/config
  $ git checkout FETCH_HEAD
  $ git log project.config
----

Non project owners may still edit the access rights and propose the
modifications to the project owners by clicking on the `Save for
Review` button. This creates a new change with the access rights
modifications that can be approved by a project owner. The project
owners are automatically added as reviewer on this change so that they
get informed about it by email.

[[inheritance]]
=== Inheritance

Normally when a new project is created in Gerrit it already has some
access rights which are inherited from the parent projects.
Projects in Gerrit are organized hierarchically as a tree with the
`All-Projects` project as root from which all projects inherit. Each
project can have only a single parent project, multi-inheritance is
not supported.

Looking at the access rights of your project in the Gerrit Web UI, you
only see the access rights which are defined on that project. To see
the inherited access rights you must follow the link to the parent
project under `Rights Inherit From`.

Inherited access rights can be overwritten unless they are defined as
link:access-control.html#block[BLOCK rule]. BLOCK rules are used to
limit the possibilities of the project owners on the inheriting
projects. With this, global policies can be enforced on all projects.
Please note that Gerrit doesn't prevent you from assigning access
rights that contradict an inherited BLOCK rule, but these access rights
will simply have no effect.

If you are responsible for several projects which require the same
permissions, it makes sense to have a common parent for them and to
maintain the access rights on that common parent. Changing the parent
of a project is only allowed for Gerrit administrators. This means you
need to contact the administrator of your Gerrit server if you want to
reparent your project. One way to do this is to change the parent
project in the Web UI, save the modifications for review and get the
change approved and merged by a Gerrit administrator.

[[refs]]
=== References

Access rights in Gerrit are assigned on references (aka refs). Refs in
Git exist in different namespaces, e.g. all branches normally exist
under `refs/heads/` and all tags under `refs/tags/`. In addition there
are a number of link:access-control.html#references_special[special refs]
and link:access-control.html#references_magic[magic refs].

Gerrit only supports tags that are reachable by any ref not owned by
Gerrit. This includes branches (refs/heads/\*) or custom ref namespaces
(refs/my-company/*). Tagging a change ref is not supported.
When filtering tags by visibility, Gerrit performs a reachability check
and will present the user ony with tags that are reachable by any ref
they can see.

Access rights can be assigned on a concrete ref, e.g.
`refs/heads/master` but also on ref patterns and regular expressions
for ref names.

A ref pattern ends with `+/*+` and describes a complete ref name
namespace, e.g. access rights assigned on `+refs/heads/*+` apply to all
branches.

Regular expressions must start with `^`, e.g. access rights assigned
on `+^refs/heads/rel-.*+` would apply to all `+rel-*+` branches.

[[groups]]
=== Groups

Access rights are granted to groups. It is useful to know that Gerrit
maintains its own groups internally but also supports different external
group backends.

The Gerrit internal groups can be seen in the Gerrit Web UI by clicking
on the `BROWSE` > `Groups` menu entry. By clicking on a group you can
edit the group members (`Members` tab) and the group options
(`General` tab).

Gerrit internal groups contain users as members, but can also include
other groups, even external groups.

Every group is owned by an owner group. Only members of the owner
group can administrate the owned group (assign members, edit the group
options). A group can own itself; in this case members of the group
can, for example, add further members to the group. When you create new
groups for your project to assign access rights to committer or other
roles, make sure that they are owned by the project owner group.

An important setting on a group is the option
`Make group visible to all registered users.`, which defines whether
non-members can see who is member of the group.

New internal Gerrit groups can be created under `BROWSE` > `Groups`
and then clicking on the `CREATE NEW` button in the upper right corner.
The `CREATE NEW` button is only available if you have the global
capability link:access-control.html#capability_createGroup[Create Group]
assigned.

Gerrit also has a set of special
link:access-control.html#system_groups[system groups] that you might
find useful.

External groups need to be prefixed when assigning access rights to
them, e.g. link:access-control.html#ldap_groups[LDAP group names] need
to be prefixed with `ldap/`.

If the link:https://gerrit-review.googlesource.com/admin/repos/plugins/singleusergroup[
singleusergroup,role=external,window=_blank] plugin is installed you can also directly assign
access rights to users, by prefixing the username with `user/` or the
user's account ID by `userid/`.

[[common-access-rights]]
=== Common Access Rights

Different roles in a project, such as developer (committer) or
contributor, need different access rights. Examples for which access
rights are typically assigned for which role are described in the
link:access-control.html#example_roles[Access Control] chapter.

[[code-review]]
=== Code Review

Gerrit's main functionality is code review, however using code review
is optional and you may decide to only use Gerrit as a Git server with
access control. Whether you allow only pushes for review or also
direct pushes depends on the project's access rights.

To push a commit for review it must be pushed to
link:access-control.html#refs_for[refs/for/<branch-name>]. This means
the link:access-control.html#category_push_review[Push] access right
must be assigned on `refs/for/<branch-name>`.

To allow direct pushes and bypass code review, the
link:access-control.html#category_push_direct[Push] access right is
required on `refs/heads/<branch-name>`.

By pushing for review you are not only enabling the review workflow,
but you can also get link:#continuous-integration[automatic
verifications from a build server] before changes are merged. In
addition you can benefit from Gerrit's merge strategies that can
automatically merge/rebase commits on server side if necessary. You can
control the merge strategy by configuring the
link:config-project-config.html#submit-type[submit type] on the project. If you
bypass code review you always need to merge/rebase manually if the tip
of the destination branch has moved. Please keep this in mind if you
choose to not work with code review because you think it's easier to
avoid the additional complexity of the review workflow; it might
actually not be easier.

You may also enable link:user-upload.html#auto_merge[auto-merge on
push] to benefit from the automatic merge/rebase on server side while
pushing directly into the repository.

[[project-options]]
== Project Options

As project owner you can control several options on your project.
The different options are described in the
link:project-configuration.html#project_options[Project Options] section.

To see the options of your project:

. Go to the Gerrit Web UI.
. Click on the `BROWSE` > `Repositories` menu entry.
. Find your project in the project list and click it.
. Click the `General` menu entry.

[[submit-type]]
=== Submit Type

An important decision for a project is the choice of the submit type
and the content merge setting (see the `Allow content merges` option).
The link:config-project-config.html#submit-type[submit type] is the method
Gerrit uses to submit a change to the project. The submit type defines
what Gerrit should do on submit of a change if the destination branch
has moved while the change was in review. The
link:project-configuration.html#content_merge[content merge] setting applies
if the same files have been modified concurrently and tells Gerrit
whether it should attempt a content merge for these files.

When choosing the submit type and the content merge setting one must
weigh development comfort against the safety of not breaking the
destination branch.

The most restrictive submit type is
link:project-configuration.html#fast_forward_only[Fast Forward Only]. Using
this submit type means that after submitting one change all other open
changes for the same destination branch must be rebased manually. This
is quite burdensome and in practice only feasible for branches with
very few changes. On the other hand, if changes are verified before
submit, e.g. automatically by a CI integration, with this submit type,
you can be sure that the destination branch never gets broken.

Choosing link:project-configuration.html#merge_if_necessary[Merge If Necessary]
as submit type makes the life for developers more comfortable,
especially if content merge is enabled. If this submit strategy is used
developers only need to rebase manually if the same files have been
modified concurrently or if the content merge on such a file fails. The
drawback with this submit type is that there is a risk of breaking
the destination branch, e.g. if one change moves a class into another
package and another change imports this class from the old location.
Experience shows that in practice `Merge If Necessary` with content
merge enabled works pretty well and breaking the destination branch
happens rarely. This is why this setting is recommended at least for
development branches. You likely want to start with
`Merge If Necessary` with content merge enabled and only switch to a
more restrictive policy if you are facing issues with the build and
test stability of the destination branches.

It is also possible to define the submit type dynamically via
link:#prolog-submit-type[Prolog]. This way you can use different submit
types for different branches.

Please note that there are other submit types available; they are
described in the link:config-project-config.html#submit-type[Submit Type]
section.

[[labels]]
== Labels

The code review process includes that reviewers formally express their
opinion about a change by voting on different link:config-labels.html[
labels]. By default Gerrit comes with the
link:config-labels.html#label_Code-Review[Code-Review] label and many
Gerrit servers have the link:config-labels.html#label_Verified[Verified]
label configured globally. However projects can also define their own
link:config-labels.html#label_custom[custom labels] to formalize
project-specific workflows. For example if a project requires an IP
approval from a special IP-team, it can define an `IP-Review` label
and grant permissions to the IP-team to vote on this label.

The behavior of a label can be controlled by its
link:config-labels.html#label_function[function], e.g. it can be
configured whether a max positive voting on the label is required for
submit or if the voting on the label is optional.

By using a custom link:#submit-rules[submit rule] it can be controlled
per change whether a label is required for submit or not.

A useful feature on labels is the possibility to automatically copy
scores forward to new patch sets if it was a
link:config-labels.html#trivial_rebase[trivial rebase] or if
link:config-labels.html#no_code_change[there was no code change] (e.g.
only the commit message was edited).

[[submit-rules]]
== Submit Rules

A link:prolog-cookbook.html#SubmitRule[submit rule] in Gerrit is logic
that defines when a change is submittable. By default, a change is
submittable when it gets at least one highest vote on each label and
has no lowest vote (aka veto vote) on any label.

The submit rules in Gerrit are implemented in link:prolog-cookbook.html[
Prolog] and projects that need more flexibility can define their own
submit rules to decide when a change should be submittable. A good
link:prolog-cookbook.html#NonAuthorCodeReview[example] from the Prolog
cookbook shows how to allow submit only if a change has a
`Code-Review+2` vote from a person that is not the change author. This
way a four-eyes principle for the reviews can be enforced.

A Prolog submit rule has access to link:prolog-change-facts.html[
information] about the change for which it is testing the
submittability. Among others the list of the modified files can be
accessed, which allows special logic if certain files are touched. For
example, a common practice is to require a vote on an additional label,
like `Library-Compliance`, if the dependencies of the project are
changed.

[[prolog-submit-type]]
It is also possible to control the link:prolog-cookbook.html#SubmitType[
submit type] from Prolog. For example this can be used to define a more
restrictive submit type such as `Fast Forward Only` for stable branches
while using a more liberal submit type, e.g. `Merge If Necessary` with
content merge, for development branches. How this can be done can be
seen from an link:prolog-cookbook.html#SubmitTypePerBranch[example] in
the Prolog cookbook.

Submit rules are maintained in the link:prolog-cookbook.html#RulesFile[
rules.pl] file in the `refs/meta/config` branch of the project. How to
write submit rules is explained in the
link:prolog-cookbook.html#HowToWriteSubmitRules[Prolog cookbook]. There
is also good support for link:prolog-cookbook.html#TestingSubmitRules[
testing submit rules] while developing them.

[[continuous-integration]]
== Continuous Integration

With Gerrit you can have continuous integration builds not only for
updates of central branches but also whenever a new change/patch set is
uploaded for review. This way you get automatic verification of all
changes *before* they are merged and any build and test issues are
detected early. To indicate the build and test status the continuous
integration system normally votes with the
link:config-labels.html#label_Verified[Verified] label on the change.

There are several solutions for integrating continuous integration
systems. The most commonly used are:

- link:https://plugins.jenkins.io/gerrit-trigger/[
  Gerrit Trigger,role=external,window=_blank] plugin for link:http://jenkins-ci.org/[Jenkins,role=external,window=_blank]

- link:http://www.mediawiki.org/wiki/Continuous_integration/Zuul[
  Zuul,role=external,window=_blank] for link:http://jenkins-ci.org/[Jenkins,role=external,window=_blank]

For the integration with the continuous integration system you must
have a service user that is able to access Gerrit. To create a service
user in Gerrit you can use the link:cmd-create-account.html[create-account]
SSH command if the link:access-control.html#capability_createAccount[
Create Account] global capability is granted. If not, you need to ask
a Gerrit administrator to create the service user.

If the link:https://gerrit-review.googlesource.com/admin/repos/plugins/serviceuser[
serviceuser,role=external,window=_blank] plugin is installed you can also create new service users
in the Gerrit Web UI under `People` > `Create Service User`. For this
the `Create Service User` global capability must be assigned.

The service user must have link:access-control.html#category_read[read]
access to your project. In addition, if automatic change verification
is enabled, the service user must be allowed to vote on the
link:config-labels.html#label_Verified[Verified] label.

Continuous integration systems usually integrate with Gerrit by
listening to the Gerrit link:cmd-stream-events.html#events[stream
events]. For this the service user must have the
link:access-control.html#capability_streamEvents[Stream Events] global
capability assigned.

[[commit-validation]]
== Commit Validation

Gerrit provides an
link:https://gerrit-review.googlesource.com/Documentation/config-validation.html#new-commit-validation[
extension point to do validation of new commits,role=external,window=_blank]. A Gerrit plugin
implementing this extension point can perform validation checks when
new commits are pushed to Gerrit. The plugin can either provide a
message to the client or reject the commit and cause the push to fail.

There are some plugins available that provide commit validation:

- link:https://gerrit-review.googlesource.com/admin/repos/plugins/uploadvalidator[
  uploadvalidator,role=external,window=_blank]:
+
The `uploadvalidator` plugin allows project owners to configure blocked
file extensions, required footers and a maximum allowed path length.

- link:https://gerrit-review.googlesource.com/admin/repos/plugins/commit-message-length-validator[
  commit-message-length-validator,role=external,window=_blank]
+
The `commit-message-length-validator` core plugin validates that commit
messages conform to line length limits.

[[branch-administration]]
== Branch Administration

As project owner you can administrate the branches of your project in
the Gerrit Web UI under `BROWSE` > `Repositories` > <your project> >
`Branches`. In the Web UI link:project-configuration.html#branch-creation[
branch creation] is allowed if you have
link:access-control.html#category_create[Create Reference] access right and
link:project-configuration.html#branch-deletion[branch deletion] is allowed if
you 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.

By setting `HEAD` on the project you can define its
link:project-configuration.html#default-branch[default branch]. For convenience
reasons, when the repository is cloned Git creates a local branch for
this default branch and checks it out.

[[notifications]]
== Email Notifications

With Gerrit individual users control their own email subscriptions. By
editing the link:user-notify.html#user[watched projects] in the Web UI
under `Settings` > `Notifications` users can decide which events to
be informed about by email. The change notifications can be filtered by
link:user-search.html[change search expressions].

This means as a project owner you normally don't need to do anything
about email notifications, except maybe telling your project team where
to configure the watches.

Gerrit also supports link:user-notify.html#project[notifications on
project level] that allow project owners to set up email notifications
for team mailing lists or groups of users. This configuration is done
in the `project.config` file in the `refs/meta/config` branch as
explained in the section about link:user-notify.html#project[project
level notifications].

[[dashboards]]
== Dashboards

Gerrit comes with a pre-defined user dashboard that provides a view
of the changes that are relevant for a user. Users can also define
their own link:user-dashboards.html[custom dashboards] where the
dashboard sections can be freely configured. As a project owner you can
configure such custom dashboards on
link:user-dashboards.html#project-dashboards[project level]. This way
you can define a view of the changes that are relevant for your
project and share this dashboard with all users. The project dashboards
can be seen in the Web UI under `BROWSE` > `Repositories` > <your project>
> `Dashboards`.

[[issue-tracker-integration]]
== Issue Tracker Integration

There are several possibilities to integrate issue trackers with
Gerrit.

- Comment Links
+
As described in the link:#comment-links[Comment Links] section, comment
links can be used to link IDs from commit message footers to issues in
an issue tracker system.

- Tracking IDs
+
Gerrit can be configured to index IDs from commit message footers so
that the link:user-search.html#tr[tr/bug] search operators can be used
to query for changes with a certain ID. The
link:config-gerrit.html#trackingid[configuration of tracking IDs] can
only be done globally by a Gerrit administrator.

- Issue Tracker System Plugins
+
There are Gerrit plugins for a tight integration with
link:https://gerrit-review.googlesource.com//admin/repos/plugins/its-jira[Jira,role=external,window=_blank],
link:https://gerrit-review.googlesource.com/admin/repos/plugins/its-bugzilla[Bugzilla,role=external,window=_blank] and
link:https://gerrit-review.googlesource.com/admin/repos/plugins/its-rtc[IBM Rational Team Concert,role=external,window=_blank].
If installed, these plugins can e.g. be used to automatically add links
to Gerrit changes to the issues in the issue tracker system or to
automatically close an issue if the corresponding change is merged.
If installed, project owners may enable/disable the issue tracker
integration from the Gerrit Web UI under `BROWSE` > `Repositories` >
<your project> > `General`.

[[comment-links]]
== Comment Links

Gerrit can linkify strings in commit messages, summary comments and
inline comments. A string that matches a defined regular expression is
then displayed as hyperlink to a configured backend system.

So called comment links can be configured globally by a Gerrit
administrator, but also per project by the project owner. Comment links
on project level are defined in the `project.config` file in the
`refs/meta/config` branch of the project as described in the
documentation of the link:config-gerrit.html#commentlink[commentlink]
configuration parameter.

Often comment links are used to link an ID in a commit message footer
to an issue in an issue tracker system. For example, to link the ID
from the `Bug` footer to Jira the following configuration can be used:

----
  [commentlink "myjira"]
    match = ([Bb][Uu][Gg]:\\s+)(\\S+)
    link =  https://myjira/browse/$2
----

[[reviewers]]
== Reviewers

Normally it is not needed to explicitly assign reviewers to every
change since the project members either link:user-notify.html#user[
watch the project] and get notified by email or regularly check the
list of open changes in the Gerrit Web UI. The project members then
pick the changes themselves that are interesting to them for review.

If authors of changes want to have a review by a particular person
(e.g. someone who is known to be expert in the touched code area, or a
stakeholder for the implemented feature), they can request the review
by adding this person in the Gerrit Web UI as a reviewer on the change.
Gerrit will then notify this person by email about the review request.

With the link:https://gerrit-review.googlesource.com/admin/repos/plugins/reviewers[
reviewers,role=external,window=_blank] plugin it is possible to configure default reviewers who
will be automatically added to each change. The default reviewers can
be configured in the Gerrit Web UI under `BROWSE` > `Repositories` >
<your project> > `General` in the `reviewers Plugin` section.

The link:https://gerrit-review.googlesource.com/admin/repos/plugins/reviewers-by-blame[
reviewers-by-blame,role=external,window=_blank] plugin can automatically add reviewers to changes
based on the link:https://www.kernel.org/pub/software/scm/git/docs/git-blame.html[
git blame,role=external,window=_blank] computation on the changed files. This means that the plugin
will add those users as reviewer that authored most of the lines
touched by the change, since these users should be familiar with the
code and can most likely review the change. How many reviewers the
plugin will add to a change at most can be configured in the Gerrit
Web UI under `BROWSE` > `Repositories` > <your project> > `General` in the
`reviewers-by-blame Plugin` section.

[[download-commands]]
== Download Commands

On the change screen in the `Downloads` drop-down panel Gerrit offers
commands for downloading the currently viewed patch set.

The download commands are implemented by Gerrit plugins. This means
that the available download commands depend on the installed Gerrit
plugins:

- link:https://gerrit-review.googlesource.com/admin/repos/plugins/download-commands[
  download-commands,role=external,window=_blank] plugin:
+
The `download-commands` plugin provides the default download commands
(`Checkout`, `Cherry Pick`, `Format Patch` and `Pull`).
+
Gerrit administrators may configure which of the commands are shown on
the change screen.

- link:https://gerrit-review.googlesource.com/admin/repos/plugins/project-download-commands[
  project-download-commands,role=external,window=_blank] plugin:
+
The `project-download-commands` plugin enables project owners to
configure project-specific download commands. For example, a
project-specific download command may update submodules, trigger a
build, execute the tests or even do a deployment.
+
The project-specific download commands must be configured in the
`project.config` file in the `refs/meta/config` branch of the project:
+
----
  [plugin "project-download-commands"]
    Build = git fetch ${url} ${ref} && git checkout FETCH_HEAD && bazel build ${project}
    Update = git fetch ${url} ${ref} && git checkout FETCH_HEAD && git submodule update
----
+
Project-specific download commands that are defined on a parent project
are inherited by the child projects. A child project can overwrite an
inherited download command, or remove it by assigning no value to it.

[[tool-integration]]
== Integration with other tools

Gerrit provides many possibilities for the integration with other
tools:

- Stream Events:
+
The link:cmd-stream-events.html[stream-events] SSH command allows to
listen to Gerrit link:cmd-stream-events.html#events[events]. Other
tools can use this to react on actions done in Gerrit.
+
The link:access-control.html#capability_streamEvents[Stream Events]
global capability is required for using the `stream-events` command.

- REST API:
+
Gerrit provides a rich link:rest-api.html[REST API] that other tools
can use to query information from Gerrit and and to trigger actions in
Gerrit.

- Gerrit Plugins:
+
The Gerrit functionality can be extended by plugins and there are many
extension points, e.g. plugins can
+
** link:pg-plugin-admin-api.html[add new menu entries]
** link:pg-plugin-endpoints.html[hook into DOM elements] and
   link:pg-plugin-dev.html#plugin-screen[add new pages]
** link:config-validation.html[do validation], e.g. of new commits
** add new REST endpoints and link:dev-plugins.html#ssh[SSH commands]

+
How to develop a Gerrit plugin is described in the link:dev-plugins.html[
Plugin Development] section.

[[project-lifecycle]]
== Project Lifecycle

[[project-creation]]
=== Project Creation

New projects can be created in the Gerrit Web UI under `BROWSE` >
`Repositories` and then clicking on the `CREATE NEW` button in the
upper right corner. The `CREATE NEW` button is only available if you
have the link:access-control.html#capability_createProject[
Create Project] global capability assigned.

Projects can also be created via REST or SSH as described in the
link:project-configuration.html#project-creation[Project Setup] section.

Creating the project with an initial empty commit is generally
recommended because some tools have issues with cloning repositories
that are completely empty. However, if you plan to link:#import-history[
import an existing history] into the new project, it is better to
create the project without an initial empty commit.

[[import-history]]
=== Import Existing History

If you have an existing history you can import it into a Gerrit
project. To do this you need to have a local Git repository that
contains this history. If your existing codebase is in another VCS you
must migrate it to Git first. For Subversion you can use the
link:http://git-scm.com/book/en/Git-and-Other-Systems-Git-and-Subversion[
git svn,role=external,window=_blank] command as described in the
link:http://git-scm.com/book/en/Git-and-Other-Systems-Migrating-to-Git#Subversion[
Subversion migration guide,role=external,window=_blank]. An importer for Perforce is available in
the `contrib` section of the Git source code; how to use
link:http://git-scm.com/docs/git-p4[git p4,role=external,window=_blank] to do the import from
Perforce is described in the
link:http://git-scm.com/book/en/Git-and-Other-Systems-Migrating-to-Git#Perforce[
Perforce migration guide,role=external,window=_blank].

To import an existing history into a Gerrit project you bypass code
review and push it directly to `refs/heads/<branch>`. For this you must
have the corresponding link:access-control.html#category_push_direct[
Push] access right assigned. If the destination branch in the Gerrit
repository already contains a history (e.g. an initial empty commit),
you can overwrite it by doing a force push. In this case force push
must be allowed in the access controls of the project.

Some Gerrit servers may disallow forging committers by blocking the
link:access-control.html#category_forge_committer[Forge Committer]
access right globally. In this case you must use the
link:https://www.kernel.org/pub/software/scm/git/docs/git-filter-branch.html[
git filter-branch,role=external,window=_blank] command to rewrite the committer information for all
commits (the author information that records who was writing the code
stays intact; signed tags will lose their signature):

----
  $ git filter-branch --tag-name-filter cat --env-filter 'GIT_COMMITTER_NAME="John Doe"; GIT_COMMITTER_EMAIL="john.doe@example.com";' -- --all
----

If a link:config-gerrit.html#receive.maxObjectSizeLimit[max object size
limit] is configured on the server you may need to remove large objects
from the history before you are able to push. To find large objects in
the history of your project you can use the `reposize.sh` script which
you can download from Gerrit:

----
  $ curl -Lo reposize.sh http://review.example.com:8080/tools/scripts/reposize.sh

or

  $ scp -p -P 29418 john.doe@review.example.com:scripts/reposize.sh .
----

You can then use the
link:https://www.kernel.org/pub/software/scm/git/docs/git-filter-branch.html[
git filter-branch] command to remove the large objects from the history
of all branches:

----
  $ git filter-branch -f --index-filter 'git rm --cached --ignore-unmatch path/to/large-file.jar' -- --all
----

Since this command rewrites all commits in the repository it's a good
idea to create a fresh clone from this rewritten repository before
pushing to Gerrit, this will ensure that the original objects which
have been rewritten are removed.

[[project-deletion]]
=== Project Deletion

Gerrit core does not support the deletion of projects.

If the link:https://gerrit-review.googlesource.com/admin/repos/plugins/delete-project[
delete-project,role=external,window=_blank] plugin is installed, projects can be deleted from the
Gerrit Web UI under `BROWSE` > `Repositories` > <project> > `General` by
clicking on the `Delete` command under `Project Commands`. The `Delete`
command is only available if you have the `Delete Projects` global
capability assigned, or if you own the project and you have the
`Delete Own Projects` global capability assigned. If neither of these
capabilities is granted, you need to contact a Gerrit administrator to
request the deletion of your project.

Instead of deleting a project you may set the
link:project-configuration.html#project-state[project state] to `ReadOnly` or
`Hidden`.

[[project-rename]]
=== Project Rename

Gerrit core does not support the renaming of projects.

If the link:https://gerrit-review.googlesource.com/admin/repos/plugins/rename-project[rename-project]
plugin is installed, projects can be renamed using the
link:https://gerrit.googlesource.com/plugins/rename-project/+/refs/heads/master/src/main/resources/Documentation/cmd-rename.md[rename-project]
ssh command.

Find details about prerequisites in the
link:https://gerrit.googlesource.com/plugins/rename-project/+/refs/heads/master/src/main/resources/Documentation/about.md[plugin documentation].

If you don't want to use the rename-project plugin you can perform the following steps as
a workaround:

. link:#project-creation[Create a new project] with the new name.
. link:#import-history[Import the history of the old project].
. link:#project-deletion[Delete the old project].

Please note that a drawback of this workaround is that the whole review
history (changes, review comments) is lost.

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

SEARCHBOX
---------