2011-05-23 16:42:58 +02:00
|
|
|
@title Arcanist User Guide: Configuring a New Project
|
|
|
|
@group userguide
|
|
|
|
|
|
|
|
Explains how to configure Arcanist projects with ##.arcconfig## files.
|
|
|
|
|
2012-05-08 02:58:05 +02:00
|
|
|
= 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.
|
|
|
|
|
2011-05-23 16:42:58 +02:00
|
|
|
= .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",
|
2011-06-26 20:52:10 +02:00
|
|
|
"conduit_uri" : "https://phabricator.example.com/"
|
2011-05-23 16:42:58 +02:00
|
|
|
}
|
|
|
|
|
|
|
|
Here's what these options mean:
|
|
|
|
|
|
|
|
- **project_id**: a human-readable string identifying the project
|
2011-06-26 20:52:10 +02:00
|
|
|
- **conduit_uri**: the URI for the Phabricator installation that Arcanist
|
|
|
|
should send diffs to for review. Be mindful about "http" vs "https".
|
2011-05-23 16:42:58 +02:00
|
|
|
|
|
|
|
For an exhaustive list of available options, see below.
|
|
|
|
|
|
|
|
= Advanced .arcconfig =
|
|
|
|
|
|
|
|
Other options include:
|
|
|
|
|
2012-06-01 16:55:30 +02:00
|
|
|
- **lint.engine**: the name of a subclass of
|
2011-06-26 20:52:10 +02:00
|
|
|
@{class@arcanist:ArcanistLintEngine}, which should be used to apply lint
|
2012-06-01 16:55:30 +02:00
|
|
|
rules to this project. See @{article:Arcanist User Guide: Lint}.
|
|
|
|
- **unit.engine**: the name of a subclass of
|
2011-06-26 20:52:10 +02:00
|
|
|
@{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}.
|
2011-05-23 16:42:58 +02:00
|
|
|
- **arcanist_configuration**: the name of a subclass of
|
2011-06-26 20:52:10 +02:00
|
|
|
@{class@arcanist:ArcanistConfiguration} which can add new command flags for
|
|
|
|
this project or provide entirely new commands.
|
|
|
|
- **copyright_holder**: used by @{class@arcanist:ArcanistLicenseLinter} to
|
|
|
|
apply license notices to source files.
|
2012-04-07 19:39:51 +02:00
|
|
|
- **immutable_history**: controls how `arc diff` behaves in Git. See below.
|
2011-05-23 16:42:58 +02:00
|
|
|
- **phutil_libraries**: map of additional Phutil libraries to load at startup.
|
2012-03-22 20:06:46 +01:00
|
|
|
See below for details about path resolution, or see
|
|
|
|
@{article:libphutil Libraries User Guide} for a general introduction to
|
|
|
|
libphutil libraries.
|
|
|
|
|
2012-04-07 19:39:51 +02:00
|
|
|
= 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.
|
|
|
|
|
2012-03-22 20:06:46 +01:00
|
|
|
= How Libraries Are Located =
|
|
|
|
|
|
|
|
If you specify an external library to load, like 'examplelib', and use a
|
|
|
|
relative path like this:
|
|
|
|
|
|
|
|
{
|
|
|
|
...
|
|
|
|
"load_libraries": {
|
|
|
|
"examplelib" : "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`.
|
|
|
|
|