Gerrit2 - Project Configuration
===============================

All Git repositories under `site_path` must be registered in the
Gerrit database in order to be accessed through SSH, or through
the web interface.

Create Git Repository
---------------------

Create a Git repository under `git_base_path`:

====
  git --git-dir=$git_base_pathgit/new/project.git init
====

[TIP]
By tradition the project name should have a `.git` suffix.

To also make this repository available over the anonymous git://
protocol, don't forget the git-daemon-export-ok file:

====
  touch $git_base_pathgit/new/project.git/git-daemon-export-ok
====

Register Project
----------------

At least two inserts are needed to register a project with Gerrit:
one to define the project exists, and another to define a branch
that changes can be uploaded to.  Additional branches may be
defined if desired.

[NOTE]
Note that the `.git` suffix is not typically included in the
project name, as it looks cleaner in the web when not shown.
Gerrit automatically assumes that `project.git` is the Git repository
for a project named `project`.

====
  psql reviewdb
  INSERT INTO projects
  (project_id
   ,use_contributor_agreements
   ,submit_type
   ,owner_group_id
   ,name)
  VALUES
  (nextval('project_id')
  ,'Y'
  ,'M'
  ,(SELECT admin_group_id FROM system_config)
  ,'new/project');

  INSERT INTO branches
  (branch_id
  ,branch_name
  ,project_name)
  VALUES
  (nextval('branch_id')
  ,'refs/heads/master'
  ,'new/project');
====

Change Submit Action
--------------------

The method Gerrit uses to submit a change to a project can be
modified by any project owner through the project console, `Admin` >
`Projects`.  The following methods are supported:

* Fast Forward Only
+
This method produces a strictly linear history.  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 (and why `\'M'` is suggested
above in the insert statement).
+
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 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
+
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.


Registering Additional Branches
-------------------------------

Branches can be created over the SSH port by any `git push` client,
if the user has been granted the `Push Branch` > `Create Branch`
(or higher) access right.

Additional branches can also be created through the web UI, assuming
at least one commit already exists in the project repository.
A project owner can create additional branches under `Admin` >
`Projects` > `Branches`.  Enter the new branch name, and the
starting Git revision.  Branch names that don't start with `refs/`
will automatically have `refs/heads/` prefixed to ensure they are
a standard Git branch name.  Almost any valid SHA-1 expression can
be used to specify the starting revision, so long as it resolves
to a commit object.  Abbreviated SHA-1s are not supported.