Update arcanist documentation to reflect "land", a sane relative commit, and "--auto"

Summary: See D2080. The introduction of `arc land`, defaulting to `origin/master`, and --auto enormously simplifies the documentation.

Test Plan: Read documentation.

Reviewers: btrahan

Reviewed By: btrahan

CC: 20after4, aran

Maniphest Tasks: T894

Differential Revision: https://secure.phabricator.com/D2082

src/applications/differential/field/specification/revisionstatus/DifferentialRevisionStatusFieldSpecification.php

@@ -36,10 +36,10 @@ final class DifferentialRevisionStatusFieldSpecification
     if ($status == ArcanistDifferentialRevisionStatus::ACCEPTED) {
       switch ($diff->getSourceControlSystem()) {
         case PhabricatorRepositoryType::REPOSITORY_TYPE_MERCURIAL:
-          $next_step = '<tt>arc merge</tt>';
+          $next_step = '<tt>hg push</tt>';
           break;
         case PhabricatorRepositoryType::REPOSITORY_TYPE_GIT:
-          $next_step = '<tt>arc amend</tt> or <tt>arc merge</tt>';
+          $next_step = '<tt>arc land</tt>';
           break;
         case PhabricatorRepositoryType::REPOSITORY_TYPE_SVN:
           $next_step = '<tt>arc commit</tt>';

src/docs/userguide/arcanist.diviner

@@ -122,164 +122,9 @@ to your ##.bashrc##, ##.profile## or similar:
 
   source /path/to/arcanist/resources/shell/bash-completion
 
-= Running Arcanist =
+== Next Steps ==
 
-Arcanist is a context-sensitive command which you should run in a working copy,
+Continue by:
-like ##git##, ##hg##, or ##svn##. Generally speaking, ##arc## commands operate
-on changed files in the working copy in SVN, a commit range you specify in git,
-and outgoing changes on the current branch in Mercurial.
 
-== SVN Basics ==
+  - learning how to use `arc` to send changes for review with
-
+    {@article:Arcanist User Guide: arc diff}.
-To **create a revision** in SVN:
-
-  $ nano source_code.c # Make changes.
-  $ arc diff
-
-This will give you a diff URI, which you can use to create a new revision via
-the web UI. To later **update an existing revision**, just do the same thing:
-
-  $ nano source_code.c # Make more changes.
-  $ arc diff
-
-This time, attach the diff to your existing revision. Once your revision has
-been accepted, you can commit it like this:
-
-  $ arc commit
-
-== Git Basics ==
-
-There are a lot of ways to use git, and Arcanist is flexible enough to handle
-several of them. Git workflows divide into two major groups based on your
-**doctrine of history mutability**.
-
-Choose a **history mutability doctrine** by setting ##"immutable_history"## in
-your ##.arcconfig##. Valid values are ##true## to enforce a **conservative
-history mutability doctrine** or ##false## to enforce a **liberal history
-mutability doctrine**.
-
-A **liberal history mutability doctrine** means you rewrite local history. You
-develop in feature branches, but squash or amend before pushing by using ##git
-commit --amend## or ##git rebase -i##. Generally, one idea in the remote is
-represented by one commit. Arc will read revision information from commit
-messages, and you will finalize commits with ##arc amend##.
-
-A **conservative history mutability doctrine** means that you do not rewrite
-local history. This is similar to how Mercurial works. You develop in feature
-branches and push them without squashing commits. You do not use ##git commit
---amend## or ##git rebase -i##. Generally, one idea in the remote is represented
-by many commits. You will specify revision information via web workflows, and
-finalize commits with ##arc merge##.
-
-You can also choose no doctrine, which allows you to use both ##arc amend##
-and ##arc merge##. This isn't recommended, but Phabricator explicitly tries to
-support a broad range of git workflows. For recommendations on how to use git
-and why this choice of doctrines exists, see @{article:Recommendations on
-Revision Control}. If you aren't compelled by this and want to use a mixed
-workflow, you can pick and choose parts of each workflow.
-
-Phabricator associates commits to revisions (code reviews) by using commit
-messages and commit hashes. It will be unable to detect that you have committed
-a revision if you rebase (which changes all the hashes), and don't ##arc amend##
-or ##arc merge##, and don't ##arc diff## to update Differential with the new
-local hashes. You can use ##arc mark-committed## to explicitly mark revisions
-committed.
-
-=== Git: Conservative Mutability Doctrine ===
-
-NOTE: This doctrine is new and experimental.
-
-This section assumes you are using git with a **conservative history mutability
-doctrine** and have set ##"immutable_history" : true## in your ##.arcconfig##.
-
-To **create or update a revision** in git with a conservative doctrine:
-
-  $ git checkout master
-  $ git checkout -b feature   # Create a feature branch
-  $ git commit -m '...'       # Make a commit
-  $ arc diff master           # Send changes since master for review
-  $ git commit -m '...'       # Make more changes
-  $ git commit -m '...'
-  $ arc diff master           # Update the revision
-
-Once the revision has been accepted:
-
-  $ git checkout master       # Checkout master
-  $ arc merge feature         # Merge your feature branch with "arc merge" to
-                              # generate a rich merge commit.
-
-Now you can ##git push## or similar.
-
-=== Git: Liberal Mutability Doctrine ===
-
-This section assumes you are using git with a **liberal history mutability
-doctrine** and have set ##"immutable_history" : false## in your ##.arcconfig##.
-
-Under a liberal mutability doctrine, arc will read revision information from
-your commit message. Use a commit template similar to this one:
-
-  arcanist/resources/git/commit-template.txt
-
-The easiest way to set up the template is to check it into your repository
-somewhere and then add this to your ##.git/config## file:
-
-  [commit]
-    template = path/to/template.txt
-
-You can also configure it globally, consult the git documentation for details.
-
-To **create a revision** in git:
-
-  $ nano source_code.c      # Make changes.
-  $ git commit -a           # Fill out the template.
-  $ arc diff origin/master  # Send changes from the origin for review.
-
-To **update a revision** in git by amending HEAD:
-
-  $ nano source_code.c      # Make changes.
-  $ git commit -a --amend   # Amend into HEAD.
-  $ arc diff origin/master  # Send changes from the origin for review.
-
-To **update a revision** in git by stacking local commits:
-
-  $ nano source_code.c      # Make changes.
-  $ git commit -a -m '...'  # Make another local commit.
-  $ arc diff origin/master  # Send changes from the origin for review.
-
-To **create and update a revision** using feature branches:
-
-  $ git checkout master
-  $ git checkout -b feature # Create a branch.
-  $ nano source_code.c      # Make changes.
-  $ git commit -a           # Fill out the template.
-  $ arc diff master         # Diff changes between here and branch 'master'
-  $ nano source_code.c      # Make more changes.
-  $ git commit -a -m '...'  # Or you can amend.
-  $ arc diff master         # Updates the diff.
-
-Once your revision has been accepted, use ##arc amend## to finalize it.
-
-  $ git rebase -i           # Squash commits if necessary.
-  $ arc amend               # Update HEAD with final revision information.
-
-After amending, you can push the commit to the remote with ##git push## or
-##git svn dcommit## or via whatever other channel your project uses as
-applicable.
-
-== Mercurial ==
-
-Mercurial works similarly to git's immutable history doctrine.
-
-To **create or update** a revision in Mercurial:
-
-  $ hg commit -m '...'    # Create a commit
-  $ arc diff              # Creates or updates a revision with outgoing changes
-                          # on this branch.
-
-Once a revision has been accepted, you can finalize it with ##arc merge##:
-
-  $ arc merge             # Works like "hg merge && hg commit" but gives you a
-                          # rich commit message.
-
-This won't work if there are no remote changes on your branch, since the merge
-is linear. In this case, just skip this step. You can now "hg push" or similar.

src/docs/userguide/arcanist_diff.diviner

@@ -0,0 +1,154 @@
+@title Arcanist User Guide: arc diff
+@group userguide
+
+Guide to running `arc diff`.
+
+= Overview =
+
+This article assumes you have `arc` installed and running; if not, see
+@{article:Arcanist User Guide} for help getting it set up.
+
+This document is intended for users of `arc diff`, and is a practical
+guide to using it to send changes for review. If you are installing and
+configuring Phabricator, make sure to read the more comprehensive information in
+@{article:Arcanist User Guide: Configuring a New Project}.
+
+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          # Commit changes.
+  $ arc diff            # Creates a new revision out of ALL unpushed commits on
+                        # this branch.
+
+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          # Commit them.
+  $ arc diff            # This prompts you to update revision information.
+
+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.
+
+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.
+
+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.)
+
+= 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 `--only` (or
+`--preview`, 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 or update a 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`.

src/docs/userguide/arcanist_new_project.diviner

@@ -44,16 +44,49 @@ Other options include:
   - **arcanist_configuration**: the name of a subclass of
     @{class@arcanist:ArcanistConfiguration} which can add new command flags for
     this project or provide entirely new commands.
-  - **remote_hooks_installed**: tells Arcanist that you've set up remote hooks
-    in the master repository (see @{article:Arcanist User Guide: Repository
-    Hooks}).
   - **copyright_holder**: used by @{class@arcanist:ArcanistLicenseLinter} to
     apply license notices to source files.
+  - **immutable_history**: controls how `arc diff` behaves in Git. See below.
   - **phutil_libraries**: map of additional Phutil libraries to load at startup.
     See below for details about path resolution, or see
     @{article:libphutil Libraries User Guide} for a general introduction to
     libphutil libraries.
 
+= Immutable History =
+
+There are a lot of ways to use git, and Arcanist is flexible enough to handle
+several of them. Git workflows divide into two major groups based on your
+**doctrine of history mutability**.
+
+Choose a **history mutability doctrine** by setting ##"immutable_history"## in
+your ##.arcconfig##. Valid values are ##true## to enforce a **conservative
+history mutability doctrine** or ##false## to enforce a **liberal history
+mutability doctrine**. The default is ##false##.
+
+A **liberal history mutability doctrine** means you rewrite local history. You
+develop in feature branches, but squash or amend before pushing by using ##git
+commit --amend## or ##git rebase -i##. Generally, one idea in the remote is
+represented by one commit.
+
+A **conservative history mutability doctrine** means that you do not rewrite
+local history. This is similar to how Mercurial works. You develop in feature
+branches and push them without squashing commits. You do not use ##git commit
+--amend## or ##git rebase -i##. Generally, one idea in the remote is represented
+by many commits.
+
+Practically, these are the differences you'll see based on your setting:
+
+  - **Mutable**
+    - `arc diff` will prompt you to amend lint changes into HEAD.
+    - `arc diff` will amend the commit message in HEAD after creating a
+      revision.
+    - `arc land` will default to the `--squash` strategy.
+  - **Immutable**
+    - `arc diff` will abort if it makes lint changes.
+    - `arc diff` will not amend the commit message in HEAD after creating a
+      revision.
+    - `arc land` will default to the `--merge` strategy.
+
 = How Libraries Are Located =
 
 If you specify an external library to load, like 'examplelib', and use a