phorge-phorge/src/docs/user/userguide/arcanist_diff.diviner

@title Arcanist User Guide: arc diff
@group userguide

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

This article assumes you have `arc` installed and running; if not, see
@{article: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
@{article:Arcanist User Guide: Configuring a New Project} for instructions and
information.

= Overview =

While `arc` has a large number of commands that interface with various
Phabricator applications, the primary use of `arc` is to send changes for
review in Differential (for more information on Differential, see
@{article: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.

Phabricator 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. (You can disable this feature by disabling
"Autoclose" in the Repository configuration.)

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`.