Page MenuHomestyx hydra
Files F272614

No OneTemporary
Actions

View Options

diff --git a/src/docs/userguide/arcanist.diviner b/src/docs/userguide/arcanist.diviner
index 2047816ee1..7ce88b1cb6 100644
--- a/src/docs/userguide/arcanist.diviner
+++ b/src/docs/userguide/arcanist.diviner
@@ -1,129 +1,160 @@
@title Arcanist User Guide
@group userguide
Guide to Arcanist, a command-line interface to Phabricator.
Arcanists provides command-line access to many Phabricator tools (like
Differential, Files, and Paste), integrates with static analysis ("lint") and
unit tests, and manages common workflows like getting changes into Differential
for review.
A detailed command reference is available by running ##arc help##. This
-document provides a high level overview of common workflows.
+document provides an overview of common workflows and installation.
Arcanist has technical, contributor-focused documentation here:
<http://www.phabricator.com/docs/arcanist/>
+= Quick Start =
+
+A quick start guide is available at @{article:Arcanist Quick Start}. It provides
+a much more compact summary of how to get `arc` set up and running for a new
+project. You may want to start there, and return here if you need more
+information.
+
= Overview =
Arcanist is a wrapper script that sits on top of other tools (e.g.,
Differential, linters, unit test frameworks, git, Mercurial, and SVN) and
provides a simple command-line API to manage code review and some related
revision control operations.
+For a detailed list of all available commands, run:
+
+ $ arc help
+
+For detailed information about a specific command, run:
+
+ $ arc help <command>
+
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##
+ - send your code to Differential for review with ##arc diff## (for detailed
+ instructions, see @{article:Arcanist User Guide: 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##
- push Git changes with ##arc land##
- view enhanced information about Git branches with ##arc branch##
Once you've configured lint and unit test integration, you can also:
- check your code for syntax and style errors with ##arc lint##
+ (see @{article:Arcanist User Guide: Lint})
- run unit tests that cover your changes with ##arc unit##
Arcanist integrates with other tools:
- upload and download files with ##arc upload## and ##arc download##
- create and view pastes with ##arc paste##
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, Mercurial, or
SVN repositories.
= Installing Arcanist =
Arcanist is meant to be installed on your local machine or development server --
-whatever machine you're editing code on. It runs on Linux, Mac OS X, and
+whatever machine you're editing code on. It runs on Linux,
+Mac OS X (see @{article:Arcanist User Guide: Mac OS X}), and
Windows (see @{article:Arcanist User Guide: Windows}).
Arcanist is written in PHP, so you need to install the PHP CLI first if you
don't already have it. Arcanist should run on PHP 5.2 and newer. If you don't
have PHP installed, you can download it from <http://www.php.net/>.
To install Arcanist, pick an install directory and clone the code from GitHub:
some_install_path/ $ git clone git://github.com/facebook/libphutil.git
some_install_path/ $ git clone git://github.com/facebook/arcanist.git
This should leave you with a directory structure like this
some_install_path/ # Wherever you chose to install it.
arcanist/ # Arcanist-specific code and libraries.
libphutil/ # A shared library Arcanist depends upon.
Now add ##some_install_path/arcanist/bin/## to your PATH environment variable.
When you type "arc", you should see something like this:
Usage Exception: No command provided. Try 'arc help'.
If you get that far, you've done things correctly. If you get an error or have
trouble getting this far, see these detailed guides:
- On Windows: @{article:Arcanist User Guide: Windows}
- On Mac OS X: @{article:Arcanist User Guide: Mac OS X}
You can later upgrade Arcanist and libphutil to the latest versions with
`arc upgrade`:
$ arc upgrade
== Installing Arcanist for a Team ==
-Arcanist changes quickly and doesn't currently have an auto-update mechanism,
-so it can be something of a headache to get it installed and keep people up to
-date. Here are some approaches you might be able to use:
+Arcanist changes quickly, so it can be something of a headache to get it
+installed and keep people up to date. Here are some approaches you might be
+able to use:
- Facebook does most development on development servers, which have a standard
environment and NFS mounts. Arcanist and libphutil themselves live on an
NFS mount, and the default `.bashrc` adds them to the PATH. Updating the
mount source updates everyone's versions, and new employees have a working
`arc` when they first log in.
- Another common approach is to write an install script as an action into
existing build scripts, so users can run `make install-arc` or
`ant install-arc` or similar.
- In general, if this sucks and is causing you pain, let us know (see
@{article:Give Feedback! Get Support!}). We're planning to improve this at
some point, but it's somewhat complicated to get right. While it can take a
little time to set up, we aren't getting feedback that it's a persistent
pain point, so it hasn't been a priority.
== 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
== Next Steps ==
Continue by:
+ - setting up a new project for use with `arc`, with
+ @{article:Arcanist User Guide: Configuring a New Project}; or
- learning how to use `arc` to send changes for review with
@{article:Arcanist User Guide: arc diff}.
+
+Advanced topics are also available. These are detailed guides to configuring
+technical features of `arc` that refine its behavior. You do not need to read
+them to get it working.
+
+ - @{article:Arcanist User Guide: Commit Ranges}
+ - @{article:Arcanist User Guide: Lint}
+ - @{article:Arcanist User Guide: Customizing Existing Linters}
+ - @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}
+ - @{article:Arcanist User Guide: Code Coverage}
+ - @{article:Arcanist User Guide: Repository Hooks}
\ No newline at end of file
diff --git a/src/docs/userguide/arcanist_commit_ranges.diviner b/src/docs/userguide/arcanist_commit_ranges.diviner
index 71977bb229..5f331c3f7b 100644
--- a/src/docs/userguide/arcanist_commit_ranges.diviner
+++ b/src/docs/userguide/arcanist_commit_ranges.diviner
@@ -1,305 +1,309 @@
@title Arcanist User Guide: Commit Ranges
@group userguide
Explains how commit ranges work in Arcanist.
+This is an advanced user guide which covers a complicated topic in detail. If
+you're just getting started, you don't need to look at this yet. Instead, start
+with the @{article:Arcanist User Guide}.
+
= Overview =
//In Subversion, `arc` commands always operate on the uncommitted changes in the
working copy. If you use Subversion, this document is not relevant to you.//
In Git and Mercurial, many `arc` commands (notably, `arc diff`) operate on a
range of commits beginning with some commit you specify and ending with the
working copy state.
Since the end of the range is fixed (the working copy state), you only need to
specify the beginning of the range. This is called the "base commit". You can do
this explicitly when you run commands:
$ arc diff HEAD^ # git: just the most recent commit
$ arc diff .^ # hg: just the most recent commit
You can also configure `arc` so it defaults to some base commit, or figures out
the base commit using a (potentially sophisticated) ruleset.
NOTE: This document describes a new mechanism for determining base commits. It
is subject to change. There are currently several other mechanisms available as
well, mentioned in other documents. As this mechanism matures, it should replace
other mechanisms and defaults.
= Configuring Base Commit Rules =
Base commit rule configuration may be more complicated than you expect. This is
because people use many different workflows in Git and Mercurial, and have very
different expectations about what base commit `arc` should pick when run. To
make matters worse, some of the most common ways of thinking about which commits
represent a change are incompatible when selecting defaults.
Historically, we tried to use a number of heuristics and simpler approaches to
determine the base commit, but there is so much diversity in how people think
about version control and what they expect to happen that some users were always
unhappy.
Although ruleset configuration is fairly complex, it's powerful enough that you
should be able to get exactly the behavior you want.
To determine the base commit, `arc` processes //rules// one at a time until it
gets a match (a rule which identifies a valid commit). The first match is the
base commit that is used to determine the beginning of the commit range.
A //rule// looks like this:
arc:upstream
A rule may //match//, meaning that it identifies some valid commit in the
working copy, or //fail//, meaning that it does not identify a valid commit. For
instance, the rule `arc:upstream` will //match// if the current Git branch
tracks an upstream branch, but //fail// if the current Git branch does not track
an upstream branch, or the working copy isn't a Git working copy. When a rule
fails, processing continues with the next rule. Some rules can never match but
produce useful side effects instead. These are described below.
A //ruleset// is a comma-separated list of rules:
arc:upstream, arc:prompt
`arc` reads five rulesets:
# `args`, specified with `--base <ruleset>` on the command line when you run
a command. This ruleset is processed first.
# `local`, specified with `arc set-config --local base <ruleset>`. This
ruleset is local to the working copy where it is set, and is processed
second.
# `project`, specified by setting the "base" key in `.arcconfig`. This
ruleset is bound to the project where it is configured, and is processed
third.
# `global`, specified with `arc set-config base <ruleset>`. This ruleset is
global for the current user, and is processed fourth.
# `system`, specified in a system-wide configuration file. This ruleset is
global for all users on the system, and is processed last.
The rules in each ruleset are processed one at a time until a valid base commit
is found. Valid rules are listed below. In this list, "*" means "any string".
- `git:*` Use the specified symbolic commit, if it exists.
- `git:merge-base(*)` Use the merge-base of HEAD and the specified symbolic
commit, if it exists.
- `git:branch-unique(*)` Attempt to select changes unique to this branch (that
is, changes between the branch point and HEAD). This rule is complicated and
has limitations, see below for a detailed description.
- `hg:*` Use the specified symbolic commit, if it exists.
- `hg:gca(*)` Use the greatest common ancestor of `.` and the specified
symbolic commit, if it exists.
- `arc:upstream` Use the merge-base of the current branch's upstream and
HEAD, if it exists. (git-only)
- `arc:outgoing` Use the most recent non-outgoing ancestor of the working
copy parent. (hg-only)
- `arc:exec(*)` Execute the specified command. The command should determine
the base revision to use and print it to stdout, then exit with return code
0. If the command exits with another return code, the rule will fail. The
command will be executed with the root directory of the working copy as the
current working directory.
- `arc:bookmark` Use the most recent non-outgoing ancestor of the working
copy parent or the most recent bookmark, whichever is more recent. This
rule is complicated and has limitations, see below for a detailed
description.
- `arc:amended` Use the current commit (`HEAD` in Git, or `.` in Mercurial) if
it has been amended to include a "Differential Revision:" field. Otherwise,
fail.
- `arc:prompt` Prompt the user to provide a commit.
- `arc:empty` Use the empty state (as though the repository were completely
empty, the range will include every commit that is an ancestor of the
working copy).
Rules are also available which change the processing order of rulesets:
- `arc:args`, `arc:local`, `arc:project`, `arc:global`, `arc:system` Stop
processing the current ruleset and begin processing the specified ruleset.
The current ruleset will resume processing after the specified ruleset is
exhausted.
- `arc:yield` Stop processing the current ruleset and begin processing the
next ruleset. The current ruleset will resume processing after other
rulesets have processed or when it next appears in the processing order,
whichever comes first.
- `arc:halt` Stops processing all rules. This will cause the command you ran
to fail, but can be used to avoid running rules which would otherwise
be processed later.
Additionally, there are some rules which are probably useful mostly for testing
or debugging rulesets:
- `arc:verbose` Turns on verbose logging of rule processing.
- `arc:skip` This rule has no effect.
- `literal:*` Use the specified commit literally. Almost certainly wrong in
production rules.
= Examples =
Diff against `origin/master` if it exists, and prompt if it doesn't:
git:merge-base(origin/master), arc:prompt
Diff against the upstream if it exists, or just use the last commit if it
doesn't:
arc:upstream, git:HEAD^
As a user, ignore project rules and always use my rules:
(local) arc:global, arc:halt
As a project maintainer, respect user rules over project rules:
(project) arc:yield, <defaults>
Debug your rules:
$ arc diff --base arc:verbose
Understand rules processing:
$ arc which
$ arc which --base '<ruleset>'
$ arc which --base 'arc:verbose, <ruleset>'
= Detailed Rule Descriptions =
Some rules have complex operation, described here in more detail. These rules
are advanced features for expert users wishing to optimize their workflow and
save a little typing. You do not need to understand the behavior of these rules
to use `arc` (you can always specify a base commit explicitly).
== git:branch-unique(*) ==
This rule only works in Git.
This rule tries to find commits that are unique to the current branch. It is
most likely to be useful if you develop using one branch per feature, update
changes by amending commits (instead of stacking commits) and merge changes by
rebasing (instead of merging).
The rule operates by first determining the merge-base of the specified commit
and HEAD, if it exists. If no such commit exists, the rule fails. If such a
commit exists, the rule counts how many branches contain HEAD, then walks from
HEAD to the merge-base commit, counting how many branches contain each commit.
It stops when it finds a commit which appears on more branches than HEAD,
or when it reaches the merge-base commit.
This rule works well for trees that look like this:
| * Commit B1, on branch "subfeature" (HEAD)
| /
| * Commit A1, on branch "feature"
|/
* Commit M1, on branch "master"
|
This tree represents using feature branches to develop one feature ("feature"),
and then creating a sub-branch to develop a dependent feature ("subfeature").
Normally, if you run `arc diff` on branch "subfeature" (with HEAD at `B1`), a
rule like `arc:merge-base(master)` will select `M1` as the base commit and thus
incorrectly include `A1` in the commit range.
For trees like this, `git:branch-unique(master)` will instead select `A1` as the
base commit (because it is the first commit between `B1` and `M1` which appears
on more branches than `B1` -- `B1` appears on only "subfeature" while `A1`
appears on "subfeature" and "feature") and include only `B1` in the commit
range.
The rule will also do the right thing when run from "feature" in this case.
However, this rule will select the wrong commit range in some cases. For
instance, it will do the wrong thing in this tree:
|
| * Commit A2, on branch "feature" (HEAD)
| |
| | * Commit B1, on branch "subfeature"
| |/
| * Commit A1, on branch "feature"
|/
* Commit M1, on branch "master"
|
This tree represents making another commit (`A2`) on "feature", on top of `A1`.
Here, when `arc diff` is run from branch "feature" (with HEAD at `A2`), this
rule will incorrectly select only `A2` because `A2` (which is HEAD) appears on
one branch ("feature") while `A1` appears on two branches ("feature",
"subfeature").
You can avoid this problem by amending changes into `A1` instead of adding new
commits, or by rebasing "subfeature" before running `arc diff`.
This rule will also select the wrong commit range in a tree like this:
|
| * Commit A1', on branch "feature", created by amending A1
| |
| | * Commit B1, on branch "subfeature" (HEAD)
| |/
| o Commit A1, no longer on "feature" but still on "subfeature"
|/
* Commit M1, on branch "master"
|
This tree represents amending `A1` without rebasing "subfeature", so that `A1`
is no longer on "feature" (replaced with `A1'`) but still on "subfeature". In
this case, running `arc diff` from "subfeature" will incorrectly select both
`B1` and `A1`, because they now are contained by the same number of branches.
You can avoid this problem by rebasing sub-branches before running `arc diff`,
or by using a rule like `arc:amended` before `git:branch-unique(*)`.
== arc:bookmark ==
This rule only works in Mercurial.
This rule finds outgoing changes, but stops when it encounters a bookmark. It is
most likely to be useful if you use one bookmark per feature.
This rule operates like `arc:outgoing`, but then walks the commits between
`.` and the selected base commit. It stops when it encounters a bookmark. For
example, if you have a tree like this:
|
| * C4 (outgoing, bookmark: stripes)
| |
| * C3 (outgoing, bookmark: zebra)
| |
| * C2 (outgoing, no bookmark)
|/
* C1 (pushed, no bookmark)
|
When run from `C4`, this rule will select just `C4`, stopping on `C3` because
it has a different bookmark. When run from `C3`, it will select `C2` and `C3`.
However, this rule will select the wrong commit range in some cases (for
example, if the "zebra" bookmark has moved on, the rule will no longer stop on
`C3` and will select `C2`, `C3` and `C4` when run from `C4`).
== arc:exec(*) ==
This rule runs some external script or shell command. It is intended for
advanced users who want specialized behavior that can't be expressed with other
rules.
To use this rule, provide some script or shell command. For example:
arc:exec(git merge-base origin/master HEAD)
arc:exec(/path/to/some/script.sh)
The command will be executed with the working copy as its working directory,
and passed no arguments. To //match//, it should print the name of a base commit
on stdout and then exit with return code 0. To //fail//, it should exit with
any other return code.
= Next Steps =
Continue by:
- learning about `arc diff` in more detail with
@{article:Arcanist User Guide: arc diff}; or
- returning to @{article:Arcanist User Guide}.
diff --git a/src/docs/userguide/arcanist_coverage.diviner b/src/docs/userguide/arcanist_coverage.diviner
index bcb29e5b48..0f28258d89 100644
--- a/src/docs/userguide/arcanist_coverage.diviner
+++ b/src/docs/userguide/arcanist_coverage.diviner
@@ -1,60 +1,69 @@
@title Arcanist User Guide: Code Coverage
@group userguide
Explains code coverage features in Arcanist and Phabricator.
+This is a configuration guide that helps you set up advanced features. If you're
+just getting started, you don't need to look at this yet. Instead, start with
+the @{article:Arcanist User Guide}.
+
+Before you can configure coverage features, you must set up unit test
+integration. For instructions, see @{article:Arcanist User Guide: Configuring
+a New Project} and @{article:Arcanist User Guide: Customizing
+Lint, Unit Tests and Workflows}.
+
= Using Coverage Features =
If your project has unit tests with coverage integration (see below for
instructions on setting it up), you can use "arc" to show coverage reports.
For example:
arc unit --detailed-coverage src/some/file.php
Depending on how your test engine is configured, this will run tests relevant
to ##src/some/file.php## and give you a detailed coverage report.
If the test engine enables coverage by default, it will be uploaded to
Differential and displayed in the right gutter when viewing diffs.
= Enabling Coverage for libphutil, Arcanist and Phabricator =
If you're contributing, libphutil, Arcanist and Phabricator support coverage if
you install Xdebug:
http://xdebug.org/
It should be sufficient to correctly install Xdebug; coverage information will
be automatically enabled.
= Building Coverage Support =
To add coverage support to a unit test engine, just call ##setCoverage()## when
building @{class@arcanist:ArcanistUnitTestResult} objects. Provide a map of
file names (relative to the working copy root) to coverage report strings.
Coverage report strings look like this:
NNNNNCCCNNNNNNNNCCCCCCNNNUUUNNNNN
Each line in the file is represented by a character. Valid characters are:
- **N** Not executable. This is a comment or whitespace which should be
ignored when computing test coverage.
- **C** Covered. This line has test coverage.
- **U** Uncovered. This line is executable but has no test coverage.
- **X** Unreachable. If your coverage analysis can detect unreachable code,
you can report it here.
This format is intended to be as simple as possible. A valid coverage result
might look like this:
array(
'src/example.php' => 'NNCNNNCNUNNNUNUNUNUNUNC',
'src/other.php' => 'NNUNNNUNCNNNUNUNCNCNCNU',
);
You may also want to filter coverage information to the paths passed to the
unit test engine. See @{class@arcanist:ArcanistPhutilTestCase} and
@{class@arcanist:PhutilUnitTestEngine} for an example of coverage integration
in PHP using Xdebug.
\ No newline at end of file
diff --git a/src/docs/userguide/arcanist_diff.diviner b/src/docs/userguide/arcanist_diff.diviner
index 2396b61e3e..fcfbdf778d 100644
--- a/src/docs/userguide/arcanist_diff.diviner
+++ b/src/docs/userguide/arcanist_diff.diviner
@@ -1,196 +1,196 @@
@title Arcanist User Guide: arc diff
@group userguide
-Guide to running `arc diff`.
-
-= Overview =
+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.
-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}.
+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 # 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.)
= 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`.
diff --git a/src/docs/userguide/arcanist_extending_lint.diviner b/src/docs/userguide/arcanist_extending_lint.diviner
index 58682c0735..b10b47e9cb 100644
--- a/src/docs/userguide/arcanist_extending_lint.diviner
+++ b/src/docs/userguide/arcanist_extending_lint.diviner
@@ -1,106 +1,114 @@
@title Arcanist User Guide: Customizing Existing Linters
@group userguide
Explains how to customize existing linters.
+This is a configuration guide that helps you set up advanced features. If you're
+just getting started, you don't need to look at this yet. Instead, start with
+the @{article:Arcanist User Guide}.
+
+This guide explains how to refine lint behavior. To configure lint in the first
+place, see @{article:Arcanist User Guide: Configuring a New Project} and
+@{article:Arcanist User Guide: Lint}.
+
= Overview =
Arcanist ships with a number of linters which you may want to reuse in whole
or in part in other projects. This document explains how to customize existing
linters for use in new engines.
First, you should set up an engine by following the instructions in
@{article:Arcanist User Guide: Lint} and possibly
@{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}.
Then, follow this guide to customize linters.
= General Guidelines =
You should customize linters by configuring or composing them, not by extending
them -- their implementations are not necessarily stable. If a linter's
configuration options aren't flexible enough to meet your needs, sending a patch
which improves its configurability is better than one that makes it
nonfinal.
= Changing Rule Severities =
By default, most linters raise lint messages as errors. You may want to reduce
the severity of some messages (e.g., reduce errors to warnings). Do this by
calling ##setCustomSeverityMap()##:
$linter = new ArcanistTextLinter();
// Change "missing newline at end of file" message from error to warning.
$linter->setCustomSeverityMap(
array(
ArcanistTextLinter::LINT_EOF_NEWLINE
=> ArcanistLintSeverity::SEVERITY_WARNING,
));
See @{class@arcanist:ArcanistLintSeverity} for a list of available severity
constants.
= Disabling Rules =
To disable rules entirely, set their severities to ##SEVERITY_DISABLED##:
$linter = new ArcanistTextLinter();
// Disable "Tab Literal" message.
$linter->setCustomSeverityMap(
array(
ArcanistTextLinter::LINT_TAB_LITERAL
=> ArcanistLintSeverity::SEVERITY_DISABLED,
));
= Running Multiple Rulesets =
If you want to run the same linter on different types of files but vary the
configuration based on the file type, just instantiate it twice and configure
each instance appropriately. For instance, this will enforce different column
widths on different languages:
$linters = array();
$text_80col_linter = new ArcanistTextLinter();
$linters[] = $text_80col_linter;
$text_120col_linter = new ArcanistTextLinter();
$text_120col_linter->setMaxLineLength(120);
$linters[] = $text_120col_linter;
foreach ($paths as $path) {
// Warn on JS/CSS lines longer than 80 columns.
if (preg_match('/\.(js|css)$/', $path)) {
$text_80col_linter->addPath($path);
}
// Warn on Java lines longer than 120 columns.
if (preg_match('/\.java$/', $path)) {
$text_120col_linter->addPath($path);
}
}
// ...
return $linters;
= Customizing Specific Linters =
Some linters are specifically customizable or configurable. Some common
options are documented here, consult class documentation for complete
information.
== ArcanistTextLinter ==
- Use ##setMaxLineLength()## to change the 80-column warning to something
else.
== ArcanistXHPASTLinter ==
- Use ##lint.xhpast.naminghook## in ##.arcconfig## to override naming
convention rules. See @{class@arcanist:ArcanistXHPASTLintNamingHook}
for details, and @{class:PhabricatorSymbolNameLinter} for an example.
- Use ##getXHPASTTreeForPath()## to reuse the AAST in other linters.
diff --git a/src/docs/userguide/arcanist_lint.diviner b/src/docs/userguide/arcanist_lint.diviner
index d82312165b..760b262a50 100644
--- a/src/docs/userguide/arcanist_lint.diviner
+++ b/src/docs/userguide/arcanist_lint.diviner
@@ -1,190 +1,198 @@
@title Arcanist User Guide: Lint
@group userguide
Guide to lint, linters, and linter configuration.
+This is a configuration guide that helps you set up advanced features. If you're
+just getting started, you don't need to look at this yet. Instead, start with
+the @{article:Arcanist User Guide}.
+
+This guide explains how lint works when configured in an `arc` project. If
+you haven't set up a project yet, do that first. For instructions, see
+@{article:Arcanist User Guide: Configuring a New Project}.
+
= Overview =
"Lint" refers to a general class of programming tools which analyze source code
and raise warnings and errors about it. For example, a linter might raise
warnings about syntax errors, uses of undeclared variables, calls to deprecated
functions, spacing and formatting conventions, misuse of scope, implicit
fallthrough in switch statements, missing license headers, use of dangerous
language features, or a variety of other issues.
Integrating lint into your development pipeline has two major benefits:
- you can detect and prevent a large class of programming errors; and
- you can simplify code review by addressing many mechanical and formatting
problems automatically.
When arc is integrated with a lint toolkit, it enables the `arc lint` command
and runs lint on changes during `arc diff`. The user is prompted to fix errors
and warnings before sending their code for review, and lint issues which are
not fixed are visible during review.
There are many lint and static analysis tools available for a wide variety of
languages. Arcanist ships with bindings for many popular tools, and you can
write new bindings fairly easily if you have custom tools.
= Available Linters =
Arcanist ships with bindings for these linters:
- [[http://www.jshint.com/ | JSHint]], a Javascript linter based on JSHint.
See @{class@arcanist:ArcanistJSHintLinter}.
- [[http://pypi.python.org/pypi/pep8 | PEP8]], a Python linter.
See @{class@arcanist:ArcanistPEP8Linter}.
- [[http://pypi.python.org/pypi/pyflakes | Pyflakes]], another Python linter.
See @{class@arcanist:ArcanistPyFlakesLinter}.
- [[http://pypi.python.org/pypi/pylint | Pylint]], yet another Python linter.
See @{class@arcanist:ArcanistPyLintLinter}.
- [[http://pear.php.net/package/PHP_CodeSniffer | PHP CodeSniffer]], a
PHP linter. See @{class@arcanist:ArcanistPhpcsLinter}.
Arcanist also ships with generic bindings which can be configured to parse the
output of a broad range of lint programs:
- @{class@arcanist:ArcanistScriptAndRegexLinter}, which runs a script and
parses its output with a regular expression.
- @{class@arcanist:ArcanistConduitLinter}, which invokes a linter over
Conduit and can allow you to build client/server linters.
Additionally, Arcanist ships with some general purpose linters:
- @{class@arcanist:ArcanistTextLinter}, which enforces basic things like
trailing whitespace, DOS newlines, file encoding, line widths, terminal
newlines, and tab literals.
- @{class@arcanist:ArcanistSpellingLinter}, which can detect common spelling
mistakes.
- @{class@arcanist:ArcanistFilenameLinter}, which can enforce generally
sensible rules about not giving files nonsense names.
- @{class@arcanist:ArcanistLicenseLinter.php}, which can make sure license
headers are applied to all source files.
- @{class@arcanist:ArcanistNoLintLinter}, which can disable lint for files
marked unlintable.
- @{class@arcanist:ArcanistGeneratedLinter}, which can disable lint for
generated files.
Finally, Arcanist has special-purpose linters:
- @{class@arcanist:ArcanistXHPASTLinter}, the PHP linter used by Phabricator
itself. This linter is powerful, but somewhat rigid (it enforces phutil
rules and isn't very configurable for other rulesets).
- @{class@arcanist:ArcanistPhutilLibraryLinter}, which enforces phutil library
layout rules.
You can add support for new linters in three ways:
- write new bindings and contribute them to the upstream;
- write new bindings and install them alongside Arcanist; or
- use a generic binding like @{class@arcanist:ArcanistScriptAndRegexLinter}
and drive the integration through configuration.
= Configuring Lint =
Arcanist's lint integration involves two major components: linters and lint
engines.
Linters themselves are programs which detect problems in a source file. Usually
a linter is an external script, which Arcanist runs and passes a path to, like
`jshint` or `pep8.py`. The script emits some messages, and Arcanist parses
the output into structured errors. A piece of glue code (like
@{class@arcanist:ArcanistJSHintLinter} or
@{class@arcanist:ArcanistPEP8Linter}) handles calling the external script and
interpreting its output.
Lint engines coordinate linters, and decide which linters should run on which
files. For instance, you might want to run `jshint` on all your `.js` files,
and `pep8.py` on all your `.py` files. And you might not want to lint anything
in `externals/` or `third-party/`, and maybe there are other files which you
want to exclude or apply special rules for.
To configure arc for lint, you specify the name of a lint engine, and possibly
provide some additional configuration. To name a lint engine, set `lint.engine`
in your `.arcconfig` to the name of a class which extends
@{class@arcanist:ArcanistLintEngine}. For more information on `.arcconfig`, see
@{article:Arcanist User Guide: Configuring a New Project}.
You can also set a default lint engine by setting `lint.engine` in your global
user config with `arc set-config lint.engine`, or specify one explicitly with
`arc lint --engine <engine>`.
The available engines are:
- @{class@arcanist:ComprehensiveLintEngine}, which runs a wide array of
linters on many types of files. This is probably of limited use in any real
project because it is overbroad, but is a good starting point for getting
lint doing things.
- @{class@arcanist:ArcanistSingleLintEngine}, which runs a single linter on
every file unconditionally. This can be used with a glue linter like
@{class@arcanist:ArcanistScriptAndRegexLinter} to put engine logic in an
external script.
- A custom engine you write. For most projects, lint rules are sufficiently
specialized that this is the best option. For instructions on writing a
custom lint engine, see
@{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}
and @{class@arcanist:ExampleLintEngine}.
= Using Lint to Improve Code Review =
Code review is most valuable when it's about the big ideas in a change. It is
substantially less valuable when it devolves into nitpicking over style,
formatting, and naming conventions.
The best response to receiving a review request full of style problems is
probably to reject it immediately, point the author at your coding convention
documentation, and ask them to fix it before sending it for review. But even
this is a pretty negative experience for both parties, and less experienced
reviewers sometimes go through the whole review and point out every problem
individually.
Lint can greatly reduce the negativity of this whole experience (and the amount
of time wasted arguing about these things) by enforcing style and formatting
rules automatically. Arcanist supports linters that not only raise warnings
about these problems, but provide patches and fix the problems for the author --
before the code goes to review.
Good linter integration means that code is pretty much mechanically correct by
the time any reviewer sees it, provides clear rules about style which are
especially helpful to new authors, and has the overall effect of pushing
discussion away from stylistic nitpicks and toward useful examination of large
ideas.
It can also provide a straightforward solution to arguments about style:
- If a rule is important enough that it should be enforced, the proponent must
add it to lint so it is automatically detected or fixed in the future and
no one has to argue about it ever again.
- If it's not important enough for them to do the legwork to add it to lint,
they have to stop complaining about it.
This may or may not be an appropriate methodology to adopt at your organization,
but it generally puts the incentives in the right places.
= Philosophy of Lint =
Some general thoughts on how to develop lint effectively, based on building
lint tools at Facebook:
- Don't write regex-based linters to enforce language rules. Use a real parser
or AST-based tool. This is not a domain you can get right at any nontrivial
complexity with raw regexes. That is not a challenge. Just don't do this.
- False positives are pretty bad and should be avoided. You should aim to
implement only rules that have very few false positives, and provide ways to
mark false positives as OK. If running lint always raises 30 warnings about
irrelevant nonsense, it greatly devalues the tool.
- Move toward autocorrect rules. Most linters do not automatically correct
the problems they detect, but Arcanist supports this and it's quite
valuable to have the linter not only say "the convention is to put a space
after comma in a function call" but to fix it for you.
= Next Steps =
Continue by:
- integrating and customizing built-in linters and lint bindings with
@{article:Arcanist User Guide: Customizing Existing Linters}; or
- learning how to add new linters and lint engines with
@{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}.
diff --git a/src/docs/userguide/arcanist_lint_unit.diviner b/src/docs/userguide/arcanist_lint_unit.diviner
index 0b24008476..06a49aae23 100644
--- a/src/docs/userguide/arcanist_lint_unit.diviner
+++ b/src/docs/userguide/arcanist_lint_unit.diviner
@@ -1,89 +1,93 @@
@title Arcanist User Guide: Customizing Lint, Unit Tests and Workflows
@group userguide
Explains how to build new classes to control how Arcanist behaves.
+This is a configuration guide that helps you set up advanced features. If you're
+just getting started, you don't need to look at this yet. Instead, start with
+the @{article:Arcanist User Guide}.
+
= Overview =
Arcanist has some basic configuration options available in the `.arcconfig`
file (see @{article:Arcanist User Guide: Configuring a New Project}), 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@arcanist:ArcanistLintEngine}.
- if you want to integrate with a unit testing framework, you need to create a
new class which extends @{class@arcanist:ArcanistBaseUnitTestEngine}.
- if you you want to change how workflows behave, or add new workflows, you
need to create a new class which extends
@{class@arcanist: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@arcanist: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**.
= Create a libphutil Library =
If you haven't created a library for the class to live in yet, you need to do
that first. Follow the instructions in @{article:libphutil Libraries User Guide},
then make the library loadable by adding it to your ##.arcconfig## like this:
{
// ...
"load" : [
// ...
"/path/to/my/library", // Absolute path
"support/arcanist", // Relative path in this project
// ...
]
// ...
}
You can either specify an absolute path, or a path relative to the project root.
When you run ##arc list --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" : "CustomArcanistLintEngine",
// ...
}
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.
= Next Steps =
- Browse the source for an example lint engine at
@{class@arcanist:ExampleLintEngine}; or
- learn how to reuse existing linters by reading
@{article:Arcanist User Guide: Customizing Existing Linters}.
diff --git a/src/docs/userguide/arcanist_mac_os_x.diviner b/src/docs/userguide/arcanist_mac_os_x.diviner
index b8c2fdcc7e..a34adfbf5d 100644
--- a/src/docs/userguide/arcanist_mac_os_x.diviner
+++ b/src/docs/userguide/arcanist_mac_os_x.diviner
@@ -1,26 +1,31 @@
@title Arcanist User Guide: Mac OS X
@group userguide
Explains how to install Arcanist on Mac OS X.
= Required Components =
You need to install:
- PHP, which should be installed by default.
- Arcanist itself, see @{article:Arcanist User Guide}.
- SVN, Git, or Mercurial.
Then, configure:
- Your PATH environmental variable should include `arcanist/bin`, and
`php` and your VCS command (`svn`, `hg`, `git`) should be in PATH. When you
type `php`, `arc`, or (for example) `git` from the command line, they should
all do something.
- Your EDITOR environmental variable should point at some valid CLI editor,
like `nano`, which is the best editor.
You can edit your `~/.profile` to permanently configure environmental variables.
Now you should be able to run `arc` like a normal command.
+= Next Steps =
+
+Continue by:
+
+ - returning to @{article:Arcanist User Guide}.
diff --git a/src/docs/userguide/arcanist_new_project.diviner b/src/docs/userguide/arcanist_new_project.diviner
index 941c5c72f2..19eb5facf1 100644
--- a/src/docs/userguide/arcanist_new_project.diviner
+++ b/src/docs/userguide/arcanist_new_project.diviner
@@ -1,195 +1,203 @@
@title Arcanist User Guide: Configuring a New Project
@group userguide
-Explains how to configure Arcanist projects with ##.arcconfig## files.
-
-= Overview =
-
-You can run `arc` commands that require a working copy in any Git, Subversion
-or Mercurial working copy, but some features won't work unless you set up an
-`.arcconfig` file to configure settings for the project. Creating this file is
-easy and only takes a few minutes.
-
-Without `.arcconfig`:
-
- - You will need to set a default Phabricator URI with
- `arc set-config default <uri>`, or specify an explicit URI
- with `--conduit-uri` each time you run a command.
- - You will not be able to run linters through arc unless you pass `--engine`
- explicitly.
- - You will not be able to customize certain linter parameters even with
- `--engine`.
- - You will not be able to run unit tests through arc unless you pass
- `--engine` explicitly.
- - You will not be able to trigger lint and unit integration through
- `arc diff`.
- - You will not be able to put Git working copies into immutable history mode
- (see below).
- - You will not be able to specify a repository encoding. UTF-8 will be assumed
- if you do not pass `--encoding`.
- - You will not be able to add plugins to arc to modify existing workflows or
- add new ones.
- - You will not be able to load additional libraries unless you specify them
- explicitly with `--load-phutil-library`.
- - Symbol index integration, which allows users to click function or class
- names in Differential and jump to their definitions, will not work.
- - `arc patch` will be unable to detect that you are applying changes to the
- wrong project.
- - In Subversion, `arc` will be unable to determine the canonical root
- of a project, and will assume it is the working directory (in Subversion
- prior to 1.7) or the root of the checkout (in Subversion after 1.7). This
- means the paths of files in diffs won't be anchored to the same place,
- and will have different amounts of path context, which may be confusing for
- reviewers and will sometimes prevent patches from applying properly if they
- are applied against a different directory than they were generated from.
- - In Subversion, `arc` will be unable to guess that you intend to update
- an existing revision; you must use `--update` explicitly or `--preview`
- and attach diffs via the web interface.
+Explains how to configure Arcanist projects with `.arcconfig` files.
= .arcconfig Basics =
+An ##.arcconfig## file is a JSON file which you check into your project's root.
+
Arcanist uses ##.arcconfig## files to determine a number of things about project
-configuration. For instance, these are things it figures out from
+configuration. For instance, these are some of the 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/"
}
Here's what these options mean:
- **project_id**: a human-readable string identifying the project
- **conduit_uri**: the URI for the Phabricator installation that Arcanist
should send diffs to for review. Be mindful about "http" vs "https".
For an exhaustive list of available options, see below.
+NOTE: You should commit your `.arcconfig` file! It contains project
+configuration, not user configuration.
+
= Advanced .arcconfig =
Other options include:
- **lint.engine**: the name of a subclass of
@{class@arcanist:ArcanistLintEngine}, which should be used to apply lint
rules to this project. See @{article:Arcanist User Guide: Lint}.
- **unit.engine**: the name of a subclass of
@{class@arcanist:ArcanistBaseUnitTestEngine}, which should be used to apply
unit test rules to this project. See
@{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}.
- **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.
- **history.immutable**: controls how `arc diff` and some other commands
behave in Git and Mercurial. See below.
- **load**: list 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.
= History Mutability =
Arcanist workflows run in two broad modes: either history is //mutable// or
//immutable//. Under a //mutable// history, `arc` commands may rewrite the
working copy history; under an //immutable// history, they may not.
You control history mutability by setting `history.immutable` to `true` or
`false` in your configuration. By default, it is `false` in Git (i.e.,
//mutable//) and `true` in Mercurial (i.e., //immutable//). The sections below
explain how these settings affect workflows.
== History Mutability: Git ==
In a workflow with //mutable// history, you rewrite local history. You develop
in feature branches, but squash or amend before pushing by using ##git commit
--amend##, ##git rebase -i##, or `git merge --squash`. Generally, one idea in
the remote is represented by one commit.
In a workflow with //immutable// history, you do not rewrite local history. 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.
- `arc amend` will amend the commit message in HEAD with information from
the corresponding or specified Differential revision.
- **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.
- `arc amend` will exit with an error message.
== History Mutability: Mercurial ==
Before version 2.2, stock Mercurial has no history mutation commands, so
this setting has no effect. With Mercurial 2.2. or newer, making history
//mutable// means:
- **Mutable** (versions 2.2 and newer)
- `arc diff` will amend the commit message in `.` after creating a
revision.
- `arc amend` will amend the commit message in `.` with information from
the corresponding or specified Differential revision.
- **Immutable** (or versions prior to 2.2)
- `arc diff` will not amend the commit message in `.` after creating a
revision.
- `arc amend` will exit with an error message.
= How Libraries Are Located =
If you specify an external library to load, like 'examplelib', and use a
relative path like this:
{
...
"load": [
"examplelib/src"
],
...
}
...arc looks for it by trying these paths:
- `path/to/root/examplelib/src/` First, arc looks in the project's root
directory (where the .arcconfig lives) to see if the library is part of
the project. This makes it easy to just put project-specific code in a
project.
- `path/to/root/../examplelib/src/` Next, arc looks //next to// the project's
root directory to see if the library is in a sibling directory. If you
work with several repositories, this makes it easy to put all the `arc`
code in one repository and just check it out in the same directory as
everything else.
- `php/include/path/examplelib/src` Finally, arc falls back to PHP, which
will look in paths described in the `include_path` php.ini setting. This
allows you to install libraries in some global location if you prefer.
You can alternately supply an absolute path, like `/var/arc/examplelib/src`, but
then everyone will need to install the library at that exact location.
NOTE: Specify the path to the directory which includes
`__phutil_library_init__.php`. For example, if your init file is in
`examplelib/src/__phutil_library_init__.php`, specify `examplelib/src`,
not just `examplelib/`.
The general intent here is:
- Put project-specific code in some directory in the project, like
`support/arc/src/`.
- Put shared code (e.g., which enforces general coding standards or hooks
up to unit tests or whatever) in a separate repository and check it out
next to other repositories.
- Or put everything in some standard location and add it to `include_path`.
+= Running Without .arcconfig =
+
+Although you don't need to set up `.arcconfig`, and you can run `arc` command
+that require a working copy in any Git, Subversion or Mercurial working copy,
+some features won't work unless you set up an `.arcconfig` file.
+
+Without `.arcconfig`:
+
+ - You will need to set a default Phabricator URI with
+ `arc set-config default <uri>`, or specify an explicit URI
+ with `--conduit-uri` each time you run a command.
+ - You will not be able to run linters through arc unless you pass `--engine`
+ explicitly.
+ - You will not be able to customize certain linter parameters even with
+ `--engine`.
+ - You will not be able to run unit tests through arc unless you pass
+ `--engine` explicitly.
+ - You will not be able to trigger lint and unit integration through
+ `arc diff`.
+ - You will not be able to put Git working copies into immutable history mode
+ (see below).
+ - You will not be able to specify a repository encoding. UTF-8 will be assumed
+ if you do not pass `--encoding`.
+ - You will not be able to add plugins to arc to modify existing workflows or
+ add new ones.
+ - You will not be able to load additional libraries unless you specify them
+ explicitly with `--load-phutil-library`.
+ - Symbol index integration, which allows users to click function or class
+ names in Differential and jump to their definitions, will not work.
+ - `arc patch` will be unable to detect that you are applying changes to the
+ wrong project.
+ - In Subversion, `arc` will be unable to determine the canonical root
+ of a project, and will assume it is the working directory (in Subversion
+ prior to 1.7) or the root of the checkout (in Subversion after 1.7). This
+ means the paths of files in diffs won't be anchored to the same place,
+ and will have different amounts of path context, which may be confusing for
+ reviewers and will sometimes prevent patches from applying properly if they
+ are applied against a different directory than they were generated from.
+ - In Subversion, `arc` will be unable to guess that you intend to update
+ an existing revision; you must use `--update` explicitly or `--preview`
+ and attach diffs via the web interface.
+
+= Next Steps =
+
+Continue by:
+
+ - returning to @{article:Arcanist User Guide}.
diff --git a/src/docs/userguide/arcanist_quick_start.diviner b/src/docs/userguide/arcanist_quick_start.diviner
new file mode 100644
index 0000000000..0aeb0f9198
--- /dev/null
+++ b/src/docs/userguide/arcanist_quick_start.diviner
@@ -0,0 +1,100 @@
+@title Arcanist Quick Start
+@group userguide
+
+Quick guide to getting Arcanist working for a new project.
+
+This is a summary of steps to install Arcanist, configure a project for use with
+it, and run `arc` to send changes for review.
+
+= Install Arcanist =
+
+For detailed instructions on installing Arcanist, see
+@{article:Arcanist User Guide}.
+
+ - For Mac OS X, see @{article:Arcanist User Guide: Mac OS X}.
+ - For Windows, see @{article:Arcanist User Guide: Windows}.
+
+First, install dependencies:
+
+ - Install PHP.
+ - Install Git.
+
+Then install Arcanist itself:
+
+ $ mkdir somewhere/
+ $ cd somewhere/
+ somewhere/ $ git clone git://github.com/facebook/libphutil.git
+ somewhere/ $ git clone git://github.com/facebook/arcanist.git
+
+Add `arc` to your path:
+
+ $ export PATH="$PATH:/somewhere/arcanist/bin/"
+
+This won't work for Windows, see @{article:Arcanist User Guide: Windows} for
+instructions.
+
+= Configure Your Project =
+
+For detailed instructions on project configuration, see
+@{article:Arcanist User Guide: Configuring a New Project}.
+
+Create a `.arcconfig` file in your project's working copy:
+
+ $ cd yourproject/
+ yourproject/ $ $EDITOR .arcconfig
+ yourproject/ $ cat .arcconfig
+ {
+ "project_id" : "yourprojectname",
+ "conduit_uri" : "https://phabricator.example.com/"
+ }
+
+Set `project_id` to a string that identifies the project.
+
+Set `conduit_uri` to the URI for your Phabricator install (where `arc`
+should send changes to).
+
+NOTE: You should **commit this file** to the repository.
+
+= Install Arcanist Credentials =
+
+Credentials allow you to authenticate. You must have an account on Phabricator
+before you can perform this step.
+
+ $ cd yourproject/
+ yourproject/ $ arc install-certificate
+ ...
+
+Follow the instructions. This will link your user account on your local machine
+to your Phabricator account.
+
+= Send Changes For Review =
+
+For detailed instructions on using `arc diff`, see
+@{article:Arcanist User Guide: arc diff}.
+
+Subversion:
+
+ $ $EDITOR file.c
+ $ arc diff
+
+Git:
+
+ $ $EDITOR file.c
+ $ git commit -a -m '...'
+ $ arc diff HEAD^
+
+Mercurial:
+
+ $ $EDITOR file.c
+ $ hg commit -m '...'
+ $ arc diff tip^
+
+= Next Steps =
+
+Continue by:
+
+ - learning more about project configuration with
+ @{article:Arcanist User Guide: Configuring a New Project}; or
+ - learning more about `arc diff` with
+ @{article:Arcanist User Guide: arc diff}; or
+ - returning to @{article:Arcanist User Guide}.
diff --git a/src/docs/userguide/arcanist_windows.diviner b/src/docs/userguide/arcanist_windows.diviner
index 550a975b1e..67a9022c5a 100644
--- a/src/docs/userguide/arcanist_windows.diviner
+++ b/src/docs/userguide/arcanist_windows.diviner
@@ -1,79 +1,84 @@
@title Arcanist User Guide: Windows
@group userguide
Explains how to install Arcanist on Windows.
= Overview =
Arcanist runs on Windows, either in `cmd.exe` or the Git Bash environments.
However, it will take a little effort to get working. This document explains
what you need to do in order to get it running.
NOTE: Windows support is relatively new and incomplete, file bugs when you run
into issues.
= Required Components =
You need to install:
- Arcanist itself, see @{article:Arcanist User Guide}.
- PHP
- SVN, Git, or Mercurial.
Then, configure:
- Your PATH environmental variable should include `arcanist/bin`, the `php`
directory, and the directory where your VCS command lives. When you type
`php`, `arc`, or (for example) `git` from the command line, they should all
do something.
- Your EDITOR environmental variable should point at some valid CLI editor,
like the Git Bash `vim`. You can set this in `arc` if you prefer.
See below for details.
You can set environmental variables somewhere in the `Advanced` tab of the
`System` control panel.
Now you should be able to run `arc` normally (either from `cmd.exe` or
Git Bash) and it should work more-or-less properly.
= Configuring an Editor =
NOTE: You **can not** use Notepad as your editor, because it does not have a
blocking mode. You can use GitPad instead.
Some arc workflows prompt you to edit large blocks of text using a text editor.
You can configure various programs for this purpose, depending on which text
editor you prefer. Some editors that will work are:
- [[ http://notepad-plus-plus.org/ | Notepad++ ]], a good all-around editor.
- **vim**, which comes with Git Bash.
- [[ https://github.com/github/gitpad | GitPad ]], which allows you to use
Notepad as your editor.
Other editors may also work, but they must have a blocking edit mode.
To configure an editor, either set the `EDITOR` environmental variable to point
at it, or run:
$ arc set-config editor "\"C:\path\to\some\editor.exe\""
NOTE: Note the use of quotes. Paths with spaces in them must be quoted, and
these quotes must be escaped when passed to `arc set-config`, as in the examples
below.
Specifically, you can use this command for **Notepad++** (adjusting the path for
your machine):
name=Notepad++
$ arc set-config editor "\"C:\Program Files (x86)\Notepad++\notepad++.exe\" -multiInst -nosession"
And this command for Vim (you may need to adjust the path):
name=vim
$ arc set-config editor "\"C:\Program Files (x86)\Git\share\vim\vim73\vim.exe\""
And this for GitPad (you may need to adjust the path):
name=GitPad
$ arc set-config editor "\"C:\Users\yourusername\AppData\Roaming\GitPad\GitPad.exe\""
+= Next Steps =
+
+Continue by:
+
+ - returning to @{article:Arcanist User Guide}.

File Metadata

Mime Type
text/x-diff
Expires
Thu, Aug 14, 7:19 PM (2 d, 2 h ago)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
202319
Default Alt Text
(67 KB)

Event Timeline

styx copyright 2020 sirocyl / ellie (kymkdd) / ncommander / styx contributors
Use of other names and brands is not intended to reflect a claim of, or right to, use the name or brand.
styx is an operating system using the Linux kernel and components, and "styx Linux" as a phrase does not reflect the inclusion of the Linux brand or trademark in the styx project.
Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.
Terms and Conditions (TODO: fix this!)