@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
2@group userguide
3
4Guide to Arcanist, a command-line interface to Phorge.
5
6Arcanist provides command-line access to many Phorge tools (like
7Differential, Files, and Paste), integrates with static analysis ("lint") and
8unit tests, and manages common workflows like getting changes into Differential
9for review.
10
11A detailed command reference is available by running `arc help`. This
12document provides an overview of common workflows and installation.
13
14Arcanist has technical, contributor-focused documentation here:
15<https://we.phorge.it/book/arcanist/>
16
17= Quick Start =
18
19A quick start guide is available at @{article:Arcanist Quick Start}. It provides
20a much more compact summary of how to get `arc` set up and running for a new
21project. You may want to start there, and return here if you need more
22information.
23
24= Overview =
25
26Arcanist is a wrapper script that sits on top of other tools (e.g.,
27Differential, linters, unit test frameworks, git, Mercurial, and SVN) and
28provides a simple command-line API to manage code review and some related
29revision control operations.
30
31For a detailed list of all available commands, run:
32
33 $ arc help
34
35For detailed information about a specific command, run:
36
37 $ arc help <command>
38
39Arcanist allows you to do things like:
40
41 - get detailed help about available commands with `arc help`
42 - send your code to Differential for review with `arc diff` (for detailed
43 instructions, see @{article:Arcanist User Guide: arc diff})
44 - show pending revision information with `arc list`
45 - find likely reviewers for a change with `arc cover`
46 - apply changes in a revision to the working copy with `arc patch`
47 - download a patch from Differential with `arc export`
48 - update Git commit messages after review with `arc amend`
49 - commit SVN changes with `arc commit`
50 - push Git and Mercurial changes with `arc land`
51 - view enhanced information about Git branches with `arc branch`
52
53Once you've configured lint and unit test integration, you can also:
54
55 - check your code for syntax and style errors with `arc lint`
56 (see @{article:Arcanist User Guide: Lint})
57 - run unit tests that cover your changes with `arc unit`
58
59Arcanist integrates with other tools:
60
61 - upload and download files with `arc upload` and `arc download`
62 - create and view pastes with `arc paste`
63
64Arcanist has some advanced features as well, you can:
65
66 - execute Conduit method calls with `arc call-conduit`
67 - create or update libraries with `arc liberate`
68 - activate tab completion with `arc shell-complete`
69 - ...or extend Arcanist and add new commands.
70
71Except where otherwise noted, these workflows are generally agnostic to the
72underlying version control system and will work properly in git, Mercurial, or
73SVN repositories.
74
75= Installing Arcanist =
76
77Arcanist is meant to be installed on your local machine or development server --
78whatever machine you're editing code on. It runs on:
79
80 - Linux;
81 - Other operating systems which are pretty similar to Linux, or which
82 Linux is pretty similar to;
83 - FreeBSD, a fine operating system held in great esteem by many;
84 - Mac OS X (see @{article:Arcanist User Guide: Mac OS X}); and
85 - Windows (see @{article:Arcanist User Guide: Windows}).
86
87Arcanist is written in PHP, so you need to install the PHP CLI first if you
88don't already have it. Arcanist should run on PHP 5.2 and newer. If you don't
89have PHP installed, you can download it from <https://www.php.net/>.
90
91To install Arcanist, pick an install directory and clone the code from GitHub:
92
93 some_install_path/ $ git clone https://github.com/phorgeit/arcanist.git
94
95Now add `some_install_path/arcanist/bin/` to your PATH environment variable.
96When you type "arc", you should see something like this:
97
98 Usage Exception: No command provided. Try 'arc help'.
99
100If you get that far, you've done things correctly. If you get an error or have
101trouble getting this far, see these detailed guides:
102
103 - On Windows: @{article:Arcanist User Guide: Windows}
104 - On Mac OS X: @{article:Arcanist User Guide: Mac OS X}
105
106You can later upgrade Arcanist to the latest version with `arc upgrade`:
107
108 $ arc upgrade
109
110== Installing Arcanist for a Team ==
111
112Arcanist changes quickly, so it can be something of a headache to get it
113installed and keep people up to date. Here are some approaches you might be
114able to use:
115
116 - Facebook does most development on development servers, which have a standard
117 environment and NFS mounts. Arcanist lives on an
118 NFS mount, and the default `.bashrc` adds them to the PATH. Updating the
119 mount source updates everyone's versions, and new employees have a working
120 `arc` when they first log in.
121 - Another common approach is to write an install script as an action into
122 existing build scripts, so users can run `make install-arc` or
123 `ant install-arc` or similar.
124
125== Installing Tab Completion ==
126
127If you use `bash`, you can set up tab completion by running this command:
128
129 $ arc shell-complete
130
131This will install shell completion into your current shell. After installing,
132you may need to start a new shell (or open a new terminal window) to pick up
133the updated configuration.
134
135== Configuration ==
136
137Some Arcanist commands can be configured. This configuration is read from
138three sources, in order:
139
140 # A project can specify configuration in an `.arcconfig` file. This file is
141 JSON, and can be updated using `arc set-config --local` or by editing
142 it manually.
143 # User configuration is read from `~/.arcconfig`. This file is JSON, and can
144 be updated using `arc set-config`.
145 # Host configuration is read from `/etc/arcconfig` (on Windows, the path
146 is `C:\ProgramData\Phorge\Arcanist\config`).
147
148Arcanist uses the first definition it encounters as the runtime setting.
149
150Existing settings can be printed with `arc get-config`.
151
152Use `arc help set-config` and `arc help get-config` for more information
153about reading and writing configuration.
154
155== Next Steps ==
156
157Continue by:
158
159 - setting up a new project for use with `arc`, with
160 @{article:Arcanist User Guide: Configuring a New Project}; or
161 - learning how to use `arc` to send changes for review with
162 @{article:Arcanist User Guide: arc diff}.
163
164Advanced topics are also available. These are detailed guides to configuring
165technical features of `arc` that refine its behavior. You do not need to read
166them to get it working.
167
168 - @{article:Arcanist User Guide: Commit Ranges}
169 - @{article:Arcanist User Guide: Lint}
170 - @{article:Arcanist User Guide: Customizing Existing Linters}
171 - @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}
172 - @{article:Arcanist User Guide: Code Coverage}