diff --git a/src/docs/user/userguide/arcanist.diviner b/src/docs/user/userguide/arcanist.diviner index 7f5d449526..b9c497007c 100644 --- a/src/docs/user/userguide/arcanist.diviner +++ b/src/docs/user/userguide/arcanist.diviner @@ -1,185 +1,185 @@ @title Arcanist User Guide @group userguide Guide to Arcanist, a command-line interface to Phabricator. Arcanists provides command-line access to many Phabricator tools (like Differential, Files, and Paste), integrates with static analysis ("lint") and unit tests, and manages common workflows like getting changes into Differential for review. A detailed command reference is available by running ##arc help##. This document provides an overview of common workflows and installation. Arcanist has technical, contributor-focused documentation here: = Quick Start = A quick start guide is available at @{article:Arcanist Quick Start}. It provides a much more compact summary of how to get `arc` set up and running for a new project. You may want to start there, and return here if you need more information. = Overview = Arcanist is a wrapper script that sits on top of other tools (e.g., Differential, linters, unit test frameworks, git, Mercurial, and SVN) and provides a simple command-line API to manage code review and some related revision control operations. For a detailed list of all available commands, run: $ arc help For detailed information about a specific command, run: $ arc help Arcanist allows you to do things like: - get detailed help about available commands with ##arc help## - send your code to Differential for review with ##arc diff## (for detailed instructions, see @{article:Arcanist User Guide: arc diff}) - show pending revision information with ##arc list## - find likely reviewers for a change with ##arc cover## - apply changes in a revision to the working copy with ##arc patch## - download a patch from Differential with ##arc export## - update Git commit messages after review with ##arc amend## - commit SVN changes with ##arc commit## - push Git and Mercurial changes with ##arc land## - view enhanced information about Git branches with ##arc branch## Once you've configured lint and unit test integration, you can also: - check your code for syntax and style errors with ##arc lint## (see @{article:Arcanist User Guide: Lint}) - run unit tests that cover your changes with ##arc unit## Arcanist integrates with other tools: - upload and download files with ##arc upload## and ##arc download## - create and view pastes with ##arc paste## Arcanist has some advanced features as well, you can: - execute Conduit method calls with ##arc call-conduit## - create or update libphutil libraries with ##arc liberate## - activate tab completion with ##arc shell-complete## - install arc as a pre-commit hook with ##arc svn-hook-pre-commit## or ##arc git-hook-pre-receive## - ...or extend Arcanist and add new commands. Except where otherwise noted, these workflows are generally agnostic to the underlying version control system and will work properly in git, Mercurial, or SVN repositories. = Installing Arcanist = Arcanist is meant to be installed on your local machine or development server -- whatever machine you're editing code on. It runs on: - Linux; - Other operating systems which are pretty similar to Linux, or which Linux is pretty similar to; - FreeBSD, a fine operating system held in great esteem by many; - Mac OS X (see @{article:Arcanist User Guide: Mac OS X}); and - Windows (see @{article:Arcanist User Guide: Windows}). Arcanist is written in PHP, so you need to install the PHP CLI first if you don't already have it. Arcanist should run on PHP 5.2 and newer. If you don't have PHP installed, you can download it from . To install Arcanist, pick an install directory and clone the code from GitHub: some_install_path/ $ git clone git://github.com/facebook/libphutil.git some_install_path/ $ git clone git://github.com/facebook/arcanist.git This should leave you with a directory structure like this some_install_path/ # Wherever you chose to install it. arcanist/ # Arcanist-specific code and libraries. libphutil/ # A shared library Arcanist depends upon. Now add ##some_install_path/arcanist/bin/## to your PATH environment variable. When you type "arc", you should see something like this: Usage Exception: No command provided. Try 'arc help'. If you get that far, you've done things correctly. If you get an error or have trouble getting this far, see these detailed guides: - On Windows: @{article:Arcanist User Guide: Windows} - On Mac OS X: @{article:Arcanist User Guide: Mac OS X} You can later upgrade Arcanist and libphutil to the latest versions with `arc upgrade`: $ arc upgrade == Installing Arcanist for a Team == Arcanist changes quickly, so it can be something of a headache to get it installed and keep people up to date. Here are some approaches you might be able to use: - Facebook does most development on development servers, which have a standard environment and NFS mounts. Arcanist and libphutil themselves live on an NFS mount, and the default `.bashrc` adds them to the PATH. Updating the mount source updates everyone's versions, and new employees have a working `arc` when they first log in. - Another common approach is to write an install script as an action into existing build scripts, so users can run `make install-arc` or `ant install-arc` or similar. - In general, if this sucks and is causing you pain, let us know (see @{article:Give Feedback! Get Support!}). We're planning to improve this at some point, but it's somewhat complicated to get right. While it can take a little time to set up, we aren't getting feedback that it's a persistent pain point, so it hasn't been a priority. == Installing Tab Completion == If you use ##bash##, you can set up tab completion by adding something like this to your ##.bashrc##, ##.profile## or similar: source /path/to/arcanist/resources/shell/bash-completion == Configuration == Some Arcanist commands can be configured. This configuration is read from several sources: # A customization can force any setting with @{method@arcanist:ArcanistWorkingCopyIdentity::setRuntimeConfig}. # User can specify settings for working copy in `arc/config` file located in VCS directory (e.g. `.git/arc/config`) in JSON format. This file can also be modified by running `arc set-config --local`. # Repository can specify its config in `.arcconfig` in JSON format. # User can specify the settings in `~/.arcrc` (JSON) through the `config` key. This file can be modified also by `arc set-config --global`. # Machine can specify the settings with `/etc/arcconfig` (JSON). On Windows, the file path is 'C:\ProgramData\Phabricator\Arcanist\config`. The first place where the setting is defined wins. -Existing settings can be printed with `arc set-config --show`. +Existing settings can be printed with `arc get-config`. == Next Steps == Continue by: - setting up a new project for use with `arc`, with @{article:Arcanist User Guide: Configuring a New Project}; or - learning how to use `arc` to send changes for review with @{article:Arcanist User Guide: arc diff}. Advanced topics are also available. These are detailed guides to configuring technical features of `arc` that refine its behavior. You do not need to read them to get it working. - @{article:Arcanist User Guide: Commit Ranges} - @{article:Arcanist User Guide: Lint} - @{article:Arcanist User Guide: Customizing Existing Linters} - @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows} - @{article:Arcanist User Guide: Code Coverage} - @{article:Arcanist User Guide: Repository Hooks} diff --git a/src/docs/user/userguide/arcanist_new_project.diviner b/src/docs/user/userguide/arcanist_new_project.diviner index c8f9389572..c29a53dfb4 100644 --- a/src/docs/user/userguide/arcanist_new_project.diviner +++ b/src/docs/user/userguide/arcanist_new_project.diviner @@ -1,227 +1,227 @@ @title Arcanist User Guide: Configuring a New Project @group userguide Explains how to configure Arcanist projects with `.arcconfig` files. = Overview = In most cases, you should be able to use `arc` without specifically configuring your project for it. If you want to adjust `arc` behaviors, you can create a `.arcconfig` file in your project to provide project-specific settings. = .arcconfig Basics = An `.arcconfig` file is a JSON file which you check into your project's root. Arcanist uses `.arcconfig` files to customize a number of things about its behavior. The first thing you're likely to want to configure is the URI for your Phabricator install. A simple, valid file looks something like this: name=.arcconfig { "phabricator.uri" : "https://phabricator.example.com/" } For details on available options, see below. NOTE: You should commit your `.arcconfig` file! It contains project configuration, not user configuration. = Advanced .arcconfig = Common options are: - **phabricator.uri**: the URI for the Phabricator install that `arc` should connect to when run in this project. This option was previously called `conduit_uri`. - **repository.callsign**: The callsign of this repository in Diffusion. Normally, `arc` can detect this automatically, but if it can't figure it out you can specify it explicitly. Use `arc which` to understand the detection process. - **history.immutable**: Configures `arc` to use workflows which never rewrite history in the working copy. By default, `arc` will perform some rewriting of unpublished history (amending commit messages, squash merging) on some workflows in Git. The distinctions are covered in detail below. Other options include: - **load**: list 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. - **project.name**: name an "Arcanist Project" to associate this working copy (Git, Mercurial) or directory (SVN) with. Previously, this was a required option, but `arc` can now usually operate without it in Git and Mercurial. This option was previously called `project_id`. - **https.cabundle**: specifies the path to an alternate certificate bundle for use when making HTTPS connections. - **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: Lint}. - **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}. These options are supported, but their use is discouraged: - **http.basicauth.user**: specify an HTTP basic auth username for use when connecting to Phabricator. - **http.basicauth.pass**: specify an HTTP basic auth password for use when connecting to Phabricator. - **https.blindly-trust-domains**: a list of domains to trust blindly over HTTPS, even if their certificates are invalid. This is a brute force solution to certificate validity problems, and is discouraged. Instead, use valid certificates. -For a complete list of options, run `arc set-config --show`. Although all +For a complete list of options, run `arc get-config`. Although all options can be set in `.arcconfig`, some options (like `editor`) usually do not make sense to set here because they're likely to vary from user to user. = History Mutability = Arcanist workflows run in two broad modes: either history is //mutable// or //immutable//. Under a //mutable// history, `arc` commands may rewrite the working copy history; under an //immutable// history, they may not. You control history mutability by setting `history.immutable` to `true` or `false` in your configuration. By default, it is `false` in Git (i.e., //mutable//) and `true` in Mercurial (i.e., //immutable//). The sections below explain how these settings affect workflows. == History Mutability: Git == In a workflow with //mutable// history, you rewrite local history. You develop in feature branches, but squash or amend before pushing by using ##git commit --amend##, ##git rebase -i##, or `git merge --squash`. Generally, one idea in the remote is represented by one commit. In a workflow with //immutable// history, you do not rewrite local history. 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. - `arc amend` will amend the commit message in HEAD with information from the corresponding or specified Differential revision. - **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. - `arc amend` will exit with an error message. == History Mutability: Mercurial == Before version 2.2, stock Mercurial has no history mutation commands, so this setting has no effect. With Mercurial 2.2. or newer, making history //mutable// means: - **Mutable** (versions 2.2 and newer) - `arc diff` will amend the commit message in `.` after creating a revision. - `arc amend` will amend the commit message in `.` with information from the corresponding or specified Differential revision. - **Immutable** (or versions prior to 2.2) - `arc diff` will not amend the commit message in `.` after creating a revision. - `arc amend` will exit with an error message. = How Libraries Are Located = If you specify an external library to load, like 'examplelib', and use a relative path like this: { ... "load": [ "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`. = Running Without .arcconfig = Although you don't need to set up `.arcconfig`, and you can run `arc` command that require a working copy in any Git, Subversion or Mercurial working copy, some features won't work unless you set up an `.arcconfig` file. Without `.arcconfig`: - You will need to set a default Phabricator URI with `arc set-config default `, 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. = Next Steps = Continue by: - returning to @{article:Arcanist User Guide}.