This is a work in progress, and first part of a three part guide to arcanist/differential. Your feedback is welcome.

Now, let’s get to work. You can grab my hand.

You’ll need Phabricator, obviously.

First, you need Phabricator. Either your own, or hosted somewhere. And what a coincidence, we can host Pharicator for you. Now that we’re done with the plug, let’s move on. If you liked the product placement, there’s one more at the end of the article.

We’ll assume your instance’s address is phabricate.exana.io.

You’ll need arcanist, the CLI tool

For OS X and homebrew, you can just brew install arcanist.

If that fails, the manual way is to clone both arcanist and libphutil:

/somewhere/ $ git clone https://github.com/phacility/libphutil.git
/somewhere/ $ git clone https://github.com/phacility/arcanist.git

Add /somewhere/arcanist/bin to your $PATH (or link it) and you’re all set.

You’ll need to configure arcanist

The CLI app is called arc.

You configure arc on a per-project basis. Configuration is pain like no other, you’ll need to create a file and put things in it. Specifically, you’ll need to create an .arcconfig file in the root of your project.

{
  "phabricator.uri" : "https://phabricate.exana.io"
}

arcanist will guess which repository you’re referring to. But if you want to be explicit, add a "repository.callsign" key to .arcconfig.

And yes, you will want to commit this file into your repository.

Workflow TL;DR:

Straight to it. Let’s say you’ve got a clean working copy of your code and you’re on the master branch (or equivalent, you may be using hg or svn after all).

$ cd /code  
$ arc feature T5410  # Start work on a new feature (task T5410).
$ arc start  # Optional: start tracking time spent on feature.
$ vim ... 
# Add spaghetti to your codebase here ...
$ git commit ...  # arcanist works on top of git/mercurial/svn, so you need to commit
$ arc stop  # Optional: let's say we're done - for now.
$ arc diff  # Create a Differential revision for our changes.
# Review happens here - comes back with a few requests for changes. 
$ vim ...
# Add better spaghetti, as noted during review.
$ git commit ... # Commit changes
$ arc diff # Send changes to review.
# Review happens here - again. Patch passes it, this time.
$ arc land
# You're done! Feature is merged into master and pushed.

Let’s break this down a bit

arc feature T5410 - doc says:

A wrapper on git branch or hg bookmark.

maligree:code/ (master) $ arc feature T100                                                                                          [11:11
Branch T100 set up to track local branch master.
Switched to a new branch 'T100'

Will create a new branch for you. If you include the task ID in the form of T123, you will be able to use arc start|stop|time and keep other things neatly integrated. Apart from that, you can name the branch anything you want.

arc start - will start tracking time spent working on this feature. Tracking time isn’t a bad idea, even if just to get an idea how off your first estimate was.

# actually coding - remember to use globals, place random side effects all over your code base and over-comment the obvious parts of it.

git add, git commit ...

arc diff - create a differential revision. You’ll need to specify a test plan, add a reviewer and so on. If you don’t have a terminal nearby, look at this paste and pretend it’s yours:

maligree:code/ (T5410-add-pipework) $ arc diff                                                                                                  [10:41:10]
Linting...
No lint engine configured for this project.
Running unit tests...
No unit test engine is configured for this project.
 SKIP STAGING  No staging area is configured for this repository.
Updated an existing Differential revision:
        Revision URI: https://phabricate.exana.io/D3

Included changes:
  A       pipework.php

arc land - if your patch passes review, you’re good to land. By default this merges current feature branch into master and pushes.

Onwards

We’ll look at configuring linters in part two, and integrating unit tests in part three.