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:
parent
94bc4003f1
commit
f0ee4946a6
4 changed files with 52 additions and 33 deletions
|
@ -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(*) ==
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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"
|
||||||
},
|
],
|
||||||
...
|
...
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
|
Loading…
Reference in a new issue