X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=README.md;h=78acb9e831384e14665abc74d6f5afcbdccb11b1;hb=b3f50653a32ee3d398d141280cdc9d7f93402ed0;hp=8e68db5df7e6e1894e56f2537f17d531f462e20c;hpb=aeba85d6423c33c0f10975027d676bb944e4c033;p=nailing-cargo.git

diff --git a/README.md b/README.md
index 8e68db5..78acb9e 100644
--- a/README.md
+++ b/README.md
@@ -248,7 +248,7 @@ rules when interpreting its command line:
     treated as the start of the `<cargo-opts>`.
 
   * `<cargo-opts>` are terminated by `--` (which is removed) or the
-    first argument which does not start with a `-`.
+    first argument which does not start with a `-` or `+`.
 
     (It is not possible to get nailing-cargo to pass the value `--`
     as a separate argument to a cargo global option, but cargo global
@@ -280,6 +280,9 @@ Options
   * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
        everywhere, and do not run any build command.
 
+  * `-f` | `--force`: Force going ahead even if problems are likely.
+    (E.g., due to missing `-E` option.)
+
   * `-T<arch>` | `--target=<arch>`
 
     Specify target architecture.
@@ -290,7 +293,13 @@ Options
     If `<arch>` starts with a capital ascii letter, it is an alias
     for some other arch: it is looked up in the configuration, and
     then in the builtin arch alias list.  The builtin list is
-    equivalent to: `[arch]` `RPI='arm-unknown-linux-gnueabihf'`.
+    equivalent to:
+
+```
+[arch]
+RPI="arm-unknown-linux-gnueabihf"
+WASM="wasm32-unknown-unknown"
+```
 
   * `-o` | `--online` | `-O` | `--offline`
 
@@ -339,8 +348,13 @@ Options
     options to pass to cargo, whether cargo needs to be online, and
     whether cargo might want to update `Cargo.lock`.
 
-    nailing-cargo knows about `update`, `generate-lockfile` and
-    `fetch`; all other subcommands are (silently) treated the same way
+    nailing-cargo knows about the following commands:
+     * `fetch`
+     * `fmt`
+     * `generate-lockfile`
+     * `update`
+
+    All other subcommands are (silently) treated the same way
     as `build` (ie, no subcommand properties).  See
     `--subcommand-props` for more detail about how the
     subcommand affects nailing-cargo's behaviour.
@@ -356,9 +370,12 @@ Options
 
     * `lock_update`: cargo will want to update `Cargo.lock`.  (The `-u` and `-U` options override this.)
     * `online`: this subcommand makes no sense to run offline.  (The `-o` and `-O` options, and the configuration, can override this.)
+    * `edits`: The purpose of this subcommand is to edit the source tree.  Imples that `--edit-sources` is necessary (unless `--force`).
+    * `creates`: The purpose of this subcommand is to edit the source tree and create new files in it.  Imples that `-EE` (`--edit-sources`, twice) is necessary (unless `--force`).
     * `!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.
+    * `linkfarm-shallow`: Make the default be `--linkfarm=shallow`.  This is the default for `miri` and can also be used for other subcommands which do not understandg `--manifest-path` properly.
+    * `linkfarm-gitclean`: Make the defaults be `--linkfarm=git` and `--preclean-build=src`.
 
     There are also some properties which should not be needed, but are
     provided for completeness.  Do not use these to solve the problem
@@ -385,9 +402,10 @@ Options
       nailing-cargo thinks cargo is going to update `Cargo.lock`.
 
     * `git`: Make a deep linkfarm, with subdirectories.  Symlink
-      those objects tracked by git.
+      those objects tracked by git.  This is the default for
+      `cargo publish`.
 
-    * `git`: Make a deep linkfarm and symlink every nondirectory found
+    * `full`: 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.
 
@@ -404,11 +422,19 @@ Options
     tracked filles* can be edited by the cargo command; edits to
     other files, and creation of new files, will be ignored.
 
+    When this option is repeated (**`-EE`**), the cargo subcommand can
+    create new files including dotfiles (but nothing in the toplevel
+    `target` and nothing called `.git`).  (This also enables
+    `--preclean=src` by default.)
+
     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`.
+    This option is overridden by a subsequent `--linkfarm` options.
+
+    `-E` or `-f` is needed for `nailing-cargo fmt`.  `-EE` or `-f` is
+    needed for `nailing-cargo init`.  (`-E` is never the default.)
 
   * `--just-linkfarm[=shallow|git|full]`: Make the out-of-tree
     linkfarm as if for `--cargo-lock-update`, but do not actually run
@@ -423,6 +449,13 @@ Options
     lockfile update, controls whether the linkfarm is kept afterwards.
     Overrides the `oot.clean` config option.  (Default: keep.)
 
+  * `--[no-]preclean-build[=no|src|full]`: When doing an out-of-tree
+    build, controls whether the build directory is purged of leftover
+    contents *before* the build is run.  The usual default is `no`.
+    For `cargo publish`, the default is `src`, which deletes
+    everything except the directory `target`.  `full` means to clean
+    out that too.
+
   * `--leave-nailed`: At the end, leave all the `Cargo.toml` files in
     their edited state, rather than (trying to) clean them up.  To
     clean this up later, run `nailing-cargo` again without this option.