@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
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
+51
-27
+51
-27
src/docs/user/userguide/arcanist_new_project.diviner
+51
-27
src/docs/user/userguide/arcanist_new_project.diviner
···
3
3
4
4
Explains how to configure Arcanist projects with `.arcconfig` files.
5
5
6
-
= .arcconfig Basics =
6
+
= Overview =
7
7
8
-
An ##.arcconfig## file is a JSON file which you check into your project's root.
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.
9
11
10
-
Arcanist uses ##.arcconfig## files to determine a number of things about project
11
-
configuration. For instance, these are some of the things it figures out from
12
-
##.arcconfig##:
12
+
= .arcconfig Basics =
13
13
14
-
- where the logical root directory of a project is;
15
-
- which server Arcanist should send diffs to for code review; and
16
-
- which lint rules should be applied.
14
+
An `.arcconfig` file is a JSON file which you check into your project's root.
17
15
18
-
A simple, valid file looks something like this:
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
19
20
+
name=.arcconfig
20
21
{
21
-
"project_id" : "some_project_name",
22
-
"conduit_uri" : "https://phabricator.example.com/"
22
+
"phabricator.uri" : "https://phabricator.example.com/"
23
23
}
24
24
25
-
Here's what these options mean:
26
-
27
-
- **project_id**: a human-readable string identifying the project
28
-
- **conduit_uri**: the URI for the Phabricator installation that Arcanist
29
-
should send diffs to for review. Be mindful about "http" vs "https".
30
-
31
-
For an exhaustive list of available options, see below.
25
+
For details on available options, see below.
32
26
33
27
NOTE: You should commit your `.arcconfig` file! It contains project
34
28
configuration, not user configuration.
35
29
36
30
= Advanced .arcconfig =
37
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
+
38
46
Other options include:
39
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.
40
58
- **lint.engine**: the name of a subclass of
41
59
@{class@arcanist:ArcanistLintEngine}, which should be used to apply lint
42
60
rules to this project. See @{article:Arcanist User Guide: Lint}.
···
44
62
@{class@arcanist:ArcanistBaseUnitTestEngine}, which should be used to apply
45
63
unit test rules to this project. See
46
64
@{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}.
47
-
- **arcanist_configuration**: the name of a subclass of
48
-
@{class@arcanist:ArcanistConfiguration} which can add new command flags for
49
-
this project or provide entirely new commands.
50
-
- **history.immutable**: controls how `arc diff` and some other commands
51
-
behave in Git and Mercurial. See below.
52
-
- **load**: list of additional Phutil libraries to load at startup.
53
-
See below for details about path resolution, or see
54
-
@{article:libphutil Libraries User Guide} for a general introduction to
55
-
libphutil libraries.
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 set-config --show`. 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.
56
80
57
81
= History Mutability =
58
82