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`.
 
 `.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
 ------------------------------
 
 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`.)
     * `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
 
     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.
 
 
     * `!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.
 
   * `--keep-linkfarm` | `--clean-linkfarm`: When doing an out-of-tree
     lockfile update, controls whether the linkfarm is kept afterwards.