Using phabricator

is a tool for doing code reviews. It 'works' with mercurial and actually works with git (including github).

Initial Setup

Getting started with phabricator is relatively simple:
  1. If you did not use khan-dotfiles to set up your environment, install phabricator requirements manually.

  2. Go to and log in using Google OAuth. After that is done, click the "Create account" button.  I strongly suggest you keep the provided username (same as your gmail username).

  3. Optional: go to and change your email address from <whatever> to <whatever>  This will make it easier to filter phabricator mail if you so desire. (Mail agents ignore the + and anything after it, which is a nice way to give a "different" email address to different accounts!) You may also want to set your 'self actions' at so you get less email. Alternately, many people have found it useful to get emails for self actions and filter them automatically upon receipt. Specifically, tell Gmail to match messages from <whatever> and do this: Skip Inbox, Mark as read.

  4. Set up your ~/.arcrc with the default values by running arc with no arguments, and then install the certificate to hook arc to the phabricator installation:
    arc install-certificate
    Note: if you get the following error: Usage Exception: Your '~/.arcrc' file is not a valid JSON file., it's probably because you have an empty ~/.arcrc file hanging around. Remove it and run the arc install-certificate command again.
Note: if for some reason you hit a -bash: arc: command not found error: 1) Verify you have the directories arcanist/ and libputil/ installed in your [somewhere]/khan/devtools/ folder. This is where the dotfiles setup script should have downloaded a bunch of files 2) Source that arc file [somewhere]/khan/devtools/arcanist/bin 

If after this, you try to run arc above and get:
$ arc
Usage Exception: No command provided. Try 'arc help'.

continue by running the command above (listed here):
arc install-certificate

That should succeed. And to fill in the missing default settings for ~/.arcrc add in the missing lines (everything but the hosts block).

