+
+ * `--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. This is the default for
+ `cargo publish`.
+
+ * `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.
+
+ 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.
+
+ 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 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
+ 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.
+ 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.
+ Without this option, the nailed versions are left in
+ `.Cargo.toml.nailed~`, so you only need this if you want to run
+ cargo by hand or something.
+
+ * `--just-run`: Execute the specified command (perhaps concurrently
+ with other commands), but do not manipulate any of Cargo's
+ metadata fiules. Useful in out of tree mode to invoke a non-cargo
+ command in the build environment. Implies `--no-nail`,
+ `--no-cargo-lock-manip` and `--no-concurrency-lock` (overrideable
+ by later occurrences of the corresponding opposite options).
+ Hazardous if the command is actually cargo, or will run cargo.
+
+ * `--no-nail` | `--nail` (default): Whether to actually nail - ie,
+ whether to actually modify any `Cargo.toml`s while running the
+ command. This can be useful, e.g., in out-of-tree mode with
+ commands that don't actually invoke cargo. Consider passingm
+ `--no-lock` too.
+
+ * `--no-cargo-lock-manip` | `--cargo-lock-manip` (default):
+ Whether to manipulate `Cargo.lock`. For example, whether to copy
+ it to the build tree and back (in out of tree mode) and whether to
+ rename it from an alternative lockfile name, and put it back.
+ Overrides `-u` etc.
+
+ * `--no-concurrency-lock` | `--concurrency-lock` (default): Whether
+ to take the nailing-cargo lock. Some kind of protection against
+ concurrent operation is necessary to prevent multiple instances of
+ nailing-cargo trashing each others' work, and possibly mangling
+ your `Cargo.toml`s, `Cargo.lock`, etc., so `--no-concurrency-lock`
+ is dangerous unless you take other measures against concurrent
+ execution.
+
+ * `-h` | `--help`: Print usage summary.
+
+ * `--doc` | `--man` | `--manual`: Format this manual into html using
+ `pandoc` and display it with `w3m`.
+
~ianmdlvl / nailing-cargo.git / blobdiff