From 8797c3ad0b2106550ec0309dbfcdeea5dc72b0dc Mon Sep 17 00:00:00 2001 From: epriestley Date: Fri, 14 Mar 2014 14:33:53 -0700 Subject: [PATCH] Partly update the .arcconfig documentation Summary: This needs more updates after .arclint is ready to use, but should fix most of the biggest issues. Test Plan: Generated and read it. Reviewers: btrahan Reviewed By: btrahan Subscribers: epriestley Differential Revision: https://secure.phabricator.com/D8539 --- .../userguide/arcanist_new_project.diviner | 80 ++++++++++++------- 1 file changed, 52 insertions(+), 28 deletions(-) diff --git a/src/docs/user/userguide/arcanist_new_project.diviner b/src/docs/user/userguide/arcanist_new_project.diviner index 19eb5facf1..c8f9389572 100644 --- a/src/docs/user/userguide/arcanist_new_project.diviner +++ b/src/docs/user/userguide/arcanist_new_project.diviner @@ -3,40 +3,58 @@ Explains how to configure Arcanist projects with `.arcconfig` files. += Overview = + +In most cases, you should be able to use `arc` without specifically configuring +your project for it. If you want to adjust `arc` behaviors, you can create a +`.arcconfig` file in your project to provide project-specific settings. + = .arcconfig Basics = -An ##.arcconfig## file is a JSON file which you check into your project's root. +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: +Arcanist uses `.arcconfig` files to customize a number of things about its +behavior. The first thing you're likely to want to configure is the URI +for your Phabricator install. A simple, valid file looks something like this: + name=.arcconfig { - "project_id" : "some_project_name", - "conduit_uri" : "https://phabricator.example.com/" + "phabricator.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. +For details on available options, see below. NOTE: You should commit your `.arcconfig` file! It contains project configuration, not user configuration. = Advanced .arcconfig = +Common options are: + + - **phabricator.uri**: the URI for the Phabricator install that `arc` should + connect to when run in this project. This option was previously called + `conduit_uri`. + - **repository.callsign**: The callsign of this repository in Diffusion. + Normally, `arc` can detect this automatically, but if it can't figure it out + you can specify it explicitly. Use `arc which` to understand the detection + process. + - **history.immutable**: Configures `arc` to use workflows which never rewrite + history in the working copy. By default, `arc` will perform some rewriting + of unpublished history (amending commit messages, squash merging) on some + workflows in Git. The distinctions are covered in detail below. + Other options include: + - **load**: list 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. + - **project.name**: name an "Arcanist Project" to associate this working + copy (Git, Mercurial) or directory (SVN) with. Previously, this was a + required option, but `arc` can now usually operate without it in Git and + Mercurial. This option was previously called `project_id`. + - **https.cabundle**: specifies the path to an alternate certificate bundle + for use when making HTTPS connections. - **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: Lint}. @@ -44,15 +62,21 @@ Other options include: @{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. - - **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 - @{article:libphutil Libraries User Guide} for a general introduction to - libphutil libraries. + +These options are supported, but their use is discouraged: + + - **http.basicauth.user**: specify an HTTP basic auth username for use when + connecting to Phabricator. + - **http.basicauth.pass**: specify an HTTP basic auth password for use when + connecting to Phabricator. + - **https.blindly-trust-domains**: a list of domains to trust blindly over + HTTPS, even if their certificates are invalid. This is a brute force + solution to certificate validity problems, and is discouraged. Instead, + use valid certificates. + +For a complete list of options, run `arc set-config --show`. Although all +options can be set in `.arcconfig`, some options (like `editor`) usually do not +make sense to set here because they're likely to vary from user to user. = History Mutability =