[Summary view] [Print] [Text view]

   1  @title Arcanist User Guide
   2  @group userguide
   3  
   4  Guide to Arcanist, a command-line interface to Phabricator.
   5  
   6  Arcanists provides command-line access to many Phabricator tools (like
   7  Differential, Files, and Paste), integrates with static analysis ("lint") and
   8  unit tests, and manages common workflows like getting changes into Differential
   9  for review.
  10  
  11  A detailed command reference is available by running ##arc help##. This
  12  document provides an overview of common workflows and installation.
  13  
  14  Arcanist has technical, contributor-focused documentation here:
  15  <http://www.phabricator.com/docs/arcanist/>
  16  
  17  = Quick Start =
  18  
  19  A quick start guide is available at @{article:Arcanist Quick Start}. It provides
  20  a much more compact summary of how to get `arc` set up and running for a new
  21  project. You may want to start there, and return here if you need more
  22  information.
  23  
  24  = Overview =
  25  
  26  Arcanist is a wrapper script that sits on top of other tools (e.g.,
  27  Differential, linters, unit test frameworks, git, Mercurial, and SVN) and
  28  provides a simple command-line API to manage code review and some related
  29  revision control operations.
  30  
  31  For a detailed list of all available commands, run:
  32  
  33    $ arc help
  34  
  35  For detailed information about a specific command, run:
  36  
  37    $ arc help <command>
  38  
  39  Arcanist allows you to do things like:
  40  
  41    - get detailed help about available commands with ##arc help##
  42    - send your code to Differential for review with ##arc diff## (for detailed
  43      instructions, see @{article:Arcanist User Guide: arc diff})
  44    - show pending revision information with ##arc list##
  45    - find likely reviewers for a change with ##arc cover##
  46    - apply changes in a revision to the working copy with ##arc patch##
  47    - download a patch from Differential with ##arc export##
  48    - update Git commit messages after review with ##arc amend##
  49    - commit SVN changes with ##arc commit##
  50    - push Git and Mercurial changes with ##arc land##
  51    - view enhanced information about Git branches with ##arc branch##
  52  
  53  Once you've configured lint and unit test integration, you can also:
  54  
  55    - check your code for syntax and style errors with ##arc lint##
  56      (see @{article:Arcanist User Guide: Lint})
  57    - run unit tests that cover your changes with ##arc unit##
  58  
  59  Arcanist integrates with other tools:
  60  
  61    - upload and download files with ##arc upload## and ##arc download##
  62    - create and view pastes with ##arc paste##
  63  
  64  Arcanist has some advanced features as well, you can:
  65  
  66    - execute Conduit method calls with ##arc call-conduit##
  67    - create or update libphutil libraries with ##arc liberate##
  68    - activate tab completion with ##arc shell-complete##
  69    - install arc as a pre-commit hook with ##arc svn-hook-pre-commit## or
  70      ##arc git-hook-pre-receive##
  71    - ...or extend Arcanist and add new commands.
  72  
  73  Except where otherwise noted, these workflows are generally agnostic to the
  74  underlying version control system and will work properly in git, Mercurial, or
  75  SVN repositories.
  76  
  77  = Installing Arcanist =
  78  
  79  Arcanist is meant to be installed on your local machine or development server --
  80  whatever machine you're editing code on. It runs on:
  81  
  82    - Linux;
  83    - Other operating systems which are pretty similar to Linux, or which
  84      Linux is pretty similar to;
  85    - FreeBSD, a fine operating system held in great esteem by many;
  86    - Mac OS X (see @{article:Arcanist User Guide: Mac OS X}); and
  87    - Windows (see @{article:Arcanist User Guide: Windows}).
  88  
  89  Arcanist is written in PHP, so you need to install the PHP CLI first if you
  90  don't already have it. Arcanist should run on PHP 5.2 and newer. If you don't
  91  have PHP installed, you can download it from <http://www.php.net/>.
  92  
  93  To install Arcanist, pick an install directory and clone the code from GitHub:
  94  
  95    some_install_path/ $ git clone https://github.com/phacility/libphutil.git
  96    some_install_path/ $ git clone https://github.com/phacility/arcanist.git
  97  
  98  This should leave you with a directory structure like this
  99  
 100    some_install_path/    # Wherever you chose to install it.
 101      arcanist/           # Arcanist-specific code and libraries.
 102      libphutil/          # A shared library Arcanist depends upon.
 103  
 104  Now add ##some_install_path/arcanist/bin/## to your PATH environment variable.
 105  When you type "arc", you should see something like this:
 106  
 107    Usage Exception: No command provided. Try 'arc help'.
 108  
 109  If you get that far, you've done things correctly. If you get an error or have
 110  trouble getting this far, see these detailed guides:
 111  
 112    - On Windows: @{article:Arcanist User Guide: Windows}
 113    - On Mac OS X: @{article:Arcanist User Guide: Mac OS X}
 114  
 115  You can later upgrade Arcanist and libphutil to the latest versions with
 116  `arc upgrade`:
 117  
 118    $ arc upgrade
 119  
 120  == Installing Arcanist for a Team ==
 121  
 122  Arcanist changes quickly, so it can be something of a headache to get it
 123  installed and keep people up to date. Here are some approaches you might be
 124  able to use:
 125  
 126    - Facebook does most development on development servers, which have a standard
 127      environment and NFS mounts. Arcanist and libphutil themselves live on an
 128      NFS mount, and the default `.bashrc` adds them to the PATH. Updating the
 129      mount source updates everyone's versions, and new employees have a working
 130      `arc` when they first log in.
 131    - Another common approach is to write an install script as an action into
 132      existing build scripts, so users can run `make install-arc` or
 133      `ant install-arc` or similar.
 134    - In general, if this sucks and is causing you pain, let us know (see
 135      @{article:Give Feedback! Get Support!}). We're planning to improve this at
 136      some point, but it's somewhat complicated to get right. While it can take a
 137      little time to set up, we aren't getting feedback that it's a persistent
 138      pain point, so it hasn't been a priority.
 139  
 140  == Installing Tab Completion ==
 141  
 142  If you use ##bash##, you can set up tab completion by adding something like this
 143  to your ##.bashrc##, ##.profile## or similar:
 144  
 145    source /path/to/arcanist/resources/shell/bash-completion
 146  
 147  == Configuration ==
 148  
 149  Some Arcanist commands can be configured. This configuration is read from
 150  several sources:
 151  
 152    # A customization can force any setting with
 153      @{method@arcanist:ArcanistWorkingCopyIdentity::setRuntimeConfig}.
 154    # User can specify settings for working copy in `arc/config` file located in
 155      VCS directory (e.g. `.git/arc/config`) in JSON format. This file can also be
 156      modified by running `arc set-config --local`.
 157    # Repository can specify its config in `.arcconfig` in JSON format.
 158    # User can specify the settings in `~/.arcrc` (JSON) through the `config` key.
 159      This file can be modified also by `arc set-config --global`.
 160    # Machine can specify the settings with `/etc/arcconfig` (JSON). On Windows,
 161      the file path is `C:\ProgramData\Phabricator\Arcanist\config`.
 162  
 163  The first place where the setting is defined wins.
 164  
 165  Existing settings can be printed with `arc get-config`.
 166  
 167  == Next Steps ==
 168  
 169  Continue by:
 170  
 171    - setting up a new project for use with `arc`, with
 172      @{article:Arcanist User Guide: Configuring a New Project}; or
 173    - learning how to use `arc` to send changes for review with
 174      @{article:Arcanist User Guide: arc diff}.
 175  
 176  Advanced topics are also available. These are detailed guides to configuring
 177  technical features of `arc` that refine its behavior. You do not need to read
 178  them to get it working.
 179  
 180   - @{article:Arcanist User Guide: Commit Ranges}
 181   - @{article:Arcanist User Guide: Lint}
 182   - @{article:Arcanist User Guide: Customizing Existing Linters}
 183   - @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}
 184   - @{article:Arcanist User Guide: Code Coverage}
 185   - @{article:Arcanist User Guide: Repository Hooks}