1
0
Fork 0
mirror of https://we.phorge.it/source/phorge.git synced 2024-11-23 07:12:41 +01:00

Update documentation for D3045

Summary: Some minor updates for changes in D3045 and clarity.

Test Plan: Read documentation.

Reviewers: dschleimer, bos, btrahan, vrana

Reviewed By: dschleimer

CC: aran, cbiesinger

Maniphest Tasks: T1507, T1546

Differential Revision: https://secure.phabricator.com/D3046
This commit is contained in:
epriestley 2012-07-26 12:01:39 -07:00
parent 94bc4003f1
commit f0ee4946a6
4 changed files with 52 additions and 33 deletions

View file

@ -55,15 +55,15 @@ 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 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 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 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. an upstream branch, or the working copy isn't a Git working copy. When a rule
Some rules can never match but produce useful side effects instead. These are fails, processing continues with the next rule. Some rules can never match but
described below. produce useful side effects instead. These are described below.
A //ruleset// is a comma-separated list of rules: A //ruleset// is a comma-separated list of rules:
arc:upstream, arc:prompt arc:upstream, arc:prompt
`arc` reads four rulesets: `arc` reads five rulesets:
# `args`, specified with `--base <ruleset>` on the command line when you run # `args`, specified with `--base <ruleset>` on the command line when you run
a command. This ruleset is processed first. a command. This ruleset is processed first.
@ -278,7 +278,7 @@ it has a different bookmark. When run from `C3`, it will select `C2` and `C3`.
However, this rule will select the wrong commit range in some cases (for However, this rule will select the wrong commit range in some cases (for
example, if the "zebra" bookmark has moved on, the rule will no longer stop on example, if the "zebra" bookmark has moved on, the rule will no longer stop on
`C3` and will select `C2`, `C3` and `C4` when run from `C4). `C3` and will select `C2`, `C3` and `C4` when run from `C4`).
== arc:exec(*) == == arc:exec(*) ==

View file

@ -38,7 +38,7 @@ then make the library loadable by adding it to your ##.arcconfig## like this:
{ {
// ... // ...
"phutil_libraries" : [ "load" : [
// ... // ...
"/path/to/my/library", // Absolute path "/path/to/my/library", // Absolute path
"support/arcanist", // Relative path in this project "support/arcanist", // Relative path in this project

View file

@ -86,35 +86,35 @@ Other options include:
- **arcanist_configuration**: the name of a subclass of - **arcanist_configuration**: the name of a subclass of
@{class@arcanist:ArcanistConfiguration} which can add new command flags for @{class@arcanist:ArcanistConfiguration} which can add new command flags for
this project or provide entirely new commands. this project or provide entirely new commands.
- **copyright_holder**: used by @{class@arcanist:ArcanistLicenseLinter} to - **history.immutable**: controls how `arc diff` and some other commands
apply license notices to source files. behave in Git and Mercurial. See below.
- **immutable_history**: controls how `arc diff` behaves in Git. See below. - **load**: list of additional Phutil libraries to load at startup.
- **phutil_libraries**: map of additional Phutil libraries to load at startup.
See below for details about path resolution, or see See below for details about path resolution, or see
@{article:libphutil Libraries User Guide} for a general introduction to @{article:libphutil Libraries User Guide} for a general introduction to
libphutil libraries. libphutil libraries.
= Immutable History = = History Mutability =
There are a lot of ways to use git, and Arcanist is flexible enough to handle Arcanist workflows run in two broad modes: either history is //mutable// or
several of them. Git workflows divide into two major groups based on your //immutable//. Under a //mutable// history, `arc` commands may rewrite the
**doctrine of history mutability**. working copy history; under an //immutable// history, they may not.
Choose a **history mutability doctrine** by setting ##"immutable_history"## in You control history mutability by setting `history.immutable` to `true` or
your ##.arcconfig##. Valid values are ##true## to enforce a **conservative `false` in your configuration. By default, it is `false` in Git (i.e.,
history mutability doctrine** or ##false## to enforce a **liberal history //mutable//) and `true` in Mercurial (i.e., //immutable//). The sections below
mutability doctrine**. The default is ##false##. explain how these settings affect workflows.
A **liberal history mutability doctrine** means you rewrite local history. You == History Mutability: Git ==
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 In a workflow with //mutable// history, you rewrite local history. You develop
local history. This is similar to how Mercurial works. You develop in feature in feature branches, but squash or amend before pushing by using ##git commit
branches and push them without squashing commits. You do not use ##git commit --amend##, ##git rebase -i##, or `git merge --squash`. Generally, one idea in
--amend## or ##git rebase -i##. Generally, one idea in the remote is represented the remote is represented by one commit.
by many commits.
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: Practically, these are the differences you'll see based on your setting:
@ -123,11 +123,30 @@ Practically, these are the differences you'll see based on your setting:
- `arc diff` will amend the commit message in HEAD after creating a - `arc diff` will amend the commit message in HEAD after creating a
revision. revision.
- `arc land` will default to the `--squash` strategy. - `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** - **Immutable**
- `arc diff` will abort if it makes lint changes. - `arc diff` will abort if it makes lint changes.
- `arc diff` will not amend the commit message in HEAD after creating a - `arc diff` will not amend the commit message in HEAD after creating a
revision. revision.
- `arc land` will default to the `--merge` strategy. - `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 = = How Libraries Are Located =
@ -136,9 +155,9 @@ relative path like this:
{ {
... ...
"load_libraries": { "load": [
"examplelib" : "examplelib/src" "examplelib/src"
}, ],
... ...
} }

View file

@ -84,9 +84,9 @@ Phabricator. For example, you might write this file to
{ {
"project_id" : "libcustom", "project_id" : "libcustom",
"phutil_libraries" : { "load" : [
"phabricator" : "phabricator/src/" "phabricator/src/"
} ]
} }
For details on creating a ##.arcconfig##, see For details on creating a ##.arcconfig##, see