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

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

[[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`.
The default branch is selected from the initial branches of the newly created project,
or set to link:config-gerrit.html#gerrit.defaultBranch[host-level default],
if the project was created with empty branches.
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
---------