@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
Improve arcanist documentation
Summary:
There's some good feedback from Wikimedia here:
http://lists.wikimedia.org/pipermail/wikitech-l/2012-August/062252.html
Try to improve on some of it. In particular:
- Make it clear that /arcanist/ is not where you should be (D3235).
- Provide better connections from "Arcanist User Guide" to other documents.
- Provide a "Quick Start" guide with a simpler set of instructions that links to richer documentation.
- Reorganize the project setup guide to put more important things earlier on.
- Make it clear that you should commit `.arcconfig`.
- Provide more hints for initial setup.
- Describe and organize advanced configuration/extension documentation as more clearly separate from basic setup/install documentation.
Test Plan: Generated, read docs.
Reviewers: vrana, btrahan
Reviewed By: vrana
CC: aran
Differential Revision: https://secure.phabricator.com/D3236
+241
-59
+37
-6
src/docs/userguide/arcanist.diviner
+37
-6
src/docs/userguide/arcanist.diviner
···
9
9
for review.
10
10
11
11
A detailed command reference is available by running ##arc help##. This
12
-
document provides a high level overview of common workflows.
12
+
document provides an overview of common workflows and installation.
13
13
14
14
Arcanist has technical, contributor-focused documentation here:
15
15
<http://www.phabricator.com/docs/arcanist/>
16
16
17
+
= Quick Start =
18
+
19
+
A quick start guide is available at @{article:Arcanist Quick Start}. It provides
20
+
a much more compact summary of how to get `arc` set up and running for a new
21
+
project. You may want to start there, and return here if you need more
22
+
information.
23
+
17
24
= Overview =
18
25
19
26
Arcanist is a wrapper script that sits on top of other tools (e.g.,
···
21
28
provides a simple command-line API to manage code review and some related
22
29
revision control operations.
23
30
31
+
For a detailed list of all available commands, run:
32
+
33
+
$ arc help
34
+
35
+
For detailed information about a specific command, run:
36
+
37
+
$ arc help <command>
38
+
24
39
Arcanist allows you to do things like:
25
40
26
41
- get detailed help about available commands with ##arc help##
27
-
- send your code to Differential for review with ##arc diff##
42
+
- send your code to Differential for review with ##arc diff## (for detailed
43
+
instructions, see @{article:Arcanist User Guide: arc diff})
28
44
- show pending revision information with ##arc list##
29
45
- find likely reviewers for a change with ##arc cover##
30
46
- apply changes in a revision to the working copy with ##arc patch##
···
37
53
Once you've configured lint and unit test integration, you can also:
38
54
39
55
- check your code for syntax and style errors with ##arc lint##
56
+
(see @{article:Arcanist User Guide: Lint})
40
57
- run unit tests that cover your changes with ##arc unit##
41
58
42
59
Arcanist integrates with other tools:
···
60
77
= Installing Arcanist =
61
78
62
79
Arcanist is meant to be installed on your local machine or development server --
63
-
whatever machine you're editing code on. It runs on Linux, Mac OS X, and
80
+
whatever machine you're editing code on. It runs on Linux,
81
+
Mac OS X (see @{article:Arcanist User Guide: Mac OS X}), and
64
82
Windows (see @{article:Arcanist User Guide: Windows}).
65
83
66
84
Arcanist is written in PHP, so you need to install the PHP CLI first if you
···
96
114
97
115
== Installing Arcanist for a Team ==
98
116
99
-
Arcanist changes quickly and doesn't currently have an auto-update mechanism,
100
-
so it can be something of a headache to get it installed and keep people up to
101
-
date. Here are some approaches you might be able to use:
117
+
Arcanist changes quickly, so it can be something of a headache to get it
118
+
installed and keep people up to date. Here are some approaches you might be
119
+
able to use:
102
120
103
121
- Facebook does most development on development servers, which have a standard
104
122
environment and NFS mounts. Arcanist and libphutil themselves live on an
···
125
143
126
144
Continue by:
127
145
146
+
- setting up a new project for use with `arc`, with
147
+
@{article:Arcanist User Guide: Configuring a New Project}; or
128
148
- learning how to use `arc` to send changes for review with
129
149
@{article:Arcanist User Guide: arc diff}.
150
+
151
+
Advanced topics are also available. These are detailed guides to configuring
152
+
technical features of `arc` that refine its behavior. You do not need to read
153
+
them to get it working.
154
+
155
+
- @{article:Arcanist User Guide: Commit Ranges}
156
+
- @{article:Arcanist User Guide: Lint}
157
+
- @{article:Arcanist User Guide: Customizing Existing Linters}
158
+
- @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}
159
+
- @{article:Arcanist User Guide: Code Coverage}
160
+
- @{article:Arcanist User Guide: Repository Hooks}
+4
src/docs/userguide/arcanist_commit_ranges.diviner
+4
src/docs/userguide/arcanist_commit_ranges.diviner
···
3
3
4
4
Explains how commit ranges work in Arcanist.
5
5
6
+
This is an advanced user guide which covers a complicated topic in detail. If
7
+
you're just getting started, you don't need to look at this yet. Instead, start
8
+
with the @{article:Arcanist User Guide}.
9
+
6
10
= Overview =
7
11
8
12
//In Subversion, `arc` commands always operate on the uncommitted changes in the
+9
src/docs/userguide/arcanist_coverage.diviner
+9
src/docs/userguide/arcanist_coverage.diviner
···
3
3
4
4
Explains code coverage features in Arcanist and Phabricator.
5
5
6
+
This is a configuration guide that helps you set up advanced features. If you're
7
+
just getting started, you don't need to look at this yet. Instead, start with
8
+
the @{article:Arcanist User Guide}.
9
+
10
+
Before you can configure coverage features, you must set up unit test
11
+
integration. For instructions, see @{article:Arcanist User Guide: Configuring
12
+
a New Project} and @{article:Arcanist User Guide: Customizing
13
+
Lint, Unit Tests and Workflows}.
14
+
6
15
= Using Coverage Features =
7
16
8
17
If your project has unit tests with coverage integration (see below for
+7
-7
src/docs/userguide/arcanist_diff.diviner
+7
-7
src/docs/userguide/arcanist_diff.diviner
···
1
1
@title Arcanist User Guide: arc diff
2
2
@group userguide
3
3
4
-
Guide to running `arc diff`.
5
-
6
-
= Overview =
4
+
Guide to running `arc diff`, to send changes to Differential for review.
7
5
8
6
This article assumes you have `arc` installed and running; if not, see
9
7
@{article:Arcanist User Guide} for help getting it set up.
10
8
11
-
This document is intended for users of `arc diff`, and is a practical
12
-
guide to using it to send changes for review. If you are installing and
13
-
configuring Phabricator, make sure to read the more comprehensive information in
14
-
@{article:Arcanist User Guide: Configuring a New Project}.
9
+
Before running `arc diff`, you should create a `.arcconfig` file. If someone
10
+
set things up for you, they may already have done this. See
11
+
@{article:Arcanist User Guide: Configuring a New Project} for instructions and
12
+
information.
13
+
14
+
= Overview =
15
15
16
16
While `arc` has a large number of commands that interface with various
17
17
Phabricator applications, the primary use of `arc` is to send changes for
+8
src/docs/userguide/arcanist_extending_lint.diviner
+8
src/docs/userguide/arcanist_extending_lint.diviner
···
3
3
4
4
Explains how to customize existing linters.
5
5
6
+
This is a configuration guide that helps you set up advanced features. If you're
7
+
just getting started, you don't need to look at this yet. Instead, start with
8
+
the @{article:Arcanist User Guide}.
9
+
10
+
This guide explains how to refine lint behavior. To configure lint in the first
11
+
place, see @{article:Arcanist User Guide: Configuring a New Project} and
12
+
@{article:Arcanist User Guide: Lint}.
13
+
6
14
= Overview =
7
15
8
16
Arcanist ships with a number of linters which you may want to reuse in whole
+8
src/docs/userguide/arcanist_lint.diviner
+8
src/docs/userguide/arcanist_lint.diviner
···
3
3
4
4
Guide to lint, linters, and linter configuration.
5
5
6
+
This is a configuration guide that helps you set up advanced features. If you're
7
+
just getting started, you don't need to look at this yet. Instead, start with
8
+
the @{article:Arcanist User Guide}.
9
+
10
+
This guide explains how lint works when configured in an `arc` project. If
11
+
you haven't set up a project yet, do that first. For instructions, see
12
+
@{article:Arcanist User Guide: Configuring a New Project}.
13
+
6
14
= Overview =
7
15
8
16
"Lint" refers to a general class of programming tools which analyze source code
+4
src/docs/userguide/arcanist_lint_unit.diviner
+4
src/docs/userguide/arcanist_lint_unit.diviner
···
3
3
4
4
Explains how to build new classes to control how Arcanist behaves.
5
5
6
+
This is a configuration guide that helps you set up advanced features. If you're
7
+
just getting started, you don't need to look at this yet. Instead, start with
8
+
the @{article:Arcanist User Guide}.
9
+
6
10
= Overview =
7
11
8
12
Arcanist has some basic configuration options available in the `.arcconfig`
+5
src/docs/userguide/arcanist_mac_os_x.diviner
+5
src/docs/userguide/arcanist_mac_os_x.diviner
+54
-46
src/docs/userguide/arcanist_new_project.diviner
+54
-46
src/docs/userguide/arcanist_new_project.diviner
···
1
1
@title Arcanist User Guide: Configuring a New Project
2
2
@group userguide
3
3
4
-
Explains how to configure Arcanist projects with ##.arcconfig## files.
5
-
6
-
= Overview =
4
+
Explains how to configure Arcanist projects with `.arcconfig` files.
7
5
8
-
You can run `arc` commands that require a working copy in any Git, Subversion
9
-
or Mercurial working copy, but some features won't work unless you set up an
10
-
`.arcconfig` file to configure settings for the project. Creating this file is
11
-
easy and only takes a few minutes.
6
+
= .arcconfig Basics =
12
7
13
-
Without `.arcconfig`:
14
-
15
-
- You will need to set a default Phabricator URI with
16
-
`arc set-config default <uri>`, or specify an explicit URI
17
-
with `--conduit-uri` each time you run a command.
18
-
- You will not be able to run linters through arc unless you pass `--engine`
19
-
explicitly.
20
-
- You will not be able to customize certain linter parameters even with
21
-
`--engine`.
22
-
- You will not be able to run unit tests through arc unless you pass
23
-
`--engine` explicitly.
24
-
- You will not be able to trigger lint and unit integration through
25
-
`arc diff`.
26
-
- You will not be able to put Git working copies into immutable history mode
27
-
(see below).
28
-
- You will not be able to specify a repository encoding. UTF-8 will be assumed
29
-
if you do not pass `--encoding`.
30
-
- You will not be able to add plugins to arc to modify existing workflows or
31
-
add new ones.
32
-
- You will not be able to load additional libraries unless you specify them
33
-
explicitly with `--load-phutil-library`.
34
-
- Symbol index integration, which allows users to click function or class
35
-
names in Differential and jump to their definitions, will not work.
36
-
- `arc patch` will be unable to detect that you are applying changes to the
37
-
wrong project.
38
-
- In Subversion, `arc` will be unable to determine the canonical root
39
-
of a project, and will assume it is the working directory (in Subversion
40
-
prior to 1.7) or the root of the checkout (in Subversion after 1.7). This
41
-
means the paths of files in diffs won't be anchored to the same place,
42
-
and will have different amounts of path context, which may be confusing for
43
-
reviewers and will sometimes prevent patches from applying properly if they
44
-
are applied against a different directory than they were generated from.
45
-
- In Subversion, `arc` will be unable to guess that you intend to update
46
-
an existing revision; you must use `--update` explicitly or `--preview`
47
-
and attach diffs via the web interface.
48
-
49
-
= .arcconfig Basics =
8
+
An ##.arcconfig## file is a JSON file which you check into your project's root.
50
9
51
10
Arcanist uses ##.arcconfig## files to determine a number of things about project
52
-
configuration. For instance, these are things it figures out from
11
+
configuration. For instance, these are some of the things it figures out from
53
12
##.arcconfig##:
54
13
55
14
- where the logical root directory of a project is;
56
15
- which server Arcanist should send diffs to for code review; and
57
16
- which lint rules should be applied.
58
17
59
-
An ##.arcconfig## file is a JSON file which you check into your project's root.
60
18
A simple, valid file looks something like this:
61
19
62
20
{
···
71
29
should send diffs to for review. Be mindful about "http" vs "https".
72
30
73
31
For an exhaustive list of available options, see below.
32
+
33
+
NOTE: You should commit your `.arcconfig` file! It contains project
34
+
configuration, not user configuration.
74
35
75
36
= Advanced .arcconfig =
76
37
···
193
154
next to other repositories.
194
155
- Or put everything in some standard location and add it to `include_path`.
195
156
157
+
= Running Without .arcconfig =
158
+
159
+
Although you don't need to set up `.arcconfig`, and you can run `arc` command
160
+
that require a working copy in any Git, Subversion or Mercurial working copy,
161
+
some features won't work unless you set up an `.arcconfig` file.
162
+
163
+
Without `.arcconfig`:
164
+
165
+
- You will need to set a default Phabricator URI with
166
+
`arc set-config default <uri>`, or specify an explicit URI
167
+
with `--conduit-uri` each time you run a command.
168
+
- You will not be able to run linters through arc unless you pass `--engine`
169
+
explicitly.
170
+
- You will not be able to customize certain linter parameters even with
171
+
`--engine`.
172
+
- You will not be able to run unit tests through arc unless you pass
173
+
`--engine` explicitly.
174
+
- You will not be able to trigger lint and unit integration through
175
+
`arc diff`.
176
+
- You will not be able to put Git working copies into immutable history mode
177
+
(see below).
178
+
- You will not be able to specify a repository encoding. UTF-8 will be assumed
179
+
if you do not pass `--encoding`.
180
+
- You will not be able to add plugins to arc to modify existing workflows or
181
+
add new ones.
182
+
- You will not be able to load additional libraries unless you specify them
183
+
explicitly with `--load-phutil-library`.
184
+
- Symbol index integration, which allows users to click function or class
185
+
names in Differential and jump to their definitions, will not work.
186
+
- `arc patch` will be unable to detect that you are applying changes to the
187
+
wrong project.
188
+
- In Subversion, `arc` will be unable to determine the canonical root
189
+
of a project, and will assume it is the working directory (in Subversion
190
+
prior to 1.7) or the root of the checkout (in Subversion after 1.7). This
191
+
means the paths of files in diffs won't be anchored to the same place,
192
+
and will have different amounts of path context, which may be confusing for
193
+
reviewers and will sometimes prevent patches from applying properly if they
194
+
are applied against a different directory than they were generated from.
195
+
- In Subversion, `arc` will be unable to guess that you intend to update
196
+
an existing revision; you must use `--update` explicitly or `--preview`
197
+
and attach diffs via the web interface.
198
+
199
+
= Next Steps =
200
+
201
+
Continue by:
202
+
203
+
- returning to @{article:Arcanist User Guide}.
+100
src/docs/userguide/arcanist_quick_start.diviner
+100
src/docs/userguide/arcanist_quick_start.diviner
···
1
+
@title Arcanist Quick Start
2
+
@group userguide
3
+
4
+
Quick guide to getting Arcanist working for a new project.
5
+
6
+
This is a summary of steps to install Arcanist, configure a project for use with
7
+
it, and run `arc` to send changes for review.
8
+
9
+
= Install Arcanist =
10
+
11
+
For detailed instructions on installing Arcanist, see
12
+
@{article:Arcanist User Guide}.
13
+
14
+
- For Mac OS X, see @{article:Arcanist User Guide: Mac OS X}.
15
+
- For Windows, see @{article:Arcanist User Guide: Windows}.
16
+
17
+
First, install dependencies:
18
+
19
+
- Install PHP.
20
+
- Install Git.
21
+
22
+
Then install Arcanist itself:
23
+
24
+
$ mkdir somewhere/
25
+
$ cd somewhere/
26
+
somewhere/ $ git clone git://github.com/facebook/libphutil.git
27
+
somewhere/ $ git clone git://github.com/facebook/arcanist.git
28
+
29
+
Add `arc` to your path:
30
+
31
+
$ export PATH="$PATH:/somewhere/arcanist/bin/"
32
+
33
+
This won't work for Windows, see @{article:Arcanist User Guide: Windows} for
34
+
instructions.
35
+
36
+
= Configure Your Project =
37
+
38
+
For detailed instructions on project configuration, see
39
+
@{article:Arcanist User Guide: Configuring a New Project}.
40
+
41
+
Create a `.arcconfig` file in your project's working copy:
42
+
43
+
$ cd yourproject/
44
+
yourproject/ $ $EDITOR .arcconfig
45
+
yourproject/ $ cat .arcconfig
46
+
{
47
+
"project_id" : "yourprojectname",
48
+
"conduit_uri" : "https://phabricator.example.com/"
49
+
}
50
+
51
+
Set `project_id` to a string that identifies the project.
52
+
53
+
Set `conduit_uri` to the URI for your Phabricator install (where `arc`
54
+
should send changes to).
55
+
56
+
NOTE: You should **commit this file** to the repository.
57
+
58
+
= Install Arcanist Credentials =
59
+
60
+
Credentials allow you to authenticate. You must have an account on Phabricator
61
+
before you can perform this step.
62
+
63
+
$ cd yourproject/
64
+
yourproject/ $ arc install-certificate
65
+
...
66
+
67
+
Follow the instructions. This will link your user account on your local machine
68
+
to your Phabricator account.
69
+
70
+
= Send Changes For Review =
71
+
72
+
For detailed instructions on using `arc diff`, see
73
+
@{article:Arcanist User Guide: arc diff}.
74
+
75
+
Subversion:
76
+
77
+
$ $EDITOR file.c
78
+
$ arc diff
79
+
80
+
Git:
81
+
82
+
$ $EDITOR file.c
83
+
$ git commit -a -m '...'
84
+
$ arc diff HEAD^
85
+
86
+
Mercurial:
87
+
88
+
$ $EDITOR file.c
89
+
$ hg commit -m '...'
90
+
$ arc diff tip^
91
+
92
+
= Next Steps =
93
+
94
+
Continue by:
95
+
96
+
- learning more about project configuration with
97
+
@{article:Arcanist User Guide: Configuring a New Project}; or
98
+
- learning more about `arc diff` with
99
+
@{article:Arcanist User Guide: arc diff}; or
100
+
- returning to @{article:Arcanist User Guide}.