Phabricator/Arcanist

Arcanist is a command line tool that can be used to submit, review and land (commit) patches to git repositories that live (i.e. read/write) on Phabricator; if the clone line has an "eye"/read-only icon on diffusion, it means the repository lives elsewhere, probably on gerrit.

Installation
Please install Arcanist using git (the first option below) as it will ensure API compatibility. Using pre-packaged alternatives (eg: Debian repositories, Homebrew or anything that's not on this page) will highly likely cause API compatibility issues.

Using git (recommended)
This applies to both Linux and OSX systems.

Chose an installation directory (for example ) and clone two repositories into it (  and  ).

You will get two subdirectories in the  directory:   and. They will be tracking the  branch, which is always in sync with our Phabricator installation.

Now add  to your PATH (variable). The easiest way to do so on Unix is to add a symlink in a directory already in your PATH, pointing to the arc binary.


 * Updating
 * Updating Arcanist is as simple as typing

Debian / Ubuntu packages
If you can, using the Git installation method above is still preferred.

Primarily used for our Continuous Integration servers and to avoid the API compatibility problem explained above, Wikimedia's APT repository provides packages for Debian Jessie and Ubuntu Trusty. We intend to keep these compatible with our Phabricator releases.

You can get our version of the arcanist and libphutil packages from apt.wikimedia.org by creating /etc/apt/sources.d/wikimedia.list with the following contents:

deb http://apt.wikimedia.org/wikimedia jessie-wikimedia main experimental backports deb-src http://apt.wikimedia.org/wikimedia jessie-wikimedia main universe
 * 1) Wikimedia APT repository

Once you've done that, update your apt cache:

sudo apt-get update

Then finally:

sudo apt-get install arcanist

For more information about the Wikimedia APT repositories, please see APT_repository.


 * Updating
 * Updating Arcanist should be as simple as doing  followed by

Installation on Debian and Ubuntu can be done without adding the Wikimedia APT repository because arcanist is available in the official Debian repositories. However, as above, we strongly recommend that you install either the Wikimedia-maintained package (or, even better, by the Git installation method) for use with phabricator.wikimedia.org to maintain API compatibility.

Setup
Tell Arcanist where your default Phabricator install is (presumably the phabricator.wikimedia.org one)

Which should respond with something like:

Set key 'default' = "https://phabricator.wikimedia.org/" in global config (was null)

Then you should install your personal Phabricator key.

Arc will prompt you to login to Phabricator via the web browser and pick up the key from the specified location:

Installing certificate for 'https://phabricator.wikimedia.org/api/'... Trying to connect to server... Connection OK!

Login to phabricator
Open this page in your browser and login to Phabricator if necessary:

https://phabricator.wikimedia.org/conduit/token/

Then paste the token on that page below.

Paste token from that page:

When clicking a link the following webpage is presented:

Certificate Install Token Copy and paste this token into the prompt given to you by "arc install-certificate":

xasdase34531asdhccasdsddadxtluyx5r5nqmu6xj5gjwxagzrej

arc will then complete the install process for you.

After the token is pasted into the arc window it should say:

Downloading authentication certificate... Installing certificate for 'yourusername'... Writing ~/.arcrc... SUCCESS! Certificate installed.

Basics
Arcanist is a tool that allows you to interact with the code-review tool (aka "Differential") in Phabricator.

Diff
arc diff will submit your changes to review, example:

git commit -a arc diff
 * 1) changes

Landing
Once a change is approved, you can land it, given that you have push access to repository. In a traditional plain git workflow you would generally merge your feature branch manually and push it up to the remote.

Arcanist provides the arc land workflow to automate this process.

Once a revision is accepted in Differential, anyone with the ability to push to the corresponding repository can merge and land the change on Phabricator. The process is straightforward, simply run the command from inside your local clone of the repository as follows, run ` ` where # represents the revision number of the patch you are landing.

Merging another author's change
In the past, ` ` had issues when landing patches by an author other than yourself. This lead us to recommend other methods of landing a patch, however, the bugs have all been fixed and ` ` is now recommended workflow regardless of whether it's your own patch or a contribution from some other author.

Example
Now you can clone an experimental respository using Git:

Go to the repository and try fetching some code:

The system will ask you:

This diff is for the 'E3Experiments' project but the working copy belongs to the '' project. Still try to apply it? [Y/n] y

Answer 'Y' and Arcanist should download the change:

Created and checked out branch arcpatch-D3. Downloading binary data... Downloading binary data... Downloading binary data... Downloading binary data... OKAY Successfully committed patch.

And you can see the patch in your local repository: master     e40fce0 [origin/master] Rename events.js -> communityClicks.js
 * arcpatch-D3 be7cfd9 Merge branch 'master' of ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/E3Experiments into munaf/pef2