Arcanist User Guide
Phorge Administrator and User Documentation (Application User Guides)

Guide to Arcanist, a command-line interface to Phorge.

Arcanist provides command-line access to many Phorge tools (like Differential, Files, and Paste), integrates with static analysis ("lint") and unit tests, and manages common workflows like getting changes into Differential for review.

A detailed command reference is available by running arc help. This document provides an overview of common workflows and installation.

Arcanist has technical, contributor-focused documentation here: https://we.phorge.it/book/arcanist/

Quick Start

A quick start guide is available at Arcanist Quick Start. It provides a much more compact summary of how to get arc set up and running for a new project. You may want to start there, and return here if you need more information.

Overview

Arcanist is a wrapper script that sits on top of other tools (e.g., Differential, linters, unit test frameworks, git, Mercurial, and SVN) and provides a simple command-line API to manage code review and some related revision control operations.

For a detailed list of all available commands, run:

$ arc help

For detailed information about a specific command, run:

$ arc help <command>

Arcanist allows you to do things like:

get detailed help about available commands with arc help
send your code to Differential for review with arc diff (for detailed instructions, see Arcanist User Guide: arc diff)
show pending revision information with arc list
find likely reviewers for a change with arc cover
apply changes in a revision to the working copy with arc patch
download a patch from Differential with arc export
update Git commit messages after review with arc amend
commit SVN changes with arc commit
push Git and Mercurial changes with arc land
view enhanced information about Git branches with arc branch

Once you've configured lint and unit test integration, you can also:

check your code for syntax and style errors with arc lint (see Arcanist User Guide: Lint)
run unit tests that cover your changes with arc unit

Arcanist integrates with other tools:

upload and download files with arc upload and arc download
create and view pastes with arc paste

Arcanist has some advanced features as well, you can:

execute Conduit method calls with arc call-conduit
create or update libphutil libraries with arc liberate
activate tab completion with arc shell-complete
...or extend Arcanist and add new commands.

Except where otherwise noted, these workflows are generally agnostic to the underlying version control system and will work properly in git, Mercurial, or SVN repositories.

Installing Arcanist

Arcanist is meant to be installed on your local machine or development server -- whatever machine you're editing code on. It runs on:

Linux;
Other operating systems which are pretty similar to Linux, or which Linux is pretty similar to;
FreeBSD, a fine operating system held in great esteem by many;
Mac OS X (see Arcanist User Guide: Mac OS X); and
Windows (see Arcanist User Guide: Windows).

Arcanist is written in PHP, so you need to install the PHP CLI first if you don't already have it. Arcanist should run on PHP 5.2 and newer. If you don't have PHP installed, you can download it from http://www.php.net/.

To install Arcanist, pick an install directory and clone the code from GitHub:

some_install_path/ $ git clone https://github.com/phorgeit/arcanist.git

Now add some_install_path/arcanist/bin/ to your PATH environment variable. When you type "arc", you should see something like this:

Usage Exception: No command provided. Try 'arc help'.

If you get that far, you've done things correctly. If you get an error or have trouble getting this far, see these detailed guides:

On Windows: Arcanist User Guide: Windows
On Mac OS X: Arcanist User Guide: Mac OS X

You can later upgrade Arcanist to the latest version with arc upgrade:

$ arc upgrade

Installing Arcanist for a Team

Arcanist changes quickly, so it can be something of a headache to get it installed and keep people up to date. Here are some approaches you might be able to use:

Facebook does most development on development servers, which have a standard environment and NFS mounts. Arcanist lives on an NFS mount, and the default .bashrc adds them to the PATH. Updating the mount source updates everyone's versions, and new employees have a working arc when they first log in.
Another common approach is to write an install script as an action into existing build scripts, so users can run make install-arc or ant install-arc or similar.

Installing Tab Completion

If you use bash, you can set up tab completion by running this command:

$ arc shell-complete

This will install shell completion into your current shell. After installing, you may need to start a new shell (or open a new terminal window) to pick up the updated configuration.

Configuration

Some Arcanist commands can be configured. This configuration is read from three sources, in order:

A project can specify configuration in an .arcconfig file. This file is JSON, and can be updated using arc set-config --local or by editing it manually.
User configuration is read from ~/.arcconfig. This file is JSON, and can be updated using arc set-config.
Host configuration is read from /etc/arcconfig (on Windows, the path is C:\ProgramData\Phorge\Arcanist\config).

Arcanist uses the first definition it encounters as the runtime setting.

Existing settings can be printed with arc get-config.

Use arc help set-config and arc help get-config for more information about reading and writing configuration.

Next Steps

Continue by:

setting up a new project for use with arc, with Arcanist User Guide: Configuring a New Project; or
learning how to use arc to send changes for review with Arcanist User Guide: arc diff.

Advanced topics are also available. These are detailed guides to configuring technical features of arc that refine its behavior. You do not need to read them to get it working.

Defined: src/docs/user/userguide/arcanist.diviner:1

Arcanist User GuidePhorge Administrator and User Documentation (Application User Guides)