Phabricator/Arcanist

You are probably looking for Download from Git and Gerrit/Tutorial instead.

Arcanist is a command line tool that can be used to submit, review and land (commit) patches to Git repositories which are hosted (i.e. read/write) on Phabricator itself.

Since late 2023, no Git repositories are hosted on Phabricator anymore. Thus there is no reason to use Arcanist except if you want to hack on the code of Phabricator itself.

All repositories under https://phabricator.wikimedia.org/diffusion/ live elsewhere (probably on Gerrit or GitLab). They are only mirrored to Phabricator so you can browse them in a web browser and link commits etc. from Phabricator tasks.

Installation, Setup, Use

Example content Installation Warning: 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 location (for example ~/apps or /opt) and clone the arcanist repository there. cd ~/apps # or cd /opt git clone https://phabricator.wikimedia.org/source/arcanist.git Now add ~/apps/arcanist/bin/arc 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 arc upgrade Debian / Ubuntu packages  Note: If you can, using the Git installation method above is still preferred. Wikimedia's APT repository provides outdated packages for Debian Jessie and Ubuntu Trusty. Their primary use was for our Continuous Integration servers and to avoid API compatibility problems. We originally intended 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.list.d/wikimedia.list with the following contents: ## Wikimedia APT repository deb http://apt.wikimedia.org/wikimedia jessie-wikimedia main experimental backports deb-src http://apt.wikimedia.org/wikimedia jessie-wikimedia main universe Once you've done that, update your apt cache: sudo apt-get update This likely will not work because the repositories are not signed and these packages have been unmaintained for many years. This is dangerous and will work: sudo apt-get update --allow-insecure-repositories --allow-unauthenticated Then finally: sudo apt-get install arcanist For more information about the Wikimedia APT repositories, please see wikitech:APT_repository. Updating Updating Arcanist would be apt-get update followed by apt-get upgrade  Note: Installation on Debian and Ubuntu can be done without adding the Wikimedia APT repository because arcanist is available in the official Debian repositories (though outdated). 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. Arcanist on Mac OSX Volunteer developer user:paladox has published a free Arcanist installer for mac osx, and although it is it is not officially supported by upstream or the Wikimedia Foundation, it aims to simplify the process of installing Arcanist on mac osx. Arcanist on Windows Arcanist is notoriously difficult to use on Windows, due in large part to the reliance on git which in turn relies on a well behaved POSIX environment. There are various hacks and workarounds that aim to provide a reasonable approximation of a standard Unix environment on top of the Windows platform. The most promising choices that we are currently aware of for running Arcanist on Windows are the following: As of 2017, git-for-windows is the most well-established solution for using git on Windows. Microsoft has recently began rolling out first-class support for a POSIX environment as part of the Windows Subsystem for Linux. This is essentially a Unix emulator layer that runs on top of Windows and supports a fairly complete environment based on the GNU/Linux userspace from Ubuntu. This alternative only recently became available as a "beta" feature released with the Windows 10 Anniversary Update. Volunteer developer user:paladox has published a free Arcanist installer for windows, and although it is it is not officially supported by upstream or the Wikimedia Foundation, it aims to simplify the process of installing Arcanist on Windows. This could be especially helpful if you are using an older version of Windows and are unable to install the Windows 10 Anniversary update. Setup Tell Arcanist where your default Phabricator install is (presumably the phabricator.wikimedia.org one) arc set-config default https://phabricator.wikimedia.org/ Which should respond with something like: Example: Set key 'default' = "https://phabricator.wikimedia.org/" in global config (was null). Then you should install your personal Phabricator API token. arc install-certificate Arc will prompt you to login to Phabricator via the web browser and pick up the API token from the specified location: Example: CONNECT Connecting to "https://phabricator.wikimedia.org/api/"... LOGIN TO PHABRICATOR Open this page in your browser and login to Phabricator if necessary: https://phabricator.wikimedia.org/conduit/login/ Then paste the API Token on that page below. Paste API Token from that page: When clicking a link the following webpage is presented: Grant Account Access Copy-paste the API Token below to grant access to your account. API Token: cli-01234567890abcdef012345678890 This will authorize the requesting script to act on your behalf permanently, like giving the script your account password. If you change your mind, you can revoke this token later in Settings → Conduit API Tokens. After the API Token is pasted into the arc window it should say: Example: Writing ~/.arcrc... SUCCESS! API Token installed. Using arcanist 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: # changes git commit -a arc diff The outcome should be something like: Example: Created a new Differential revision: Revision URI: https://secure.phabricator.com/D1234567 Updating an existing Differential revision (which you initially created yourself) requires performing the same steps. 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 arc land D# where # represents the revision number of the patch you are landing. Merging another author's change In the past, arc land 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 arc land 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: git clone ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/E3Experiments.git Go to the repository and try fetching some code: cd E3Experiments arc patch D3 The system will ask you: Example: 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: Example: 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: git branch -vv Example: * arcpatch-D3 be7cfd9 Merge branch 'master' of ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/E3Experiments into munaf/pef2 master e40fce0 [origin/master] Rename events.js -> communityClicks.js Further Reading Explore arc help and the User's Guide.