From 904d44492acfd058ae61908102b9cdc1e89a795c Mon Sep 17 00:00:00 2001 From: epriestley Date: Fri, 15 Jun 2012 14:02:19 -0700 Subject: [PATCH] Document base commit DSL Summary: Documentation for D2748. Test Plan: Generated and read docs. Reviewers: dschleimer, zeeg Reviewed By: dschleimer CC: aran, csilvers Maniphest Tasks: T1233 Differential Revision: https://secure.phabricator.com/D2750 --- src/docs/userguide/arcanist.diviner | 11 +- .../userguide/arcanist_commit_ranges.diviner | 148 ++++++++++++++++++ 2 files changed, 153 insertions(+), 6 deletions(-) create mode 100644 src/docs/userguide/arcanist_commit_ranges.diviner 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 @@ -86,14 +86,13 @@ When you type "arc", you should see something like this: 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 == 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 ` on the command line when you run + a command. This ruleset is processed first. + # `local`, specified with `arc set-config --local base `. 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 `. 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, + +Debug your rules: + + $ arc diff --base arc:verbose + +Understand rules processing: + + $ arc which + $ arc which --base '' + $ arc which --base 'arc:verbose, ' + += 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}.