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