diff --git a/src/docs/userguide/arcanist.diviner b/src/docs/userguide/arcanist.diviner index 2047816ee1..7ce88b1cb6 100644 --- a/src/docs/userguide/arcanist.diviner +++ b/src/docs/userguide/arcanist.diviner @@ -9,11 +9,18 @@ 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 a high level overview of common workflows. +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., @@ -21,10 +28,19 @@ 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## + - 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## @@ -37,6 +53,7 @@ Arcanist allows you to do things like: 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: @@ -60,7 +77,8 @@ 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, Mac OS X, and +whatever machine you're editing code on. It runs on Linux, +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 @@ -96,9 +114,9 @@ You can later upgrade Arcanist and libphutil to the latest versions with == Installing Arcanist for a Team == -Arcanist changes quickly and doesn't currently have an auto-update mechanism, -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: +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 @@ -125,5 +143,18 @@ to your ##.bashrc##, ##.profile## or similar: 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} \ No newline at end of file diff --git a/src/docs/userguide/arcanist_commit_ranges.diviner b/src/docs/userguide/arcanist_commit_ranges.diviner index 71977bb229..5f331c3f7b 100644 --- a/src/docs/userguide/arcanist_commit_ranges.diviner +++ b/src/docs/userguide/arcanist_commit_ranges.diviner @@ -3,6 +3,10 @@ Explains how commit ranges work in Arcanist. +This is an advanced user guide which covers a complicated topic in detail. If +you're just getting started, you don't need to look at this yet. Instead, start +with the @{article:Arcanist User Guide}. + = Overview = //In Subversion, `arc` commands always operate on the uncommitted changes in the diff --git a/src/docs/userguide/arcanist_coverage.diviner b/src/docs/userguide/arcanist_coverage.diviner index bcb29e5b48..0f28258d89 100644 --- a/src/docs/userguide/arcanist_coverage.diviner +++ b/src/docs/userguide/arcanist_coverage.diviner @@ -3,6 +3,15 @@ Explains code coverage features in Arcanist and Phabricator. +This is a configuration guide that helps you set up advanced features. If you're +just getting started, you don't need to look at this yet. Instead, start with +the @{article:Arcanist User Guide}. + +Before you can configure coverage features, you must set up unit test +integration. For instructions, see @{article:Arcanist User Guide: Configuring +a New Project} and @{article:Arcanist User Guide: Customizing +Lint, Unit Tests and Workflows}. + = Using Coverage Features = If your project has unit tests with coverage integration (see below for diff --git a/src/docs/userguide/arcanist_diff.diviner b/src/docs/userguide/arcanist_diff.diviner index 2396b61e3e..fcfbdf778d 100644 --- a/src/docs/userguide/arcanist_diff.diviner +++ b/src/docs/userguide/arcanist_diff.diviner @@ -1,17 +1,17 @@ @title Arcanist User Guide: arc diff @group userguide -Guide to running `arc diff`. - -= Overview = +Guide to running `arc diff`, to send changes to Differential for review. This article assumes you have `arc` installed and running; if not, see @{article:Arcanist User Guide} for help getting it set up. -This document is intended for users of `arc diff`, and is a practical -guide to using it to send changes for review. If you are installing and -configuring Phabricator, make sure to read the more comprehensive information in -@{article:Arcanist User Guide: Configuring a New Project}. +Before running `arc diff`, you should create a `.arcconfig` file. If someone +set things up for you, they may already have done this. See +@{article:Arcanist User Guide: Configuring a New Project} for instructions and +information. + += Overview = While `arc` has a large number of commands that interface with various Phabricator applications, the primary use of `arc` is to send changes for diff --git a/src/docs/userguide/arcanist_extending_lint.diviner b/src/docs/userguide/arcanist_extending_lint.diviner index 58682c0735..b10b47e9cb 100644 --- a/src/docs/userguide/arcanist_extending_lint.diviner +++ b/src/docs/userguide/arcanist_extending_lint.diviner @@ -3,6 +3,14 @@ Explains how to customize existing linters. +This is a configuration guide that helps you set up advanced features. If you're +just getting started, you don't need to look at this yet. Instead, start with +the @{article:Arcanist User Guide}. + +This guide explains how to refine lint behavior. To configure lint in the first +place, see @{article:Arcanist User Guide: Configuring a New Project} and +@{article:Arcanist User Guide: Lint}. + = Overview = Arcanist ships with a number of linters which you may want to reuse in whole diff --git a/src/docs/userguide/arcanist_lint.diviner b/src/docs/userguide/arcanist_lint.diviner index d82312165b..760b262a50 100644 --- a/src/docs/userguide/arcanist_lint.diviner +++ b/src/docs/userguide/arcanist_lint.diviner @@ -3,6 +3,14 @@ Guide to lint, linters, and linter configuration. +This is a configuration guide that helps you set up advanced features. If you're +just getting started, you don't need to look at this yet. Instead, start with +the @{article:Arcanist User Guide}. + +This guide explains how lint works when configured in an `arc` project. If +you haven't set up a project yet, do that first. For instructions, see +@{article:Arcanist User Guide: Configuring a New Project}. + = Overview = "Lint" refers to a general class of programming tools which analyze source code diff --git a/src/docs/userguide/arcanist_lint_unit.diviner b/src/docs/userguide/arcanist_lint_unit.diviner index 0b24008476..06a49aae23 100644 --- a/src/docs/userguide/arcanist_lint_unit.diviner +++ b/src/docs/userguide/arcanist_lint_unit.diviner @@ -3,6 +3,10 @@ Explains how to build new classes to control how Arcanist behaves. +This is a configuration guide that helps you set up advanced features. If you're +just getting started, you don't need to look at this yet. Instead, start with +the @{article:Arcanist User Guide}. + = Overview = Arcanist has some basic configuration options available in the `.arcconfig` diff --git a/src/docs/userguide/arcanist_mac_os_x.diviner b/src/docs/userguide/arcanist_mac_os_x.diviner index b8c2fdcc7e..a34adfbf5d 100644 --- a/src/docs/userguide/arcanist_mac_os_x.diviner +++ b/src/docs/userguide/arcanist_mac_os_x.diviner @@ -24,3 +24,8 @@ You can edit your `~/.profile` to permanently configure environmental variables. Now you should be able to run `arc` like a normal command. += Next Steps = + +Continue by: + + - returning to @{article:Arcanist User Guide}. diff --git a/src/docs/userguide/arcanist_new_project.diviner b/src/docs/userguide/arcanist_new_project.diviner index 941c5c72f2..19eb5facf1 100644 --- a/src/docs/userguide/arcanist_new_project.diviner +++ b/src/docs/userguide/arcanist_new_project.diviner @@ -1,62 +1,20 @@ @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 `, 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. +Explains how to configure Arcanist projects with `.arcconfig` files. = .arcconfig Basics = +An ##.arcconfig## file is a JSON file which you check into your project's root. + Arcanist uses ##.arcconfig## files to determine a number of things about project -configuration. For instance, these are things it figures out from +configuration. For instance, these are some of the 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: { @@ -72,6 +30,9 @@ Here's what these options mean: For an exhaustive list of available options, see below. +NOTE: You should commit your `.arcconfig` file! It contains project +configuration, not user configuration. + = Advanced .arcconfig = Other options include: @@ -193,3 +154,50 @@ The general intent here is: 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}. diff --git a/src/docs/userguide/arcanist_quick_start.diviner b/src/docs/userguide/arcanist_quick_start.diviner new file mode 100644 index 0000000000..0aeb0f9198 --- /dev/null +++ b/src/docs/userguide/arcanist_quick_start.diviner @@ -0,0 +1,100 @@ +@title Arcanist Quick Start +@group userguide + +Quick guide to getting Arcanist working for a new project. + +This is a summary of steps to install Arcanist, configure a project for use with +it, and run `arc` to send changes for review. + += Install Arcanist = + +For detailed instructions on installing Arcanist, see +@{article:Arcanist User Guide}. + + - For Mac OS X, see @{article:Arcanist User Guide: Mac OS X}. + - For Windows, see @{article:Arcanist User Guide: Windows}. + +First, install dependencies: + + - Install PHP. + - Install Git. + +Then install Arcanist itself: + + $ mkdir somewhere/ + $ cd somewhere/ + somewhere/ $ git clone git://github.com/facebook/libphutil.git + somewhere/ $ git clone git://github.com/facebook/arcanist.git + +Add `arc` to your path: + + $ export PATH="$PATH:/somewhere/arcanist/bin/" + +This won't work for Windows, see @{article:Arcanist User Guide: Windows} for +instructions. + += Configure Your Project = + +For detailed instructions on project configuration, see +@{article:Arcanist User Guide: Configuring a New Project}. + +Create a `.arcconfig` file in your project's working copy: + + $ cd yourproject/ + yourproject/ $ $EDITOR .arcconfig + yourproject/ $ cat .arcconfig + { + "project_id" : "yourprojectname", + "conduit_uri" : "https://phabricator.example.com/" + } + +Set `project_id` to a string that identifies the project. + +Set `conduit_uri` to the URI for your Phabricator install (where `arc` +should send changes to). + +NOTE: You should **commit this file** to the repository. + += Install Arcanist Credentials = + +Credentials allow you to authenticate. You must have an account on Phabricator +before you can perform this step. + + $ cd yourproject/ + yourproject/ $ arc install-certificate + ... + +Follow the instructions. This will link your user account on your local machine +to your Phabricator account. + += Send Changes For Review = + +For detailed instructions on using `arc diff`, see +@{article:Arcanist User Guide: arc diff}. + +Subversion: + + $ $EDITOR file.c + $ arc diff + +Git: + + $ $EDITOR file.c + $ git commit -a -m '...' + $ arc diff HEAD^ + +Mercurial: + + $ $EDITOR file.c + $ hg commit -m '...' + $ arc diff tip^ + += Next Steps = + +Continue by: + + - learning more about project configuration with + @{article:Arcanist User Guide: Configuring a New Project}; or + - learning more about `arc diff` with + @{article:Arcanist User Guide: arc diff}; or + - returning to @{article:Arcanist User Guide}. diff --git a/src/docs/userguide/arcanist_windows.diviner b/src/docs/userguide/arcanist_windows.diviner index 550a975b1e..67a9022c5a 100644 --- a/src/docs/userguide/arcanist_windows.diviner +++ b/src/docs/userguide/arcanist_windows.diviner @@ -77,3 +77,8 @@ And this for GitPad (you may need to adjust the path): name=GitPad $ arc set-config editor "\"C:\Users\yourusername\AppData\Roaming\GitPad\GitPad.exe\"" += Next Steps = + +Continue by: + + - returning to @{article:Arcanist User Guide}.