Documentation/project-setup.txt

Gerrit Code Review - Project Configuration
==========================================

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

Create Through SSH
------------------

Creating a new repository over SSH is perhaps the easiest way to
configure a new project:

====
  ssh -p 29418 review.example.com gerrit create-project --name new/project
====

See link:cmd-create-project.html[gerrit create-project] for more
details.


Manual Creation
---------------

Projects may also be manually registered with the database.

Create Git Repository
~~~~~~~~~~~~~~~~~~~~~

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

One insert is needed to register a project with Gerrit.

[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`.

====
  INSERT INTO projects
  (use_contributor_agreements
   ,submit_type
   ,name)
  VALUES
  ('N'
  ,'M'
  ,'new/project');
====

[[submit_type]]
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.
+
Note that Gerrit ignores patch set dependencies when operating in
cherry-pick mode. Submitters must remember to submit changes in
the right order since inter-change dependencies will not be
enforced for them.


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.

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