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.

= .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`.