[Summary view] [Print] [Text view]

   1  @title Diffusion User Guide
   2  @group userguide
   3  
   4  Guide to Diffusion, the Phabricator repository browser.
   5  
   6  = Overview =
   7  
   8  Diffusion is a repository browser which allows you to explore source code in a
   9  Subversion, Git, or Mercurial repository. It is somewhat similar to software
  10  like Trac and GitWeb.
  11  
  12  Diffusion can either import a read-only copy of repositories hosted somewhere
  13  else (for example, from GitHub, Bitbucket or existing hosting) or host
  14  repositories within Phabricator. Hosted repositories support a variety of
  15  triggers and access controls.
  16  
  17  Diffusion is integrated with the other tools in the Phabricator suite. For
  18  instance:
  19  
  20    - when you commit Differential revisions to a tracked repository, they are
  21      automatically updated and linked to the corresponding commits;
  22    - you can add Herald rules to notify you about commits that match certain
  23      rules;
  24    - for hosted repositories, Herald can enforce granular access control rules;
  25    - in all the tools, commit names are automatically linked.
  26  
  27  = Adding Repositories =
  28  
  29  Repository administration is accomplished through Diffusion. You can use the
  30  web interface in Diffusion to import an external repository, or create a new
  31  hosted repository.
  32  
  33    - For hosted repositories, make sure you go through the setup instructions
  34      in @{article:Diffusion User Guide: Repository Hosting} first.
  35    - For all repositories, you'll need to be running the daemons. If you have
  36      not set them up yet, see @{article:Managing Daemons with phd}.
  37  
  38  By default, you must be an administrator to create a new repository.
  39  
  40  = Repository Callsigns and Commit Names =
  41  
  42  Each repository is identified by a "callsign", which is a short uppercase string
  43  like "P" (for Phabricator) or "ARC" (for Arcanist).
  44  
  45  Each repository must have a unique callsign. Callsigns must be unique within
  46  an install but do not need to be globally unique, so you are free to use the
  47  single-letter callsigns for brevity. For example, Facebook uses "E" for the
  48  Engineering repository, "O" for the Ops repository, "Y" for a Yum package
  49  repository, and so on, while Phabricator uses "P", "ARC", "PHU" for libphutil,
  50  and "J" for Javelin. Keeping callsigns brief will make them easier to use, and
  51  the use of one-character callsigns is recommended if they are reasonably
  52  evocative and you have no more than 26 tracked repositories.
  53  
  54  The primary goal of callsigns is to namespace commits to SVN repositories: if
  55  you use multiple SVN repositories, each repository has a revision 1, revision 2,
  56  etc., so referring to them by number alone is ambiguous. However, even for Git
  57  they impart additional information to human readers and allow parsers to detect
  58  that something is a commit name with high probability (and allow distinguishing
  59  between multiple copies of a repository).
  60  
  61  Diffusion uses this callsign and information about the commit itself to generate
  62  a commit name, like "rE12345" or "rP28146171ce1278f2375e3646a1e1ea3fd56fc5a3".
  63  The "r" stands for "revision". It is followed by the repository callsign, and
  64  then a VCS-specific commit identifier (for SVN, the commit number; for Git and
  65  Mercurial, the commit hash). When writing the name of a Git commit you may
  66  abbreviate the hash, but note that hash collisions are probable for short prefix
  67  lengths. See this post on the LKML for a historical explanation of Git's
  68  occasional internal use of 7-character hashes:
  69  
  70  https://lkml.org/lkml/2010/10/28/287
  71  
  72  Because 7-character hashes are likely to collide for even moderately large
  73  repositories, Diffusion generally uses either a 16-character prefix (which makes
  74  collisions very unlikely) or the full 40-character hash (which makes collisions
  75  astronomically unlikely).
  76  
  77  = Running Diffusion Daemons =
  78  
  79  In most cases, it is sufficient to run:
  80  
  81    phabricator/bin/ $ ./phd start
  82  
  83  ...to start the daemons. For a more in-depth explanation of `phd` and daemons,
  84  see @{article:Managing Daemons with phd}.
  85  
  86  NOTE: If you have an unusually large install with multiple web frontends, see
  87  notes in @{article:Managing Daemons with phd}.
  88  
  89  You can use the repository detail screen and the Daemon Console to monitor the
  90  daemons and their progress importing the repository. Small repositories should
  91  import quickly, while larger repositories may take some time. Commits should
  92  begin appearing in Diffusion within a few minutes for all but the largest
  93  repositories.
  94  
  95  = Next Steps =
  96  
  97    - Learn about creating a symbol index at
  98      @{article:Diffusion User Guide: Symbol Indexes}; or
  99    - set up repository hosting with
 100      @{article:Diffusion User Guide: Repository Hosting}; or
 101    - understand daemons in detail with @{article:Managing Daemons with phd}; or
 102    - give us feedback at @{article:Give Feedback! Get Support!}.