Arcanist User Guide: arc diff

Phorge Administrator and User Documentation (Application User Guides)

Guide to running arc diff, to send changes to Differential for review.

This article assumes you have arc installed and running; if not, see Arcanist User Guide for help getting it set up.

Before running arc diff, you should create a .arcconfig file. If someone set things up for you, they may already have done this. See Arcanist User Guide: Configuring a New Project for instructions and information.

Overview

While arc has a large number of commands that interface with various Phorge applications, the primary use of arc is to send changes for review in Differential (for more information on Differential, see Differential User Guide). If you aren't familiar with Differential, it may be instructive to read that article first to understand the big picture of how the code review workflow works.

You send changes for review by running arc diff. The rest of this document explains how to use arc diff, and how the entire review workflow operates for different version control systems.

Subversion

In Subversion, arc diff sends the uncommitted changes in the working copy for review.

To create a revision in SVN:

$ nano source_code.c # Make changes.
$ arc diff

This will prompt you for information about the revision. To later update an existing revision, just do the same thing:

$ nano source_code.c # Make more changes.
$ arc diff

This time, arc will prompt you to update the revision. Once your revision has been accepted, you can commit it like this:

$ arc commit

Git

In Git, arc diff sends all commits in a range for review. By default, this range is:

`git merge-base origin/master HEAD`..HEAD

That's a fancy way of saying "all the commits on the current branch that you haven't pushed yet". So, to create a revision in Git, run:

$ nano source_code.c  # Make changes.
$ git commit -a       # Commit changes.
$ arc diff            # Creates a new revision out of ALL unpushed commits on
                      # this branch.

The git commit step is optional. If there are uncommitted changes in the working copy then Arcanist will ask you to create a commit from them.

Since it uses all the commits on the branch, you can make several commits before sending your changes for review if you prefer.

You can specify a different commit range instead by running:

$ arc diff <commit>

This means to use the range:

`git merge-base <commit> HEAD`..HEAD

However, this is a relatively advanced feature. The default is usually correct if you aren't creating branches-on-branches, juggling remotes, etc.

To update a revision, just do the same thing:

$ nano source_code.c  # Make more changes.
$ git commit -a       # Commit them.
$ arc diff            # This prompts you to update revision information.

The git commit step is optional. If there are uncommitted changes in the working copy then Arcanist will ask you to amend them to the commit.

When your revision has been accepted, you can usually push it like this:

$ arc land <branch>   # Merges <branch> into master and pushes.

arc land makes some assumptions about your workflow which might not be true. Consult the documentation before you use it. You should also look at arc amend, which may fit your workflow better.

Mercurial

In Mercurial, arc diff sends all commits in a range for review. By default, this range is changes between the first non-outgoing parent of any revision in history and the directory state. This is a fancy way of saying "every outgoing change since the last merge". It includes any uncommitted changes in the working copy, although you will be prompted to include these.

To create a revision in Mercurial, run:

$ nano source_code.c  # Make changes.
$ hg commit           # Commit changes.
$ arc diff            # Creates a new revision out of ALL outgoing commits
                      # on this branch since the last merge.

The hg commit step is optional. If there are uncommitted changes in the working copy then Arcanist will ask you to create a commit from them.

Since it uses all the outgoing commits on the branch, you can make several commits before sending your changes for review if you prefer.

You can specify a different commit range instead by running:

$ arc diff <commit>

This means to use the range from that commit to the directory state. However, this is an advanced feature and the default is usually correct.

To update a revision, just do the same thing:

$ nano source_code.c  # Make changes.
$ hg commit           # Commit changes.
$ arc diff            # This prompts you to update revision information.

The hg commit step is optional. If there are uncommitted changes in the working copy then Arcanist will ask you to create a commit from them (or amend them to the previous commit if supported).

When your revision has been accepted, push it normally. (arc does not have push integration in Mercurial because it can't force merges and thus can't guarantee it will be able to do anything useful.)

Pushing and Closing Revisions

After changes have been accepted, you generally push them and close the revision. arc has several workflows which help with this, by:

• squashing or merging changes from a feature branch into a master branch (if relevant);
• formatting a good commit message with all the information from Differential; and
• automatically closing the revision.

You don't need to use any of these workflows: you can just run git push, hg push or svn commit and then manually close the revision from the web. However, these workflows can make common development strategies more convenient, and give you better commit messages in the repository. The workflows arc supports are:

• arc land: Works in Git if you develop in feature branches. Does a merge or squash-merge from your feature branch into some master branch, provides a detailed commit message, pushes master, and then deletes your branch.
• arc amend: Works in Git if you can't use arc land. Amends HEAD with a detailed commit message.
• arc commit: Works in Subversion. Runs svn commit with a detailed commit message.
• arc close-revision: Works anywhere, closes a revision from the CLI without going through the web UI.

You can use arc help <command> for detailed help with any of these. Differential will make a guess about a next step on accepted revisions, but it may not be the best next step for your workflow.

Phorge will also automatically close revisions if the changes are pushed to a repository that is tracked in Diffusion. Specifically, it will close revisions based on commit and tree hashes, and Differential Revision identifiers in commit messages.

If you push to an untracked repository (or arc can't figure out that it's tracked), arc land, arc amend and arc commit will implicitly run arc close-revision.

General Information

This information is not unique to a specific version control system.

Force Diff Only

You can create just a diff (rather than a revision) with --preview (or --only, but this disables other features). You can later use it to create or update a revision from the web UI.

Other Diff Sources

You can create a diff out of an arbitrary patch file by using --raw and piping it to stdin. In most cases this will only create a diff, not a revision. You can use the web UI to create a revision from the diff, or update an existing revision.

Force Create / Update

arc uses information about the working copy (like the path, branch name, local commit hashes, and local tree hashes, depending on which version control system you are using) to figure out whether you intend to create or update a revision. If it guesses incorrectly, you can force it to either create or update a revision with:

$ arc diff --create             # Force "create".
$ arc diff --update <revision>  # Force "update".

You can figure out what arc believes to be in the working copy with arc which.