Page MenuHomestyx hydra
Files F1993843

No OneTemporary
Actions

View Options

diff --git a/src/docs/userguide/arcanist_new_project.diviner b/src/docs/userguide/arcanist_new_project.diviner
index 85807b2127..84d6557496 100644
--- a/src/docs/userguide/arcanist_new_project.diviner
+++ b/src/docs/userguide/arcanist_new_project.diviner
@@ -1,134 +1,177 @@
@title Arcanist User Guide: Configuring a New Project
@group userguide
Explains how to configure Arcanist projects with ##.arcconfig## files.
+= Overview =
+
+You can run `arc` commands that require a working copy in any Git, Subversion
+or Mercurial working copy, but some features won't work unless you set up an
+`.arcconfig` file to configure settings for the project. Creating this file is
+easy and only takes a few minutes.
+
+Without `.arcconfig`:
+
+ - You will need to set a default Phabricator URI with
+ `arc set-config default <uri>`, or specify an explicit URI
+ with `--conduit-uri` each time you run a command.
+ - You will not be able to run linters through arc unless you pass `--engine`
+ explicitly.
+ - You will not be able to customize certain linter parameters even with
+ `--engine`.
+ - You will not be able to run unit tests through arc unless you pass
+ `--engine` explicitly.
+ - You will not be able to trigger lint and unit integration through
+ `arc diff`.
+ - You will not be able to put Git working copies into immutable history mode
+ (see below).
+ - You will not be able to specify a repository encoding. UTF-8 will be assumed
+ if you do not pass `--encoding`.
+ - You will not be able to add plugins to arc to modify existing workflows or
+ add new ones.
+ - You will not be able to load additional libraries unless you specify them
+ explicitly with `--load-phutil-library`.
+ - Symbol index integration, which allows users to click function or class
+ names in Differential and jump to their definitions, will not work.
+ - `arc patch` will be unable to detect that you are applying changes to the
+ wrong project.
+ - In Subversion, `arc` will be unable to determine the canonical root
+ of a project, and will assume it is the working directory (in Subversion
+ prior to 1.7) or the root of the checkout (in Subversion after 1.7). This
+ means the paths of files in diffs won't be anchored to the same place,
+ and will have different amounts of path context, which may be confusing for
+ reviewers and will sometimes prevent patches from applying properly if they
+ are applied against a different directory than they were generated from.
+ - In Subversion, `arc` will be unable to guess that you intend to update
+ an existing revision; you must use `--update` explicitly or `--preview`
+ and attach diffs via the web interface.
+
= .arcconfig Basics =
Arcanist uses ##.arcconfig## files to determine a number of things about project
configuration. For instance, these are 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.
An ##.arcconfig## file is a JSON file which you check into your project's root.
A simple, valid file looks something like this:
{
"project_id" : "some_project_name",
"conduit_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.
= Advanced .arcconfig =
Other options include:
- **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: Customizing Lint,
Unit Tests and Workflows}.
- **unit_engine**: the name of a subclass of
@{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.
- **copyright_holder**: used by @{class@arcanist:ArcanistLicenseLinter} to
apply license notices to source files.
- **immutable_history**: controls how `arc diff` behaves in Git. See below.
- **phutil_libraries**: map 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.
= Immutable History =
There are a lot of ways to use git, and Arcanist is flexible enough to handle
several of them. Git workflows divide into two major groups based on your
**doctrine of history mutability**.
Choose a **history mutability doctrine** by setting ##"immutable_history"## in
your ##.arcconfig##. Valid values are ##true## to enforce a **conservative
history mutability doctrine** or ##false## to enforce a **liberal history
mutability doctrine**. The default is ##false##.
A **liberal history mutability doctrine** means you rewrite local history. You
develop in feature branches, but squash or amend before pushing by using ##git
commit --amend## or ##git rebase -i##. Generally, one idea in the remote is
represented by one commit.
A **conservative history mutability doctrine** means that you do not rewrite
local history. This is similar to how Mercurial works. You develop in feature
branches and push them without squashing commits. You do not use ##git commit
--amend## or ##git rebase -i##. Generally, one idea in the remote is represented
by many commits.
Practically, these are the differences you'll see based on your setting:
- **Mutable**
- `arc diff` will prompt you to amend lint changes into HEAD.
- `arc diff` will amend the commit message in HEAD after creating a
revision.
- `arc land` will default to the `--squash` strategy.
- **Immutable**
- `arc diff` will abort if it makes lint changes.
- `arc diff` will not amend the commit message in HEAD after creating a
revision.
- `arc land` will default to the `--merge` strategy.
= How Libraries Are Located =
If you specify an external library to load, like 'examplelib', and use a
relative path like this:
{
...
"load_libraries": {
"examplelib" : "examplelib/src"
},
...
}
...arc looks for it by trying these paths:
- `path/to/root/examplelib/src/` First, arc looks in the project's root
directory (where the .arcconfig lives) to see if the library is part of
the project. This makes it easy to just put project-specific code in a
project.
- `path/to/root/../examplelib/src/` Next, arc looks //next to// the project's
root directory to see if the library is in a sibling directory. If you
work with several repositories, this makes it easy to put all the `arc`
code in one repository and just check it out in the same directory as
everything else.
- `php/include/path/examplelib/src` Finally, arc falls back to PHP, which
will look in paths described in the `include_path` php.ini setting. This
allows you to install libraries in some global location if you prefer.
You can alternately supply an absolute path, like `/var/arc/examplelib/src`, but
then everyone will need to install the library at that exact location.
NOTE: Specify the path to the directory which includes
`__phutil_library_init__.php`. For example, if your init file is in
`examplelib/src/__phutil_library_init__.php`, specify `examplelib/src`,
not just `examplelib/`.
The general intent here is:
- Put project-specific code in some directory in the project, like
`support/arc/src/`.
- Put shared code (e.g., which enforces general coding standards or hooks
up to unit tests or whatever) in a separate repository and check it out
next to other repositories.
- Or put everything in some standard location and add it to `include_path`.

File Metadata

Mime Type
text/x-diff
Expires
Wed, Dec 3, 3:07 AM (6 h, 26 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
433087
Default Alt Text
(8 KB)

Event Timeline

styx copyright 2020 sirocyl / ellie (kymkdd) / ncommander / styx contributors
Use of other names and brands is not intended to reflect a claim of, or right to, use the name or brand.
styx is an operating system using the Linux kernel and components, and "styx Linux" as a phrase does not reflect the inclusion of the Linux brand or trademark in the styx project.
Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.
Terms and Conditions (TODO: fix this!)