Page MenuHomestyx hydra
Files F233266

No OneTemporary
Actions

View Options

diff --git a/src/docs/userguide/arcanist.diviner b/src/docs/userguide/arcanist.diviner
index 873d55bb22..2047816ee1 100644
--- a/src/docs/userguide/arcanist.diviner
+++ b/src/docs/userguide/arcanist.diviner
@@ -1,130 +1,129 @@
@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 a high level overview of common workflows.
Arcanist has technical, contributor-focused documentation here:
<http://www.phabricator.com/docs/arcanist/>
= 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.
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##
- 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 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##
- 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, 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 <http://www.php.net/>.
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: @{Arcanist User Guide: Windows}
- - On Mac OS X: @{Arcanist User Guide: Mac OS X}
+ - On Windows: @{article:Arcanist User Guide: Windows}
+ - On Mac OS X: @{article:Arcanist User Guide: Mac OS X}
-The code changes quickly, so remember to update regularly, by running
-`git pull` on the two directories:
+You can later upgrade Arcanist and libphutil to the latest versions with
+`arc upgrade`:
- some_install_path/arcanist/ $ git pull
- some_install_path/libphutil/ $ git pull
+ $ arc upgrade
== 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:
- 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
== Next Steps ==
Continue by:
- learning how to use `arc` to send changes for review with
@{article:Arcanist User Guide: arc diff}.
diff --git a/src/docs/userguide/arcanist_commit_ranges.diviner b/src/docs/userguide/arcanist_commit_ranges.diviner
new file mode 100644
index 0000000000..fa3027c416
--- /dev/null
+++ b/src/docs/userguide/arcanist_commit_ranges.diviner
@@ -0,0 +1,148 @@
+@title Arcanist User Guide: Commit Ranges
+@group userguide
+
+Explains how commit ranges work in Arcanist.
+
+= Overview =
+
+//In Subversion, `arc` commands always operate on the uncommitted changes in the
+working copy. If you use Subversion, this document is not relevant to you.//
+
+In Git and Mercurial, many `arc` commands (notably, `arc diff`) operate on a
+range of commits beginning with some commit you specify and ending with the
+working copy state.
+
+Since the end of the range is fixed (the working copy state), you only need to
+specify the beginning of the range. This is called the "base commit". You can do
+this explicitly when you run commands:
+
+ $ arc diff HEAD^ # git: just the most recent commit
+ $ arc diff .^ # hg: just the most recent commit
+
+You can also configure `arc` so it defaults to some base commit, or figures out
+the base commit using a (potentially sophisticated) ruleset.
+
+NOTE: This document describes a new mechanism for determining base commits. It
+is subject to change. There are currently several other mechanisms available as
+well, mentioned in other documents. As this mechanism matures, it should replace
+other mechanisms and defaults.
+
+= Configuring Base Commit Rules =
+
+Base commit rule configuration may be more complicated than you expect. This is
+because people use many different workflows in Git and Mercurial, and have very
+different expectations about what base commit `arc` should pick when run. To
+make matters worse, some of the most common ways of thinking about which commits
+represent a change are incompatible when selecting defaults.
+
+Historically, we tried to use a number of heuristics and simpler approaches to
+determine the base commit, but there is so much diversity in how people think
+about version control and what they expect to happen that some users were always
+unhappy.
+
+Although ruleset configuration is fairly complex, it's powerful enough that you
+should be able to get exactly the behavior you want.
+
+To determine the base commit, `arc` processes //rules// one at a time until it
+gets a match (a rule which identifies a valid commit). The first match is the
+base commit that is used to determine the beginning of the commit range.
+
+A //rule// looks like this:
+
+ arc:upstream
+
+A rule may //match//, meaning that it identifies some valid commit in the
+working copy, or //fail//, meaning that it does not identify a valid commit. For
+instance, the rule `arc:upstream` will //match// if the current Git branch
+tracks an upstream branch, but //fail// if the current Git branch does not track
+an upstream branch. When a rule fails, processing continues with the next rule.
+Some rules can never match but produce useful side effects instead. These are
+described below.
+
+A //ruleset// is a comma-separated list of rules:
+
+ arc:upstream, arc:prompt
+
+`arc` reads four rulesets:
+
+ # `args`, specified with `--base <ruleset>` on the command line when you run
+ a command. This ruleset is processed first.
+ # `local`, specified with `arc set-config --local base <ruleset>`. This
+ ruleset is local to the working copy where it is set, and is processed
+ second.
+ # `project`, specified by setting the "base" key in `.arcconfig`. This
+ ruleset is bound to the project where it is configured, and is processed
+ third.
+ # `global`, specified with `arc set-config base <ruleset>`. This ruleset is
+ global for the current user, and is processed last.
+
+The rules in each ruleset are processed one at a time until a valid base commit
+is found. Valid rules are listed below. In this list, "*" means "any string".
+
+ - `git:*` Use the specified symbolic commit, if it exists.
+ - `git:merge-base(*)` Use the merge-base of HEAD and the specified symbolic
+ commit, if it exists.
+ - `arc:upstream` Use the merge-base of the current branch's upstream and
+ HEAD, if it exists.
+ - `arc:prompt` Prompt the user to provide a commit.
+ - `arc:empty` Use the empty state (as though the repository were completely
+ empty, the range will include every commit that is an ancestor of the
+ working copy).
+
+Rules are also available which change the processing order of rulesets:
+
+ - `arc:args`, `arc:local`, `arc:project`, `arc:global` Stop processing the
+ current ruleset and begin processing the specified ruleset. The current
+ ruleset will resume processing after the specified ruleset is exhausted.
+ - `arc:yield` Stop processing the current ruleset and begin processing the
+ next ruleset. The current ruleset will resume processing after other
+ rulesets have processed or when it next appears in the processing order,
+ whichever comes first.
+ - `arc:halt` Stops processing all rules. This will cause the command you ran
+ to fail, but can be used to avoid running rules which would otherwise
+ be processed later.
+
+Additionally, there are some rules which are probably useful mostly for testing
+or debugging rulesets:
+
+ - `arc:verbose` Turns on verbose logging of rule processing.
+ - `arc:skip` This rule has no effect.
+ - `literal:*` Use the specified commit literally. Almost certainly wrong in
+ production rules.
+
+= Examples =
+
+Diff against `origin/master` if it exists, and prompt if it doesn't:
+
+ git:merge-base(origin/master), arc:prompt
+
+Diff against the upstream if it exists, or just use the last commit if it
+doesn't:
+
+ arc:upstream, git:HEAD^
+
+As a user, ignore project rules and always use my rules:
+
+ (local) arc:global, arc:halt
+
+As a project maintainer, respect user rules over project rules:
+
+ (project) arc:yield, <defaults>
+
+Debug your rules:
+
+ $ arc diff --base arc:verbose
+
+Understand rules processing:
+
+ $ arc which
+ $ arc which --base '<ruleset>'
+ $ arc which --base 'arc:verbose, <ruleset>'
+
+= Next Steps =
+
+Continue by:
+
+ - learning about `arc diff` in more detail with
+ @{article:Arcanist User Guide: arc diff}; or
+ - returning to @{article:Arcanist User Guide}.

File Metadata

Mime Type
text/x-diff
Expires
Mon, Jul 28, 12:58 AM (1 w, 20 h ago)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
186304
Default Alt Text
(12 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!)