[Summary view] [Print] [Text view]

   1  @title Arcanist User Guide: Configuring a New Project
   2  @group userguide
   3  
   4  Explains how to configure Arcanist projects with `.arcconfig` files.
   5  
   6  = Overview =
   7  
   8  In most cases, you should be able to use `arc` without specifically configuring
   9  your project for it. If you want to adjust `arc` behaviors, you can create a
  10  `.arcconfig` file in your project to provide project-specific settings.
  11  
  12  = .arcconfig Basics =
  13  
  14  An `.arcconfig` file is a JSON file which you check into your project's root.
  15  
  16  Arcanist uses `.arcconfig` files to customize a number of things about its
  17  behavior. The first thing you're likely to want to configure is the URI
  18  for your Phabricator install. A simple, valid file looks something like this:
  19  
  20    name=.arcconfig
  21    {
  22      "phabricator.uri" : "https://phabricator.example.com/"
  23    }
  24  
  25  For details on available options, see below.
  26  
  27  NOTE: You should commit your `.arcconfig` file! It contains project
  28  configuration, not user configuration.
  29  
  30  = Advanced .arcconfig =
  31  
  32  Common options are:
  33  
  34    - **phabricator.uri**: the URI for the Phabricator install that `arc` should
  35      connect to when run in this project. This option was previously called
  36      `conduit_uri`.
  37    - **repository.callsign**: The callsign of this repository in Diffusion.
  38      Normally, `arc` can detect this automatically, but if it can't figure it out
  39      you can specify it explicitly. Use `arc which` to understand the detection
  40      process.
  41    - **history.immutable**: Configures `arc` to use workflows which never rewrite
  42      history in the working copy. By default, `arc` will perform some rewriting
  43      of unpublished history (amending commit messages, squash merging) on some
  44      workflows in Git. The distinctions are covered in detail below.
  45  
  46  Other options include:
  47  
  48    - **load**: list of additional Phutil libraries to load at startup.
  49      See below for details about path resolution, or see
  50      @{article:libphutil Libraries User Guide} for a general introduction to
  51      libphutil libraries.
  52    - **project.name**: name an "Arcanist Project" to associate this working
  53      copy (Git, Mercurial) or directory (SVN) with. Previously, this was a
  54      required option, but `arc` can now usually operate without it in Git and
  55      Mercurial. This option was previously called `project_id`.
  56    - **https.cabundle**: specifies the path to an alternate certificate bundle
  57      for use when making HTTPS connections.
  58    - **lint.engine**: the name of a subclass of
  59      @{class@arcanist:ArcanistLintEngine}, which should be used to apply lint
  60      rules to this project. See @{article:Arcanist User Guide: Lint}.
  61    - **unit.engine**: the name of a subclass of
  62      @{class@arcanist:ArcanistUnitTestEngine}, which should be used to apply
  63      unit test rules to this project. See
  64      @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}.
  65  
  66  These options are supported, but their use is discouraged:
  67  
  68    - **http.basicauth.user**: specify an HTTP basic auth username for use when
  69      connecting to Phabricator.
  70    - **http.basicauth.pass**: specify an HTTP basic auth password for use when
  71      connecting to Phabricator.
  72    - **https.blindly-trust-domains**: a list of domains to trust blindly over
  73      HTTPS, even if their certificates are invalid. This is a brute force
  74      solution to certificate validity problems, and is discouraged. Instead,
  75      use valid certificates.
  76  
  77  For a complete list of options, run `arc get-config`. Although all
  78  options can be set in `.arcconfig`, some options (like `editor`) usually do not
  79  make sense to set here because they're likely to vary from user to user.
  80  
  81  = History Mutability =
  82  
  83  Arcanist workflows run in two broad modes: either history is //mutable// or
  84  //immutable//. Under a //mutable// history, `arc` commands may rewrite the
  85  working copy history; under an //immutable// history, they may not.
  86  
  87  You control history mutability by setting `history.immutable` to `true` or
  88  `false` in your configuration. By default, it is `false` in Git (i.e.,
  89  //mutable//) and `true` in Mercurial (i.e., //immutable//). The sections below
  90  explain how these settings affect workflows.
  91  
  92  == History Mutability: Git ==
  93  
  94  In a workflow with //mutable// history, you rewrite local history. You develop
  95  in feature branches, but squash or amend before pushing by using ##git commit
  96  --amend##, ##git rebase -i##, or `git merge --squash`. Generally, one idea in
  97  the remote is represented by one commit.
  98  
  99  In a workflow with //immutable// history, you do not rewrite local history. You
 100  develop in feature branches and push them without squashing commits. You do not
 101  use ##git commit --amend## or ##git rebase -i##. Generally, one idea in the
 102  remote is represented by many commits.
 103  
 104  Practically, these are the differences you'll see based on your setting:
 105  
 106    - **Mutable**
 107      - `arc diff` will prompt you to amend lint changes into HEAD.
 108      - `arc diff` will amend the commit message in HEAD after creating a
 109        revision.
 110      - `arc land` will default to the `--squash` strategy.
 111      - `arc amend` will amend the commit message in HEAD with information from
 112        the corresponding or specified Differential revision.
 113    - **Immutable**
 114      - `arc diff` will abort if it makes lint changes.
 115      - `arc diff` will not amend the commit message in HEAD after creating a
 116        revision.
 117      - `arc land` will default to the `--merge` strategy.
 118      - `arc amend` will exit with an error message.
 119  
 120  == History Mutability: Mercurial ==
 121  
 122  Before version 2.2, stock Mercurial has no history mutation commands, so
 123  this setting has no effect. With Mercurial 2.2. or newer, making history
 124  //mutable// means:
 125  
 126    - **Mutable** (versions 2.2 and newer)
 127      - `arc diff` will amend the commit message in `.` after creating a
 128        revision.
 129      - `arc amend` will amend the commit message in `.` with information from
 130        the corresponding or specified Differential revision.
 131    - **Immutable** (or versions prior to 2.2)
 132      - `arc diff` will not amend the commit message in `.` after creating a
 133        revision.
 134      - `arc amend` will exit with an error message.
 135  
 136  = How Libraries Are Located =
 137  
 138  If you specify an external library to load, like 'examplelib', and use a
 139  relative path like this:
 140  
 141    {
 142      ...
 143      "load": [
 144        "examplelib/src"
 145      ],
 146      ...
 147    }
 148  
 149  ...arc looks for it by trying these paths:
 150  
 151    - `path/to/root/examplelib/src/` First, arc looks in the project's root
 152      directory (where the `.arcconfig` lives) to see if the library is part of
 153      the project. This makes it easy to just put project-specific code in a
 154      project.
 155    - `path/to/root/../examplelib/src/` Next, arc looks //next to// the project's
 156      root directory to see if the library is in a sibling directory. If you
 157      work with several repositories, this makes it easy to put all the `arc`
 158      code in one repository and just check it out in the same directory as
 159      everything else.
 160    - `php/include/path/examplelib/src` Finally, arc falls back to PHP, which
 161      will look in paths described in the `include_path` php.ini setting. This
 162      allows you to install libraries in some global location if you prefer.
 163  
 164  You can alternately supply an absolute path, like `/var/arc/examplelib/src`, but
 165  then everyone will need to install the library at that exact location.
 166  
 167  NOTE: Specify the path to the directory which includes
 168  `__phutil_library_init__.php`. For example, if your init file is in
 169  `examplelib/src/__phutil_library_init__.php`, specify `examplelib/src`,
 170  not just `examplelib/`.
 171  
 172  The general intent here is:
 173  
 174    - Put project-specific code in some directory in the project, like
 175      `support/arc/src/`.
 176    - Put shared code (e.g., which enforces general coding standards or hooks
 177      up to unit tests or whatever) in a separate repository and check it out
 178      next to other repositories.
 179    - Or put everything in some standard location and add it to `include_path`.
 180  
 181  = Running Without .arcconfig =
 182  
 183  Although you don't need to set up `.arcconfig`, and you can run `arc` command
 184  that require a working copy in any Git, Subversion or Mercurial working copy,
 185  some features won't work unless you set up an `.arcconfig` file.
 186  
 187  Without `.arcconfig`:
 188  
 189    - You will need to set a default Phabricator URI with
 190      `arc set-config default <uri>`, or specify an explicit URI
 191      with `--conduit-uri` each time you run a command.
 192    - You will not be able to run linters through arc unless you pass `--engine`
 193      explicitly.
 194    - You will not be able to customize certain linter parameters even with
 195      `--engine`.
 196    - You will not be able to run unit tests through arc unless you pass
 197      `--engine` explicitly.
 198    - You will not be able to trigger lint and unit integration through
 199      `arc diff`.
 200    - You will not be able to put Git working copies into immutable history mode
 201      (see below).
 202    - You will not be able to specify a repository encoding. UTF-8 will be assumed
 203      if you do not pass `--encoding`.
 204    - You will not be able to add plugins to arc to modify existing workflows or
 205      add new ones.
 206    - You will not be able to load additional libraries unless you specify them
 207      explicitly with `--load-phutil-library`.
 208    - Symbol index integration, which allows users to click function or class
 209      names in Differential and jump to their definitions, will not work.
 210    - `arc patch` will be unable to detect that you are applying changes to the
 211      wrong project.
 212    - In Subversion, `arc` will be unable to determine the canonical root
 213      of a project, and will assume it is the working directory (in Subversion
 214      prior to 1.7) or the root of the checkout (in Subversion after 1.7). This
 215      means the paths of files in diffs won't be anchored to the same place,
 216      and will have different amounts of path context, which may be confusing for
 217      reviewers and will sometimes prevent patches from applying properly if they
 218      are applied against a different directory than they were generated from.
 219    - In Subversion, `arc` will be unable to guess that you intend to update
 220      an existing revision; you must use `--update` explicitly or `--preview`
 221      and attach diffs via the web interface.
 222  
 223  = Next Steps =
 224  
 225  Continue by:
 226  
 227    - returning to @{article:Arcanist User Guide}.