.. _repositories:

=====================
Managing Repositories
=====================

Review Board supports talking to multiple source code repositories of various
types. A single Review Board server can be configured with nearly an unlimited
number of repositories, making it useful in large projects and companies as
well as small. These are managed in the
:ref:`Administration UI <administration-ui>` through either the
:ref:`database section <database-management>` or the
:ref:`administrator-dashboard`.

A repository can be linked up with a supported hosting service. This provides
a fast and easy way to configure a repository without having to figure out
specific paths. See :ref:`hosting-services` for more information.

.. _adding-repositories:

Adding Repositories
===================

In order for Review Board to talk to a source code repository, it must first
know how to access it.

To add a new repository, click the :guilabel:`Add` link next to the
:guilabel:`Repositories` entry in the
:ref:`database section <database-management>` or the
:ref:`administrator-dashboard`.

A form will appear with fields split into the following sections:

* `General Information`_
* `Repository Hosting`_
* `Bug Tracker`_
* `Advanced`_


General Information
-------------------

* **Name** (required)
    This is the human-readable name of the repository that users will see.
    The name can be whatever you like and will appear on the "New Review
    Request" page and in the review request's displayed information.

* **Show this repository** (optional)
    Determines whether or not the repository will be show. If this is
    unchecked, then users won't see the repository in Review Board or
    through third-party applications that talk to Review Board.

    This is most often used for hiding a repository that's no longer in use.


Repository Hosting
------------------

This is a complete list of fields that can be shown in this section. Not all
of them will actually be shown at once. The fields will depend on the
selected `Hosting service`_ and `Repository type`_.

.. _`Hosting service`:

* **Hosting service** (required)
    The source code hosting service this repository will use, if any. This
    will be one of the following:

    * :guilabel:`Bitbucket` - The Bitbucket_ Mercurial hosting service.
    * :guilabel:`GitHub` - A public account at GitHub_.
    * :guilabel:`GitHub (Private)` - A private account at GitHub_.
    * :guilabel:`Google Code` - An open source Subversion or Mercurial
      project at `Google Code`_.
    * :guilabel:`SourceForge` - An open source project on SourceForge_.
    * :guilabel:`Custom` - A custom-hosted repository. This should be used
      if one of the above isn't appropriate.

    See :ref:`hosting-services` for more information.

.. _`Repository type`:

* **Repository type** (required)
    This is the type of the repository. This will depend on the
    `Hosting service`_ selected.

.. _`Project's owner`:

* **Project's owner** (required)
    The user that owns the project on the hosting service. This is used
    for hosting services that closely associate a project with an owner.

    This is only shown for Bitbucket_ and GitHub_.

* **Project's name** (required)
    The name of the project on the hosting service. This is different from
    the repository's name.

    This is only shown when `Hosting service`_ is not set to
    :guilabel:`Custom`.

* **API token** (required)
    The API token provided by the hosting service. This is needed in order
    to access files on the repository. You will need to look at your account
    settings on the hosting service to determine the proper API token to use.

    This is only shown when `Hosting service`_ is not set to
    :guilabel:`GitHub (Private)`.

.. _`Path field`:

* **Path** (required)
    This is the path to the repository on the server. It must be accessible
    by the server running Review Board. The value depends on the repository
    type. See :ref:`determining-repository-information` below for more
    information.

    This is only shown when `Hosting service`_ is set to :guilabel:`Custom`.

.. _`Mirror path field`:

* **Mirror Path** (optional)
    This is an alternate path for the repository that is used during
    lookups. It's usually used when there's separate developer and anonymous
    URLs for the repository, with the anonymous URL entered in
    :guilabel:`Path` and the developer URL entered in :guilabel:`Mirror Path`.
    Review Board will always use the main path when looking up files.

    This is only shown when `Hosting service`_ is set to :guilabel:`Custom`.

    See :ref:`determining-repository-information` below for more
    information on the URLs.

.. _`Raw file URL mask`:

* **Raw file URL mask** (optional)
    The raw file URL mask is a path to a raw file blob on a cgit or Gitweb
    server with special tags that will be substituted to build a real URL to a
    file in the repository. This field is needed when using Review Board with
    a remote Git repository.

    For example:

    * **cgit**:
      ``http://git.gnome.org/browse/gtk+/plain/<filename>?id2=<revision>``
    * **Gitweb**:
      ``http://git.kernel.org/?p=bluetooth/bluez-gnome.git;a=blob_plain;f=<filename>;hb=<revision>``

    This is only shown when `Hosting service`_ is set to :guilabel:`Custom`
    and `Repository type`_ is set to :guilabel:`Git`.

    See :ref:`raw-file-urls` below for more information.