*These settings are current as of 06/17/2014 -
  "aliases" : {
    "mail" : [
  "config"  : {
    ""      : "rebase",
    "default"                      : "http:\/\/",
    "history.immutable"            : false,
    "lint.engine"                  : "ArcanistSingleLintEngine",
    "lint.engine.single.linter"    : "ArcanistScriptAndRegexLinter",
    "linter.scriptandregex.regex"  : "\/^((?P<file>[^:]*):(?P<line>\\d+):((?P<char>\\d+):)? (?P<name>((?P<error>E)|(?P<warning>W))\\S+) (?P<message>.*))|(?P<ignore>SKIPPING.*)$\/m",
    "linter.scriptandregex.script" : "~\/khan\/devtools\/khan-linter\/ --always-exit-0 --blacklist=yes"
  "khan"    : {
    "do_not_auto_update" : [
 "hosts" : {  <-------- USE YOUR OWN "hosts" BLOCK
    "http:\/\/\/api\/" : {
      "user" : "YOUR NAME!!!!!!!!!!!!!!!!!!!!!!!!!!!!",
      "cert" : "SOME REALLY LONG STRING!!!!!!!!!!!!!!!!!!!"

Day-to-day use

Phabricator best practice is to do all your work in branches.  You do no development in the master branch; that is just a staging branch to push upstream (to github or kiln or whatever).  These instructions are for git; you can do something similar with hg with some difficulty; talk to marcos for details.
  1. When you want to start work on a new feature or change, create a local branch: git co -b <branchname>
    • Phabricator will work best if this is set up as a tracking branch.  If you installed khan-dotfiles this will happen automatically; otherwise you'll want to do git branch --track <branchname> && git co <branchname> instead.)

  2. Make a bunch of changes, and commit them as normal: git commit

  3. When you're ready for a review, run arc diff --rr reviewer1,reviewer2 [--cc person3] --verbatim
    • You can also just run arc diff and specify the reviewers manually by putting 'Reviewers: xxx, yyy' in the editor that pops up.
    • Note that the names of reviewers should be their phabricator usernames, which may be different from their github usernames.
    • --verbatim says to use the git commit message as the arc review message.  Some people prefer to do it the other way around, and always have 'WIP' as the git commit message, and instead put their real text in the arc editor.  In that case, do not provide --verbatim here.  (Note phabricator will always replace the git commit message with the arc message when you land the review, so what ends up in the editor here is what's most important.)
    • If you're tired of typing --verbatim all the time, you can run arc alias vdiff diff -- --verbatim, and then use arc vdiff
    • If you are not quite sure what arc diff will do, you can find out by running arc which

  4. Often, the feedback from the review will prompt you to make changes.  Make the changes as normal in your branch, and then commit them.  You can either run git commit or git commit --amend; some people prefer the latter to keep each branch with only one commit in it, but phabricator will deal correctly with either.  When you are done with your changes, run arc diff --verbatim again (or just arc diff).
    • If you need to force arc to assign the new commits to the correct phabricator revision id, use arc diff --update [revision id]

  5. When you are ready to push, you'll want to rebase your changes into the master branch (no merges in this model), and do a git push from master up to github. You can do this in one step, which will also update your commit message with phabricator metadata: arc land
    • If you want to be explicit, you can run arc land <to-branch>
    • If you accidentally did your changes in master instead of a branch, run arc amend && git push rather than arc land

If other people have committed changes that you want to incorporate into your branch (perhaps a bugfix that you need), you can just do git pull in your feature branch.  Phabricator will do the right thing in ignoring these not-your changes.  Note that khan-dotfiles sets this up so the pull will do a rebase, which is what we want; if you don't have that setup do git pull --rebase.

The phabricator author's workflow may be helpful; it covers some corner cases not covered here.


git co -b <branchname>
<edit edit edit>
git commit
arc diff --rr reviewer1,reviewer2 [--cc person3] --verbatim

<edit based on review feedback>
git commit
arc diff

<maybe run git pull if you want some updates>
<edit + commit + arc diff some more>

arc land

Alternate day-to-day use

This is a bit easier to use since no branches are involved. You just do your work in the main branch (master). The downside is it is difficult to work on multiple features at once; you'll need multiple clones of the repo to do that.

<edit edit edit>
git commit
arc diff --rr reviewer1,reviewer2 [--cc person3] --verbatim

<edit based on review feedback>
git commit
arc diff

<maybe run git pull if you want some updates>
<edit + commit + arc diff some more>

arc amend
git push

This is very similar to the normal approach, but you do not create a new branch, and the 'land' command is a bit different.

Post-push review

If you have a change that you need to get out right away (such as a test fix), you can use this workflow to use the 'audit' (post-push review) workflow instead of the normal 'differential' (pre-push review) workflow. (DO NOT use `arc diff` with this workflow.)

<edit edit edit>
git commit
# put 'Auditors: foo,bar,baz' in the commit message
git push

As you can see, this is just like a normal commit+push, except you put a special tag in the commit message, like so:

Fix the foobaz test now that we no longer frob our foos.

I can't believe I forgot to run this test when I changed the foo-frobbing code!

Auditors: chris, james

Test plan:


Reviewing changes locally

Sometimes you may want to try out a revision locally, for example when large changes in user interaction are involved. This is really simple with Phabricator:
  1. arc patch [revision id] (e.g. arc patch D29233) will check out out the latest version of the given revision into a new branch named arcpatch-[revision id].
    You can then test locally, and quickly switch between between the revision and your other branches.
  2. After the revision has been closed, you can tidy up your branches via git branch -D arcpatch-[revision id].
    If you're tired of typing that all the time, you can run arc alias clear '!git checkout master && git branch | grep arcpatch | xargs git branch -D' and then use arc clear. (Will delete all local branches created via arc patch.)

Some special situations

Working on a sub-feature while a feature is up for review

Say you're working on feature X, and the review is dragging on but you want to get started on feature Y, which depends on feature X, while the review is happening.  To do this, make a branch off the feature branch to continue your work. You can run arc diff, just like normal, in the grandchild branch.

See "Advanced topic: Dependent Phabricator reviews," below, for more details.

Making changes in a submodule

Suppose you want to make changes to webapp/third_party/babel, which is a submodule.  If you run arc diff in that submodule, then phabricator will complain, because it doesn't know what repository to associate the submodule with.

There are two solutions:

  1. Check out the submodule separately somewhere else:
    ~/khan/submodules% git clone
    You can make the change there, and phabricator will work just fine.
    • After your changes have been approved and landed onto the master branch of the submodule, you must make a "substate commit" on the master branch. To do this:
    • cd ~/khan/webapp/third_party/babel
    • git checkout master
    • cd ~/khan/webapp
    • At this point git status will show modified: third_party/babel-khansrc (new commits)
    • git commit -nm "Substate"
    • git push
  2. Add a .arcconfig file in the sub-repo indicating what repo to use:
        "project_id": "babel",
        "conduit_uri": ""
    The project-id comes from the 'repository' field at  See webapp/third_party/gae_mini_profiler/.arcconfig for an example.  You can also find the project-id on the page, if you do not have permission to view the previous URL.
    • When you make changes directly in the submodule's subdirectory, git status will show modified: third_party/babel-khansrc (modified content) before you land your changes into the submodule. After you land your change onto the master branch of the submodule, you need to make a substate commit in the parent repo.
    • cd ~/khan/webapp
    • git commit -nm "Substate"
    • git push

Manual installation

This is only necessary if you've not used khan-dotfiles.  khan-dotfiles does all this setup for you.

First, install the necessary software and set up your path

sudo apt-get install php5-cli php5-curl         # linux only
git clone git://
git clone git://   # must be a sibling to arcanist/
export PATH=~/path/to/arcanist/khan-bin:$PATH   # put in your .bashrc or similar

If you installed khan-linter in a non-standard location (separate from where khan-dotfiles puts it), you will also need to run this command:

arc set-config linter.scriptandregex.script "~/path/to/khan-linter/ --always-exit-0 --blacklist=yes"

Advanced topic: Dependent Phabricator reviews

Say you have an upstream called master, and a feature branch F1, and a second change that depends on F1, (call it F2).
git checkout master
git checkout -b F1
# work work
git commit -a
arc diff
git checkout -b F2   # Note that F1 is set as the upstream of F1
# work work
git commit -a
arc diff   # arc will now check to see diffs against the upstream, so only the change from F1 to F2 will be posted

Now let's say you had issues in F1 from a review and you need to update the Phabricator diff.
git co F1
# fix the stuff
git commit -a --amend
arc diff   # upload updated patch
git co F2
git rebase -i F1   # rebase the contents of F2 on top of the *new* F1. You should only select the actual change on F2

F1 has set its upstream to master. So let's say you want to land F1. After landing F1, you'll want to rebase F2 onto master and change its git upstream to master.
git co master
git pull
git co F1
git rebase master
arc land --onto master  # this lands F1. at this point, F2's upstream has disappeared. we need to fix that
git co F2
git branch --set-upstream-to=master  # Now F2's upstream is master, since we landed F1!
git rebase -i master

Now, F2 is like a normal branch pointed to master. arc diff uses the upstream to determine the diff to upload to the server.


I forgot to start a new branch and now my dependent diff includes too many commits.

You need to manually specify which commit the diff should start from.

There are a few ways to do this.  Let's say you need the last three commits, e.g. through git SHA 27c7f06:
  • arc diff HEAD~3
  • arc diff --revision D123456 27c7f06
  • arc diff --update D123456 --raw-command "git diff 27c7f06"

For Phabricator Admins

See the admin page.