Bring over Arcanist documentation.

Summary: Mostly from arcanist/ and libphutil/.

src/docs/userguide/arcanist.diviner

@@ -0,0 +1,139 @@
+@title Arcanist User Guide
+@group userguide
+
+Guide to Arcanist, a command-line tool for code review and revision management.
+
+Arcanists glues together several other tools, like Differential and lint. It
+also serves as the CLI to Phabricator, and is used to get changesets into
+Differential for review.
+
+A detailed command reference is available by running ##arc help##. This
+document provides a high level overview of common workflows.
+
+Arcanist has technical, contributor-focused documentation here:
+<http://www.phabricator.com/docs/arcanist/>
+
+= Overview =
+
+Arcanist is a wrapper script that sits on top of other tools (e.g.,
+Differential, linters, unit test frameworks, SVN, and git) and provides a
+simple command-line API to manage code review and some related revision control
+operations.
+
+Arcanist allows you to do things like:
+
+  - get detailed help about available commands with ##arc help##
+  - send your code to Differential for review with ##arc diff##
+  - show pending revision information with ##arc list##
+  - find likely reviewers for a change with ##arc cover##
+  - apply changes in a revision to the working copy with ##arc patch##
+  - download a patch from Differential with ##arc export##
+  - update Git commit messages after review with ##arc amend##
+  - commit SVN changes with ##arc commit##
+
+Once you've configured lint and unit test integration, you can also:
+
+  - check your code for syntax and style errors with ##arc lint##
+  - run unit tests that cover your changes with ##arc unit##
+
+Arcanist has some advanced features as well, you can:
+
+  - execute Conduit method calls with ##arc call-conduit##
+  - create or update libphutil libraries with ##arc liberate##
+  - activate tab completion with ##arc shell-complete##
+  - install arc as a pre-commit hook with ##arc svn-hook-pre-commit## or
+    ##arc git-hook-pre-receive##
+  - ...or extend Arcanist and add new commands
+
+Except where otherwise noted, these workflows are generally agnostic to the
+underlying version control system and will work properly in git or SVN
+repositories.
+
+= Installing Arcanist =
+
+Arcanist is meant to be installed on your local machine or development server,
+i.e. whatever machine you're editing code on. It runs on Linux and Mac OS X;
+To install it, clone it and libphutil off github:
+
+  somewhere/ $ git clone git://github.com/facebook/libphutil.git
+  somewhere/ $ git clone git://github.com/facebook/arcanist.git
+
+Now add ##somewhere/arcanist/bin/arc## to your path.
+
+== Installing Tab Completion ==
+
+If you use ##bash##, you can set up tab completion by adding something like this
+to your ##.bashrc##, ##.profile## or similar:
+
+  source /path/to/arcanist/resources/shell/bash-completion
+
+= Running Arcanist =
+
+Arcanist is a context-sensitive command which you should run in a working copy,
+like ##svn## or ##git##. Generally speaking, ##arc## commands operate on changed
+files in the working copy in svn, and on the commit at HEAD in git.
+
+== SVN Basics ==
+
+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. Use a commit template similar to this one:
+
+  resources/git/commit-template.txt
+
+To **create a revision** in git:
+
+  $ nano source_code.c      # Make changes.
+  $ git commit -a           # Fill out the template.
+  $ arc diff
+
+To **update a revision** in git by amending HEAD:
+
+  $ nano source_code.c      # Make changes.
+  $ git commit -a --amend   # Amend into HEAD.
+  $ arc diff
+
+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 HEAD^^         # Update with the last two changes.
+
+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.
+
+  $ arc amend               # If you used an --amend workflow.
+
+If you used a multiple-commit workflow, you need to squash commits first with
+##git rebase -i## or similar, then amend the squashed commit.
+
+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.

src/docs/userguide/arcanist_hooks.diviner

@@ -0,0 +1,37 @@
+@title Arcanist User Guide: Repository Hooks
+@group userguide
+
+Describes how to set up Arcanist as an SVN pre-commit hook.
+
+= Installing Arcanist SVN Hooks =
+
+You can install Arcanist as an SVN pre-commit hook, to reject commits which
+contain lint errors. The immediate value of this is that syntax errors won't
+be committable, but you can block other kinds of badness with appropriate lint
+engines.
+
+To install Arcanist as a pre-commit hook, add this to your svn/hooks/pre-commit:
+
+  #!/bin/sh
+  /usr/local/bin/php -f /path/to/arcanist/bin/arc svn-hook-pre-commit $@ 1>&2
+
+Make sure you make this file executable, or you'll get an error for every commit
+with an unhelpful error message. You also need to specify the full path to PHP
+since SVN nukes ENV before executing scripts. Alternatively you can specify
+PATH explicitly.
+
+If your project is configured to run linters or lint engines which aren't part
+of Arcanist, specify where to load them from with ##--load-phutil-library##:
+
+  --load-phutil-library=/path/to/library/root
+
+Since SVN commit hooks run without access to a working copy, you'll need to keep
+one checked out somewhere and reference it with ##--load-phutil-library## if you
+build new linters or customize lint engines. For example, your hook might
+look like this:
+
+  #!/bin/sh
+  /usr/local/bin/php -f /path/to/arcanist/bin/arc svn-hook-pre-commit \
+    --load-phutil-library=/path/to/custom/lint/engine \
+    --load-phutil-library=/path/to/custom/unittest/engine \
+    $@ 1>&2

