@title Diffusion User Guide
@group userguide

Guide to Diffusion, the Phorge application for hosting and browsing
repositories.

Overview
========

Diffusion allows you to create repositories so that you can browse them from
the web and interact with them from other applications.

Diffusion can host repositories locally, or observe existing remote
repositories which are hosted elsewhere (for example, on GitHub, Bitbucket, or
other existing hosting). Both types of repositories can be browsed and
interacted with, but hosted repositories support some additional triggers
and access controls which are not available for observed repositories.

Diffusion is integrated with the other tools in the Phorge suite. For
instance:

  - when you commit Differential revisions to a tracked repository, they are
    automatically updated and linked to the corresponding commits;
  - you can add Herald rules to notify you about commits that match certain
    rules;
  - for hosted repositories, Herald can enforce granular access control rules;
  - in all the tools, commit names are automatically linked.

The remainder of this document walks through creating, configuring, and
managing repositories.


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

Repository administration is accomplished through Diffusion. You can use the
web interface in Diffusion to observe an external repository or create a new
hosted repository.

  - For hosted repositories, make sure you go through the setup instructions
    in @{article:Diffusion User Guide: Repository Hosting} first.
  - For all repositories, you'll need to be running the daemons. If you have
    not set them up yet, see @{article:Managing Daemons with phd}.

By default, you must be an administrator to create a new repository. You can
change this in the application settings.


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

Diffusion repositories have an array of configurable options and behaviors. For
details on the available options and guidance on managing and administrating
repositories, see @{article:Diffusion User Guide: Managing Repositories}.

Repositories can also be managed via the API. For an overview on using the
API to create and edit repositories, see
@{article:Diffusion User Guide: Repositories API}.


Repository Clustering
=====================

Phorge repository hosts can be set up in a cluster configuration so you
can lose hosts with minimal downtime and data loss. This is an advanced feature
which most installs do not need to pursue.

To get started with clustering, see @{article:Clustering Introduction}. For
details on repository clustering, see @{article:Cluster: Repositories}.


Next Steps
==========

Continue by:

  - learning how to creating a symbol index at
    @{article:Diffusion User Guide: Symbol Indexes}; or
  - setting up repository hosting with
    @{article:Diffusion User Guide: Repository Hosting}; or
  - managing repository hooks with
    @{article:Diffusion User Guide: Commit Hooks}; or
  - understanding daemons in more detail with
    @{article:Managing Daemons with phd}.

If you're having trouble getting things working, these topic guides may be
helpful:

  - get details about automatically taking actions in response to commits in
    @{article:Diffusion User Guide: Permanent Refs}; or
  - understand how Phorge updates repositories with
    @{article:Diffusion User Guide: Repository Updates}; or
  - fix issues with repository imports with
    @{article:Troubleshooting Repository Imports}.