Article Arcanist User Guide: Configuring a New Project

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

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 ArcanistLintEngine, which should be used to apply lint rules to this project. See Arcanist User Guide: Lint.
• unit.engine: the name of a subclass of ArcanistBaseUnitTestEngine, which should be used to apply unit test rules to this project. See Arcanist User Guide: Customizing Lint, Unit Tests and Workflows.
• arcanist_configuration: the name of a subclass of 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 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.

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 Arcanist User Guide.