.. _`Username and Password fields`:
.. _`Username field`:

* **Username** and **Password** (optional)
    Some repositories will require a username and password for access,
    some require only a username, and some don't require either and instead
    allow for anonymous access.

    Subversion repositories, for example, generally provide anonymous access,
    while CVS and Perforce generally require a username but not a password.

    The administrator of the repository should know what is required. This
    varies depending on the setup.

    This may or may not be shown depending on `Hosting service`_ and
    `Repository type`_.


Bug Tracker
-----------

In most projects, there's a bug tracker associated with the repository
or project, and review requests will often reference bugs.

Review Board will automatically link any bugs to the bug tracker
associated with the repository if this field is provided.


* **Use hosting service's bug tracker** (optional)
   If checked, and if the selected `Hosting service`_ has a built-in
   bug tracker, then that bug tracker will be used for this repository.

   If unchecked, a bug tracker can be specified below.

* **Type** (optional)
    The value of the field should be the path of a ticket, except with
    ``%s`` substituted for the ticket name.

    For example:
      * **Bugzilla**:
        ``http://bugzilla.example.com/show_bug.cgi?id=%s``
      * **Google Code**:
        ``http://code.google.com/p/myproject/issues/detail?id=%s``
      * **Trac**:
        ``http://trac.example.com/ticket/%s``

    If you don't use a bug tracker with projects in this repository, this
    field can be left blank.


Advanced
--------

* **Encoding** (optional)
    In some cases there's confusion as to the proper encoding to expect from
    files in a repository. You can set this to the proper encoding type (such
    as utf-8) if you need to, but generally you don't want to touch this field
    if things are working fine. You can leave this blank.

When done, click :guilabel:`Save` to create the repository entry.


.. _editing-repositories:

Editing Repositories
====================

In the event that you need to change the information on a repository (for
example, if the repository path or the bug tracker URL has changed), you can
edit your repository information by clicking :guilabel:`Repositories` in the
:ref:`administrator-dashboard` or
:ref:`Database section <database-management>` of the
:ref:`Administration UI <administration-ui>`.

See :ref:`adding-repositories` for a description of each field.

When done, click :guilabel:`Save` to save your changes.


Deleting Repositories
=====================

To delete a repository, follow the instructions in
:ref:`editing-repositories` to find the repository you want to get rid of.
Then click :guilabel:`Delete` at the bottom of the page.

.. warning::

   Deleting a repository will delete any and all review requests, reviews,
   diffs, or other data associated with it. You should never delete a
   repository that has been previously used, unless the server is really
   dead and gone with no replacement (in which case review requests won't be
   able to grab the diff information anyway).


.. _hosting-services:

Hosting Services
================

Review Board can be easily configured to work with different hosting
services. This is a convenient method for specifying the repository paths
and other information necessary to talk to the particular repository.

By changing the `Hosting service`_ field, the list of repository types
(Subversion, Git, etc.) will be limited to the list that the hosting
service supports. The list of fields you need to fill out will also change.

As of Review Board 1.5, the following hosting services are supported:

* Bitbucket_
* GitHub_ (public and private repositories)
* `Google Code`_
* SourceForge_

More may be added in future releases based on demand.

If you're using a custom code repository, whether hosted on a private server
or on some other hosting provider, you can set `Hosting service`_ to
:guilabel:`Custom` and fill out the information manually. This is equivalent
to configuring a repository in Review Board 1.0.x.

If you have an existing repository from Review Board 1.0.x using one of the
supported hosting services, the form should detect which hosting service
you're using and display it. This will depend on what values were entered
for the `Path field`_ and `Mirror Path field`_.

.. _Bitbucket: http://bitbucket.org/
.. _GitHub: http://github.com/
.. _`Google Code`: http://code.google.com/hosting/
.. _SourceForge: http://sourceforge.net/


.. _determining-repository-information:

Determining Repository Information
==================================

The `Path field`_ for a repository is very dependent on the type of repository
you're configuring. This section provides some help for determining which
value to use.


