phorge-phorge/src/docs/userguide/arcanist_new_project.diviner

@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.

= .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/"
  }

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.

= 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: Customizing Lint,
    Unit Tests and Workflows}.
  - **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.
  - **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
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`.