Document linkfarmking options and --edit-sources

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/README.md b/README.md
index b722bb9783c6827043072743a0cf04f07cfdcf0f..8e68db5df7e6e1894e56f2537f17d531f462e20c 100644 (file)
--- a/README.md
+++ b/README.md
@@ -157,6 +157,12 @@ nailing-cargo arranges this for you.  You can either put this file in
 `.gitignore`; or commit it to git; or you can tell nailing-cargo to
 save it as something like `Cargo.lock.example`.
 
+Depending on the circumstances, nailing-cargo uses a variety of
+strategies, including `--manifest-path` options, and linkfarming, to
+make out of tree builds.  Some crates don't natively support
+out-of-tree builds, in which case passing a `--linkfarm` option to
+nailing-cargo can be helpful.
+
 Configuring out-of-tree builds
 ------------------------------
 
@@ -352,6 +358,7 @@ Options
     * `online`: this subcommand makes no sense to run offline.  (The `-o` and `-O` options, and the configuration, can override this.)
     * `!target`: cargo would reject `--target=<arch>`; in this case nailing-cargo's `-T` option is ineffective.
     * `!target-dir`: cargo would reject `--target-dir`, so don't pass it.  (Usually we pass `--target-dir=target` when we pass `--manifest-path`, since cargo's default is `target` in the same directory as `Cargo.toml`.)
+    * `edits`: The purpose of this subcommand is to edit the source tree.  Enables `--edit-sources` mode.
 
     There are also some properties which should not be needed, but are
     provided for completeness.  Do not use these to solve the problem
@@ -363,10 +370,54 @@ Options
     * `!offline`: the build command would reject `--offline`, so never pass it.  *Not* overridden by configuration or command line.
 
 
-  * `--just-linkfarm`: Make the out-of-tree linkfarm as if for
-    `--cargo-lock-update`, but do not actually run any command, nor
-    try to copy back a a generated `Cargo.lock`.  Forces
-    `--keep-linkfarm` (even if the contrary is also specified).
+  * `--linkfarm[=no|shallow|git|full]`: Override nailing-cargo's
+    approach to out-of-tree builds.  Normally nailing-cargo chooses
+    automatically whether to make a linkfarm, and precisely what kind
+    of linkfarm, based on the cargo subcommand.  The linkfarm styles
+    are:
+
+    * `no`: Do not make a linkfarm; pass a `--manifest-path` option
+      pointing to the actual source directory.  This is the default
+      for most cargo commands.
+
+    * `shallow`: Symlink top-level objects in the source directory,
+      including whole subdirectories.  This the default when
+      nailing-cargo thinks cargo is going to update `Cargo.lock`.
+
+    * `git`: Make a deep linkfarm, with subdirectories.  Symlink
+      those objects tracked by git.
+
+    * `git`: Make a deep linkfarm and symlink every nondirectory found
+      in the source tree.  This will including all sorts of junk,
+      including for example editor backup files.
+
+    Whenever nailing-cargo linkfarms, old symlinks pointing back to
+    the source tree are deleted.  In each case, `Cargo.lock` is not
+    symlinked, but copied.  If nailing-cargo expects cargo to update
+    `Cargo.lock`, it will copy it back to the source tree afterwards.
+    Just `--linkfarm` is the same as `--linkfarm=git`.
+
+  * `--edit | --edit-sources | -E`: Permits the cargo command to edit
+    sources in the source tree.  This is achieved by *copying* the
+    entire source tree (all files tracked by git) into the destination
+    directory, and then copying back all changed files.  *Only git
+    tracked filles* can be edited by the cargo command; edits to
+    other files, and creation of new files, will be ignored.
+
+    If you are running out of tree builds for privsep reasons, you
+    should use git to review the edits made by the cargo command and
+    either stage and commit them, or reject them.
+
+    This is the default mode for `nailing-cargo fmt`.
+
+  * `--just-linkfarm[=shallow|git|full]`: Make the out-of-tree
+    linkfarm as if for `--cargo-lock-update`, but do not actually run
+    any command, nor try to copy back a a generated `Cargo.lock`.
+    Forces `--keep-linkfarm` (even if the contrary is also specified).
+
+    With a linkfarming mode, overrides (and is overridden by)
+    `--linkfarm=`.  Without a linkfarming mode, and without
+    `--linkfarm`, the default is `shallow`.
 
   * `--keep-linkfarm` | `--clean-linkfarm`: When doing an out-of-tree
     lockfile update, controls whether the linkfarm is kept afterwards.