From f0ee4946a6c45ba24296bf5dc7b404ef5d34f416 Mon Sep 17 00:00:00 2001 From: epriestley Date: Thu, 26 Jul 2012 12:01:39 -0700 Subject: [PATCH] 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 --- .../userguide/arcanist_commit_ranges.diviner | 10 +-- src/docs/userguide/arcanist_lint_unit.diviner | 2 +- .../userguide/arcanist_new_project.diviner | 67 ++++++++++++------- src/docs/userguide/libraries.diviner | 6 +- 4 files changed, 52 insertions(+), 33 deletions(-) diff --git a/src/docs/userguide/arcanist_commit_ranges.diviner b/src/docs/userguide/arcanist_commit_ranges.diviner index 59e31742c1..71977bb229 100644 --- a/src/docs/userguide/arcanist_commit_ranges.diviner +++ b/src/docs/userguide/arcanist_commit_ranges.diviner @@ -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 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. +an upstream branch, or the working copy isn't a Git working copy. 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: +`arc` reads five rulesets: # `args`, specified with `--base ` on the command line when you run 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 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(*) == diff --git a/src/docs/userguide/arcanist_lint_unit.diviner b/src/docs/userguide/arcanist_lint_unit.diviner index 25ca2a273c..0b24008476 100644 --- a/src/docs/userguide/arcanist_lint_unit.diviner +++ b/src/docs/userguide/arcanist_lint_unit.diviner @@ -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 "support/arcanist", // Relative path in this project diff --git a/src/docs/userguide/arcanist_new_project.diviner b/src/docs/userguide/arcanist_new_project.diviner index 0e09be87df..941c5c72f2 100644 --- a/src/docs/userguide/arcanist_new_project.diviner +++ b/src/docs/userguide/arcanist_new_project.diviner @@ -86,35 +86,35 @@ Other options include: - **arcanist_configuration**: the name of a subclass of @{class@arcanist:ArcanistConfiguration} which can add new command flags for this project or provide entirely new commands. - - **copyright_holder**: used by @{class@arcanist:ArcanistLicenseLinter} to - apply license notices to source files. - - **immutable_history**: controls how `arc diff` behaves in Git. See below. - - **phutil_libraries**: map of additional Phutil libraries to load at startup. + - **history.immutable**: controls how `arc diff` and some other commands + behave in Git and Mercurial. See below. + - **load**: list of additional Phutil libraries to load at startup. See below for details about path resolution, or see @{article:libphutil Libraries User Guide} for a general introduction to libphutil libraries. -= Immutable History = += History Mutability = -There are a lot of ways to use git, and Arcanist is flexible enough to handle -several of them. Git workflows divide into two major groups based on your -**doctrine of history mutability**. +Arcanist workflows run in two broad modes: either history is //mutable// or +//immutable//. Under a //mutable// history, `arc` commands may rewrite the +working copy history; under an //immutable// history, they may not. -Choose a **history mutability doctrine** by setting ##"immutable_history"## in -your ##.arcconfig##. Valid values are ##true## to enforce a **conservative -history mutability doctrine** or ##false## to enforce a **liberal history -mutability doctrine**. The default is ##false##. +You control history mutability by setting `history.immutable` to `true` or +`false` in your configuration. By default, it is `false` in Git (i.e., +//mutable//) and `true` in Mercurial (i.e., //immutable//). The sections below +explain how these settings affect workflows. -A **liberal history mutability doctrine** means you rewrite local history. You -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. +== History Mutability: Git == -A **conservative history mutability doctrine** means that you do not rewrite -local history. This is similar to how Mercurial works. 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. +In a workflow with //mutable// history, you rewrite local history. You develop +in feature branches, but squash or amend before pushing by using ##git commit +--amend##, ##git rebase -i##, or `git merge --squash`. Generally, one idea in +the remote is represented by one commit. + +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: @@ -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 revision. - `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** - `arc diff` will abort if it makes lint changes. - `arc diff` will not amend the commit message in HEAD after creating a revision. - `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 = @@ -136,9 +155,9 @@ relative path like this: { ... - "load_libraries": { - "examplelib" : "examplelib/src" - }, + "load": [ + "examplelib/src" + ], ... } diff --git a/src/docs/userguide/libraries.diviner b/src/docs/userguide/libraries.diviner index 51275150e6..46bcff1b9a 100644 --- a/src/docs/userguide/libraries.diviner +++ b/src/docs/userguide/libraries.diviner @@ -84,9 +84,9 @@ Phabricator. For example, you might write this file to { "project_id" : "libcustom", - "phutil_libraries" : { - "phabricator" : "phabricator/src/" - } + "load" : [ + "phabricator/src/" + ] } For details on creating a ##.arcconfig##, see