src/docs/userguide/arcanist_lint_unit.diviner

@@ -0,0 +1,85 @@
+@title Arcanist User Guide: Customizing Lint, Unit Tests and Workflows
+@group userguide
+
+Explains how to build new classes to control how Arcanist behaves.
+
+NOTE: TODO: This document is pretty trash, follow at your own risk.
+
+= Overview =
+
+Arcanist has some basic configuration options available in the ##.arcconfig##
+file (see @{article:Setting Up .arcconfig}), but it can't handle everything. If
+you want to customize Arcanist at a deeper level, you need to build new classes.
+For instance:
+
+  - if you want to configure linters, or add new linters, you need to create a
+    new class which extends @{class:ArcanistLintEngine}.
+  - if you want to integrate with a unit testing framework, you need to create a
+    new class which extends @{class:ArcanistBaseUnitTestEngine}.
+  - if you you want to change how workflows behave, or add new workflows, you
+    need to create a new class which extends @{class:ArcanistConfiguration}.
+
+Arcanist works through a sort of dependency-injection approach. For example,
+Arcanist does not run lint rules by default, but you can set **lint_engine**
+in your ##.arcconfig## to the name of a class which extends
+@{class:ArcanistLintEngine}. When running from inside your project, Arcanist
+will load this class and call methods on it in order to run lint. To make this
+work, you need to do three things:
+
+  - actually write the class;
+  - add the library where the class exists to your ##.arcconfig##;
+  - add the class name to your ##.arcconfig## as the **lint_engine**,
+    **unit_engine**, or **arcanist_configuration**.
+
+= Write the Class =
+
+(TODO)
+
+= Load the Class =
+
+To make the class loadable, you need to put the path to it in your
+##.arcconfig##, under **phutil_libraries**:
+
+  {
+    // ...
+    "phutil_libraries" : {
+      // ...
+      "my-library" : "/path/to/my/library",
+      // ...
+    }
+    // ...
+  }
+
+You can either specify an absolute path, or a path relative to the project root.
+When you run ##arc --trace##, you should see a message to the effect that it has
+loaded your library.
+
+For debugging or testing, you can also run Arcanist with the
+##--load-phutil-library## flag:
+
+  arc --load-phutil-library=/path/to/library <command>
+
+You can specify this flag more than once to load several libraries. Note that
+if you use this flag, Arcanist will ignore any libraries listed in
+##.arcconfig##.
+
+= Use the Class =
+
+This step is easy: just edit ##.arcconfig## to specify your class name as
+the appropriate configuration value.
+
+  {
+    // ...
+    "lint_engine" : "MyCustomArcanistLintEngine",
+    // ...
+  }
+
+Now, when you run Arcanist in your project, it will invoke your class when
+appropriate.
+
+For lint and unit tests, you can also use the ##--engine## flag override the
+default engine:
+
+  arc lint --engine MyCustomArcanistLintEngine
+
+This is mostly useful for debugging and testing.

src/docs/userguide/arcanist_new_project.diviner

@@ -0,0 +1,52 @@
+@title Arcanist User Guide: Configuring a New Project
+@group userguide
+
+Explains how to configure Arcanist projects with ##.arcconfig## files.
+
+= .arcconfig Basics =
+
+Arcanist uses ##.arcconfig## files to determine a number of things about project
+configuration. For instance, these are things it figures out from
+##.arcconfig##:
+
+  - where the logical root directory of a project is;
+  - which server Arcanist should send diffs to for code review; and
+  - which lint rules should be applied.
+
+An ##.arcconfig## file is a JSON file which you check into your project's root.
+A simple, valid file looks something like this:
+
+  {
+    "project_id" : "some_project_name",
+    "conduit_uri" : "https://phabricator.example.com/api/"
+  }
+
+Here's what these options mean:
+
+  - **project_id**: a human-readable string identifying the project
+  - **conduit_uri**: the Conduit API URI for the Phabricator installation that
+    Arcanist should send diffs to for review. Generally, if you access
+    Phabricator at ##https://phabricator.example.com/##, the **conduit_uri** is
+    ##https://phabricator.example.com/api/##. Be mindful about "http" vs
+    "https".
+
+For an exhaustive list of available options, see below.
+
+= Advanced .arcconfig =
+
+Other options include:
+
+  - **lint_engine**: the name of a subclass of @{class:ArcanistLintEngine},
+    which should be used to apply lint rules to this project. See (TODO).
+  - **unit_engine**: the name of a subclass of
+    @{class:ArcanistBaseUnitTestEngine}, which should be used to apply unit
+    test rules to this project. See (TODO).
+  - **arcanist_configuration**: the name of a subclass of
+    @{class: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:Installing Arcanist SVN Hooks} for
+    SVN, or (TODO) for git).
+  - **copyright_holder**: used by @{class:ArcanistLicenseLinter} to apply
+    license notices to source files.
+  - **phutil_libraries**: map of additional Phutil libraries to load at startup.