ClearCase
---------

Review Board currently works with local ClearCase dynamic views, by utilizing
version-extended paths to access specific file revisions.

The `Path field`_ should point to the top of the very top of the view, which
will be either a drive letter on Windows, or a mount point on Unix.

The `Username and Password fields`_ should be blank.


CVS
---

Review Board supports several methods of connecting to a CVS server. In
particular, the following connection types can be used:

* ``:ext:``
* ``:fork:``
* ``:gserver:``
* ``:kgserver:``
* ``:local:``
* ``:pserver:``
* ``:server:``

If you use one of these connection types and provide it for the `Path field`_,
you won't need to fill in the `Username and Password fields`_.

If you use ``:pserver:``, you can instead provide a Path of the form
``hostname:port/path`` and then specify the username and password in the
appropriate fields.

Some example of valid paths include:

* ``cvs.example.com/cvsroot``
* ``:pserver:anonymous@cvs.example.com/cvsroot``
* ``:pserver:myuser:mypass@cvs.example.com:1234/cvsroot``
* ``:local:C:\CVSROOTS\myproject``


To determine the path of an existing checkout, you can go to the top-most
directory of the checkout and type::

    $ cat CVS/Root

You should use the contents of this file as the repository path, adjusting the
username, password or path as necessary.


Git
---

In order to use Git with Review Board, you'll need either a local clone
on the server, or by using raw file URLs to a web front-end to Git (cgit,
Gitweb, etc.) on the Git server. Git doesn't have a way of fetching an
individual file of a given revision from a remote server without having an
entire clone, so it works differently from other repository types.


Local Clone
~~~~~~~~~~~

In order to work with Review Board, a local clone needs to be kept in
sync regularly. It should either have direct access to a central Git
server, or it needs to be updated on every commit to the central Git
server.

The `Path field`_ should be the full path of the ``.git`` directory inside
this checkout.  For example: ``/var/git/projectname/.git``

The `Mirror path field`_ should contain the repository URL.  Find the URL you
should use from within a git checkout by running the following::

    $ git remote show origin

The value shown as ``URL:`` should be entered as the mirror path.  For
example: ``git@git.example.com:projectname.git``

The `Username and Password fields`_ should be blank.


.. _raw-file-urls:

Raw File URLs
~~~~~~~~~~~~~

.. versionadded:: 1.5

Review Board can access a remote file by talking to a cgit or gitweb server.
This is done by filling out the `Raw file URL mask`_ field to tell Review
Board how to access a single file based on revision.

The URL can make use of the following tags, which will be replaced before
attempting to fetch the file:

* ``<revision>`` - The full SHA1 of the file blob.
* ``<filename>`` - The unescaped path to the file.

cgit
^^^^

For cgit, this path should be in the form of:

:samp:`http://{servername}/browse/gtk+/plain/<filename>?id2=<revision>`

For example:

:samp:`http://git.gnome.org/browse/gtk+/plain/<filename>?id2=<revision>`


Gitweb
^^^^^^

For Gitweb:

:samp:`http://{servername}/?p={relative path to git repo};a=blob_plain;f=<filename>;hb=<revision>`

For example:

:samp:`http://git.kernel.org/?p=bluetooth/bluez-gnome.git;a=blob_plain;f=<filename>;hb=<revision>`


Perforce
--------

The Perforce path can be retrieved from an existing Perforce checkout by
typing the following::

    $ p4 info

Use the value from the :guilabel:`Server address` field.

In most setups, the `Username field`_ must be provided. This must be a user
that has access to the whole repository. In some setups, this is a dedicated
read-only user.

Note that Review Board will only ever use this user for read-only operations.
It will never write to the repository.


Subversion
----------

The Subversion path can be retrieved from an existing Subversion checkout by
typing the following::

    $ svn info

Use the value from the :guilabel:`Repository Root` field.

In most server setups, Subversion provides anonymous access, so the
`Username and Password fields`_ won't need to be filled out. However, this
depends on the server setup. Some are more restricted and will require a
dedicated user.

In Subversion setups where there's a public anonymous URL and a secured
developer URL (such as one using ``https`` or ``svn+ssh``), you
should put the public URL in :guilabel:`Path` field and
your developer URL in the :guilabel:`Mirror Path`.


.. comment: vim: ft=rst et
