Git and Arcanist¶
All of our code is stored on our own private Git repositories. For those who don’t know, Git is a VCS, which means it keeps track of every change that is made. Using Git enables us to collaborate on the code and merge all of our changes together cleanly.
There is a difference between Git and GitHub. GitHub is an online service that offers free and paid Git repositories. We have “mirrors” of our code on GitHub, meaning the code is copied directly over from our own repositories, but we do not use GitHub itself for development work.
Phabricator manages all our Git repositories, and that gives us a lot of additional features - Differential being key among those. In order to upload directly to Phabricator, we use a program called Arcanist.
Installing Git and Arcanist¶
Installing on Ubuntu¶
On Ubuntu, you can simply install Arcanist like any other package. We’ll install it along with its dependencies and related tools.
$ sudo apt install git php php-curl php-cli php-xml cppcheck arcanist
Then, we just test it out.
$ arc help
If the help list shows up, that’s it! You’re ready to go.
Installing on Linux, Alternate¶
If the above worked, do NOT follow this version of the
instructions. Just skip to next section,
If you’re on a Debian-based Linux OS, you can follow these instructions to install Arcanist. If you’re on another Linux OS, these instructions should still work, although you may need to adjust commands a little to make it work.
First, we need to install our dependencies.
$ sudo apt install git php php-curl php-cli php-xml cppcheck
Enter your password if prompted. It will want to install a few other packages. Tell it “yes” (Y) and let it run. It might take a little while.
Still in your terminal, create the folder for Arcanist to live in, and then pull in Arcanist.
$ mkdir ~/.arcanist $ cd ~/.arcanist $ git clone https://github.com/phacility/arcanist.git
Now we need to tell our system where to look for Arcanist. The easiest way
to do this is to add Arcanist’s
/bin directory to our environment
$ sudo pluma /etc/environment
Just before the last ”, insert the following, replacing USERNAME with your Ubuntu username.:
Note the colon at the beginning, which separates each entry. Your new path will probably look something like this:
Save and close pluma. Then, restart your computer. To test it out, run...
$ arc help
If you installed it wrong, you’ll see a suggestion to install the package “arc”. DON’T DO IT! That is a completely different program.
Arcanist may ask you to install additional PHP packages via apt. If you set everything up right, you’ll see arc’s help list.
Installing on Mac¶
On Mac, Git is automatically installed as part of
Command Line Tools for Xcode. If you prefer an alternative means of
installation, see Git: Getting Started Installing Git
You can install Arcanist following these instructions: Arcanist User Guide: Mac OS X
Register yourself with Git, so you’ll be credited for commits.
If you only want the given name and/or email for the current
repository, omit the
Run the following commands, substituting in your own information. Staff should use their company email here; otherwise use the email associated with your GitHub account.
$ git config --global user.name "Sam Smith" $ git config --global user.email firstname.lastname@example.org
All of our projects are preconfigured to work on Linux and Mac systems. You only need to pull them down using Git.
Decide on a place to put your repositories. I recommend creating a
repos directory in your Home folder. Wherever you want your
repositories, create and navigate to the directory in question.
On Linux or Mac, run...
$ mkdir ~/repos $ cd ~/repos
Now we need to check out a repository. You have two options for this...
- Use an SSH key (recommended).
- Use your Phabricator username and a VCS password.
Using an SSH Key¶
We need a public and private SSH key pair for this method. If you already
have one set up, find your public key, which probably has a file path like
~/.ssh/id_rsa.pub. If you have an SSH key already, skip to
Adding Your Public Key.
Creating a Keypair (Linux/Mac)¶
If you need to create a new SSH key pair, we can do that now. We start by installing OpenSSH Client, so we can log into other systems with SSH.
On Ubuntu, you can install OpenSSH via...
$ sudo apt install openssh-client
If you’re on Mac, the necessary software is already installed by default.
Next, we generate a new keypair. Be sure to enter your GitHub or company email address in place of email@example.com.
$ ssh-keygen -t rsa -b 4096 -C 'firstname.lastname@example.org'
You’ll see a message that the key pair is being generated. When prompted, press
Enter to use the default path for the key.
Finally, enter a password used for unlocking the SSH key. You’ll find the
new keypair at
Your public key is the part you share. NEVER EVER EVER share your private key (the part ending in .rsa)!
Creating a Keypair (Windows)¶
If you’re using Windows, you can create an SSH keypair using PuTTYGen or Git Bash. Two methods are described below:
Adding Your Public Key¶
Open your public key in a plain text editor, or just output it in your terminal. On Linux or Mac, you can do this via...
$ cat ~/.ssh/id_rsa.pub
On Phabricator, click your profile picture towards the right of the top menubar, and click Settings. From the menu pane on the left, select SSH Public Keys.
Next, click SSH Key Actions (upper-right) and Upload Public Key.
Paste your public key under Public Key. Then, enter a Name for the key. The name only needs to be something helpful for you to remember what key this is.
Finally, click Upload Public Key.
Using a VCS Password¶
This method is a bit easier to set up, but considerably more annoying to use. During a typical git pull or git push, you may have to enter the VCS password as many as three times!
On Phabricator, click your profile picture towards the right of the top menubar, and click Settings. From the menu pane on the left, select VCS Password.
Enter a new VCS password under New VCS Password and confirm it under Confirm VCS Password. Then, click Change Password.
Cloning the Repository¶
On Phabricator, navigate to the Diffusion app, and select for the repository you want to check out. On the repository page, look in the Details box for the Clone commands. If you’re using the VCS password, select the https:// URL. Otherwise, if you’re using the SSH key, select the ssh:// URL.
In your terminal, make sure you’re in the directory where you want to check out your repositories. On Linux or Mac, run...
$ cd ~/repos
Then, clone the repository with the
git clone URL command.
For example, to check out the PawLIB repository with SSH, use...
$ git clone ssh://email@example.com:2222/diffusion/P/pawlib-git.git
Switching Between SSH and VCS¶
If you’ve cloned a repository using one protocol, and decide you need to use the other, you can switch them out fairly easily without having to clone the repository all over again.
In the root of the repository you want to switch out, edit the file :file`.git/config`.
Look for the url = section. Swap that URL out for the one that matches the method you want to move. (Again, you can find those URLs on the Phabricator Diffusion page for the repository in question.)
After switching out the URLs, save and close the file. That’s it!
Sign In With Arcanist¶
In your terminal, navigate into the root of one of the repositories you
checked out, using
cd reponame. Once in your project directory, run
$ arc install-certificate
Go to this link and sign
in if necessary. You’ll receive a validation code. Copy and paste
Ctrl+Shift+V) the validation code into the terminal when prompted.
If you did all this correctly, you will see the message “API Token installed”.
That’s it! Repeat the Cloning the Repository section as needed to import each repository you need.