[Summary view] [Print] [Text view]

   1  @title Arcanist User Guide: arc diff
   2  @group userguide
   3  
   4  Guide to running `arc diff`, to send changes to Differential for review.
   5  
   6  This article assumes you have `arc` installed and running; if not, see
   7  @{article:Arcanist User Guide} for help getting it set up.
   8  
   9  Before running `arc diff`, you should create a `.arcconfig` file. If someone
  10  set things up for you, they may already have done this. See
  11  @{article:Arcanist User Guide: Configuring a New Project} for instructions and
  12  information.
  13  
  14  = Overview =
  15  
  16  While `arc` has a large number of commands that interface with various
  17  Phabricator applications, the primary use of `arc` is to send changes for
  18  review in Differential (for more information on Differential, see
  19  @{article:Differential User Guide}). If you aren't familiar with Differential,
  20  it may be instructive to read that article first to understand the big picture
  21  of how the code review workflow works.
  22  
  23  You send changes for review by running `arc diff`. The rest of this document
  24  explains how to use `arc diff`, and how the entire review workflow operates for
  25  different version control systems.
  26  
  27  = Subversion =
  28  
  29  In Subversion, `arc diff` sends the **uncommitted changes in the working copy**
  30  for review.
  31  
  32  To **create a revision** in SVN:
  33  
  34    $ nano source_code.c # Make changes.
  35    $ arc diff
  36  
  37  This will prompt you for information about the revision. To later **update an
  38  existing revision**, just do the same thing:
  39  
  40    $ nano source_code.c # Make more changes.
  41    $ arc diff
  42  
  43  This time, `arc` will prompt you to update the revision. Once your revision has
  44  been accepted, you can commit it like this:
  45  
  46    $ arc commit
  47  
  48  = Git =
  49  
  50  In Git, `arc diff` sends **all commits in a range** for review. By default,
  51  this range is:
  52  
  53    `git merge-base origin/master HEAD`..HEAD
  54  
  55  That's a fancy way of saying "all the commits on the current branch that
  56  you haven't pushed yet". So, to **create a revision** in Git, run:
  57  
  58    $ nano source_code.c  # Make changes.
  59    $ git commit -a       # Commit changes.
  60    $ arc diff            # Creates a new revision out of ALL unpushed commits on
  61                          # this branch.
  62  
  63  The `git commit` step is optional. If there are uncommitted changes in the
  64  working copy then Arcanist will ask you to create a commit from them.
  65  
  66  Since it uses **all** the commits on the branch, you can make several commits
  67  before sending your changes for review if you prefer.
  68  
  69  You can specify a different commit range instead by running:
  70  
  71    $ arc diff <commit>
  72  
  73  This means to use the range:
  74  
  75    `git merge-base <commit> HEAD`..HEAD
  76  
  77  However, this is a relatively advanced feature. The default is usually correct
  78  if you aren't creating branches-on-branches, juggling remotes, etc.
  79  
  80  To **update a revision**, just do the same thing:
  81  
  82    $ nano source_code.c  # Make more changes.
  83    $ git commit -a       # Commit them.
  84    $ arc diff            # This prompts you to update revision information.
  85  
  86  The `git commit` step is optional. If there are uncommitted changes in the
  87  working copy then Arcanist will ask you to amend them to the commit.
  88  
  89  When your revision has been accepted, you can usually push it like this:
  90  
  91    $ arc land <branch>   # Merges <branch> into master and pushes.
  92  
  93  `arc land` makes some assumptions about your workflow which might not be
  94  true. Consult the documentation before you use it. You should also look at
  95  `arc amend`, which may fit your workflow better.
  96  
  97  = Mercurial =
  98  
  99  In Mercurial, `arc diff` sends **all commits in a range** for review. By
 100  default, this range is changes between the first non-outgoing parent of any
 101  revision in history and the directory state. This is a fancy way of saying
 102  "every outgoing change since the last merge". It includes any uncommitted
 103  changes in the working copy, although you will be prompted to include these.
 104  
 105  To **create a revision** in Mercurial, run:
 106  
 107    $ nano source_code.c  # Make changes.
 108    $ hg commit           # Commit changes.
 109    $ arc diff            # Creates a new revision out of ALL outgoing commits
 110                          # on this branch since the last merge.
 111  
 112  The `hg commit` step is optional. If there are uncommitted changes in the
 113  working copy then Arcanist will ask you to create a commit from them.
 114  
 115  Since it uses **all** the outgoing commits on the branch, you can make several
 116  commits before sending your changes for review if you prefer.
 117  
 118  You can specify a different commit range instead by running:
 119  
 120    $ arc diff <commit>
 121  
 122  This means to use the range from that commit to the directory state. However,
 123  this is an advanced feature and the default is usually correct.
 124  
 125  To **update a revision**, just do the same thing:
 126  
 127    $ nano source_code.c  # Make changes.
 128    $ hg commit           # Commit changes.
 129    $ arc diff            # This prompts you to update revision information.
 130  
 131  The `hg commit` step is optional. If there are uncommitted changes in the
 132  working copy then Arcanist will ask you to create a commit from them (or amend
 133  them to the previous commit if supported).
 134  
 135  When your revision has been accepted, push it normally. (`arc` does not have
 136  push integration in Mercurial because it can't force merges and thus can't
 137  guarantee it will be able to do anything useful.)
 138  
 139  = Pushing and Closing Revisions =
 140  
 141  After changes have been accepted, you generally push them and close the
 142  revision. `arc` has several workflows which help with this, by:
 143  
 144    - squashing or merging changes from a feature branch into a master branch
 145      (if relevant);
 146    - formatting a good commit message with all the information from Differential;
 147      and
 148    - automatically closing the revision.
 149  
 150  You don't need to use any of these workflows: you can just run `git push`,
 151  `hg push` or `svn commit` and then manually close the revision from the web.
 152  However, these workflows can make common development strategies more convenient,
 153  and give you better commit messages in the repository. The workflows `arc`
 154  supports are:
 155  
 156    - `arc land`: Works in Git if you develop in feature branches. Does a merge
 157      or squash-merge from your feature branch into some master branch, provides
 158      a detailed commit message, pushes master, and then deletes your branch.
 159    - `arc amend`: Works in Git if you can't use `arc land`. Amends HEAD with
 160      a detailed commit message.
 161    - `arc commit`: Works in Subversion. Runs `svn commit` with a detailed commit
 162      message.
 163    - `arc close-revision`: Works anywhere, closes a revision from the CLI
 164      without going through the web UI.
 165  
 166  You can use `arc help <command>` for detailed help with any of these.
 167  Differential will make a guess about a next step on accepted revisions, but it
 168  may not be the best next step for your workflow.
 169  
 170  Phabricator will also automatically close revisions, if the changes are pushed
 171  to a repository that is tracked in Diffusion. Specifically, it will close
 172  revisions based on commit and tree hashes, and `Differential Revision`
 173  identifiers in commit messages. (You can disable this feature by disabling
 174  "Autoclose" in the Repository configuration.)
 175  
 176  If you push to an untracked repository (or `arc` can't figure out that it's
 177  tracked), `arc land`, `arc amend` and `arc commit` will implicitly run
 178  `arc close-revision`.
 179  
 180  = General Information =
 181  
 182  This information is not unique to a specific version control system.
 183  
 184  == Force Diff Only ==
 185  
 186  You can create just a diff (rather than a revision) with `--preview` (or
 187  `--only`, but this disables other features). You can later use it to create
 188  or update a revision from the web UI.
 189  
 190  == Other Diff Sources ==
 191  
 192  You can create a diff out of an arbitrary patch file by using `--raw` and piping
 193  it to stdin. In most cases this will only create a diff, not a revision. You
 194  can use the web UI to create a revision from the diff, or update an existing
 195  revision.
 196  
 197  == Force Create / Update ==
 198  
 199  `arc` uses information about the working copy (like the path, branch name, local
 200  commit hashes, and local tree hashes, depending on which version control system
 201  you are using) to figure out whether you intend to create or update a revision.
 202  If it guesses incorrectly, you can force it to either create or update a
 203  revision with:
 204  
 205    $ arc diff --create             # Force "create".
 206    $ arc diff --update <revision>  # Force "update".
 207  
 208  You can figure out what `arc` believes to be in the working copy with
 209  `arc which`.