mirror of
https://we.phorge.it/source/phorge.git
synced 2025-01-07 13:21:02 +01:00
95fe4f9451
Summary: Fixes T8615. Basic overview of the pipeline, where to look for errors, and how to identify/understand/fix/force your way through. Test Plan: Read documentation. Reviewers: btrahan, joshuaspence Reviewed By: joshuaspence Subscribers: epriestley Maniphest Tasks: T8615 Differential Revision: https://secure.phabricator.com/D13376
116 lines
5.1 KiB
Text
116 lines
5.1 KiB
Text
@title Diffusion User Guide
|
|
@group userguide
|
|
|
|
Guide to Diffusion, the Phabricator repository browser.
|
|
|
|
= Overview =
|
|
|
|
Diffusion is a repository browser which allows you to explore source code in a
|
|
Subversion, Git, or Mercurial repository. It is somewhat similar to software
|
|
like Trac and GitWeb.
|
|
|
|
Diffusion can either import a read-only copy of repositories hosted somewhere
|
|
else (for example, from GitHub, Bitbucket or existing hosting) or host
|
|
repositories within Phabricator. Hosted repositories support a variety of
|
|
triggers and access controls.
|
|
|
|
Diffusion is integrated with the other tools in the Phabricator 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.
|
|
|
|
= Adding Repositories =
|
|
|
|
Repository administration is accomplished through Diffusion. You can use the
|
|
web interface in Diffusion to import 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.
|
|
|
|
= Repository Callsigns and Commit Names =
|
|
|
|
Each repository is identified by a "callsign", which is a short uppercase string
|
|
like "P" (for Phabricator) or "ARC" (for Arcanist).
|
|
|
|
Each repository must have a unique callsign. Callsigns must be unique within
|
|
an install but do not need to be globally unique, so you are free to use the
|
|
single-letter callsigns for brevity. For example, Facebook uses "E" for the
|
|
Engineering repository, "O" for the Ops repository, "Y" for a Yum package
|
|
repository, and so on, while Phabricator uses "P", "ARC", "PHU" for libphutil,
|
|
and "J" for Javelin. Keeping callsigns brief will make them easier to use, and
|
|
the use of one-character callsigns is recommended if they are reasonably
|
|
evocative and you have no more than 26 tracked repositories.
|
|
|
|
The primary goal of callsigns is to namespace commits to SVN repositories: if
|
|
you use multiple SVN repositories, each repository has a revision 1, revision 2,
|
|
etc., so referring to them by number alone is ambiguous. However, even for Git
|
|
they impart additional information to human readers and allow parsers to detect
|
|
that something is a commit name with high probability (and allow distinguishing
|
|
between multiple copies of a repository).
|
|
|
|
Diffusion uses this callsign and information about the commit itself to generate
|
|
a commit name, like "rE12345" or "rP28146171ce1278f2375e3646a1e1ea3fd56fc5a3".
|
|
The "r" stands for "revision". It is followed by the repository callsign, and
|
|
then a VCS-specific commit identifier (for SVN, the commit number; for Git and
|
|
Mercurial, the commit hash). When writing the name of a Git commit you may
|
|
abbreviate the hash, but note that hash collisions are probable for short prefix
|
|
lengths. See this post on the LKML for a historical explanation of Git's
|
|
occasional internal use of 7-character hashes:
|
|
|
|
https://lkml.org/lkml/2010/10/28/287
|
|
|
|
Because 7-character hashes are likely to collide for even moderately large
|
|
repositories, Diffusion generally uses either a 16-character prefix (which makes
|
|
collisions very unlikely) or the full 40-character hash (which makes collisions
|
|
astronomically unlikely).
|
|
|
|
= Running Diffusion Daemons =
|
|
|
|
In most cases, it is sufficient to run:
|
|
|
|
phabricator/bin/ $ ./phd start
|
|
|
|
...to start the daemons. For a more in-depth explanation of `phd` and daemons,
|
|
see @{article:Managing Daemons with phd}.
|
|
|
|
NOTE: If you have an unusually large install with multiple web frontends, see
|
|
notes in @{article:Managing Daemons with phd}.
|
|
|
|
You can use the repository detail screen and the Daemon Console to monitor the
|
|
daemons and their progress importing the repository. Small repositories should
|
|
import quickly, while larger repositories may take some time. Commits should
|
|
begin appearing in Diffusion within a few minutes for all but the largest
|
|
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 closing tasks and revisions in response
|
|
to commits in @{article:Diffusion User Guide: Autoclose}; or
|
|
- understand how Phabricator updates repositories with
|
|
@{article:Diffusion User Guide: Repository Updates}; or
|
|
- fix issues with repository imports with
|
|
@{article:Troubleshooting Repository Imports}.
|