有关CLI标志、环境变量和配置项之间的关联，请参阅以下CLI文档。CLI优先于环境，环境优先于配置。

CLI

有一些命令可用

$ cargo help liner
Cargo subcommand to install and update binary packages listed in
configuration.

Usage: cargo liner [OPTIONS] [COMMAND]

Commands:
  ship         The default command if omitted: install and update
               configured packages
  import       Import the `$CARGO_HOME/.crates.toml` Cargo-edited
               save file as a new Liner configuration file
  completions  Generate an auto-completion script for the given shell
  help         Print this message or the help of the given
               subcommand(s)

Options:
  -v, --verbose...
          Be more verbose. Use multiple times to be more and more so
          each time.
          
          When omitted, INFO and above messages of only this crate
          are logged. When used once, DEBUG and above messages of
          only this crate are logged and error backtraces are shown
          (`RUST_BACKTRACE=1`). When used twice, DEBUG and above
          messages of all crates are logged, `-v` is given to Cargo
          calls (details ran commands), and error backtraces are
          fully shown (`RUST_BACKTRACE=full`). When used three times
          or more, TRACE and above messages of all crates are logged,
          `-vv` is given to Cargo calls (includes build output) and
          error backtraces are fully shown (`RUST_BACKTRACE=full`).
          This takes precedence over the environment.

  -q, --quiet...
          Be quieter. Use multiple times to be more and more so each
          time.
          
          When omitted, INFO and above messages of only this crate
          are logged. When used once, WARN and above messages of only
          this crate are logged. When used twice, ERROR messages of
          all crates are logged. When used three times or more, no
          message will be logged, including Cargo's by passing `-q`
          to it and error reports are silenced. This takes precedence
          over the environment.

      --color <WHEN>
          Control the coloring of the logging output.
          
          This enables one to manually specify when should the logs
          and error reports be colored or not, for example if the
          automatic detection is either not wished or not functional.
          The value is also passed onto calls to Cargo.
          
          [default: auto]
          [possible values: auto, always, never]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

默认命令

当省略子命令时，它将使用带有默认选项的ship子命令。有关更多详细信息，请参阅其具体文档。

只需运行cargo liner即可

• 从配置文件中读取包。
• 从Cargo的安装中检测当前已安装的包。
• 检查它们的最新版本。
• 安装或更新需要更新的包，同时遵守版本要求。
• 自我更新。

如果需要bat和cargo-expand的示例输出

$ cargo liner
 INFO  cargo_liner::cargo > Fetching latest package versions...
...
 INFO  cargo_liner        > Results:
┌──────────────┬─────────────┬─────────────┬────────┐
│ Name         │ Old version │ New version │ Status │
├──────────────┼─────────────┼─────────────┼────────┤
│ bat          │ ø           │ 0.24.0      │ 🛈      │
│ cargo-expand │ 1.0.78      │ 1.0.79      │ 🛈      │
│ cargo-liner  │ 0.0.0       │ ø           │ ✔      │
└──────────────┴─────────────┴─────────────┴────────┘
 INFO  cargo_liner::cargo > Installing `bat`...
    Updating [..] index
 Downloading crates ...
  Downloaded bat v0.24.0 (registry [..])
  Installing bat v0.24.0
    Updating [..] index
...
   Compiling bat v0.24.0
    Finished `release` profile [optimized] target(s) in [..]s
  Installing [..]/.cargo/bin/bat
   Installed package `bat v0.24.0` (executable `bat`)
...
 INFO  cargo_liner::cargo > Updating `cargo-expand`...
    Updating [..] index
 Downloading crates ...
  Downloaded cargo-expand v1.0.79 (registry [..])
  Installing cargo-expand v1.0.79
    Updating [..] index
...
   Compiling cargo-expand v1.0.79
    Finished `release` profile [optimized] target(s) in [..]s
   Replacing [..]/.cargo/bin/cargo-expand
    Replaced package `cargo-expand v1.0.78` with `cargo-expand v1.0.79` (executable `cargo-expand`)
...
 INFO  cargo_liner        > Installation report:
┌──────────────┬─────────────┬─────────────┬────────┐
│ Name         │ Old version │ New version │ Status │
├──────────────┼─────────────┼─────────────┼────────┤
│ bat          │ ø           │ 0.24.0      │ +      │
│ cargo-expand │ 1.0.78      │ 1.0.79      │ ✔      │
└──────────────┴─────────────┴─────────────┴────────┘
 INFO  cargo_liner        > Done.

其中第一个表格显示每个配置包的当前安装版本和最新版本，以及将要执行的操作；第二个表格显示一个结束报告，显示每个受影响的包的先前版本和新版本，以及调用cargo install的结果。

输出中可选地用颜色表示状态图标，代表以下内容

• ø：当没有要显示或需要执行的操作时：已经是最新的。
• ?：当元素无法确定时，例如使用skip-check时包的新版本。
• 🛈：当需要执行某些操作时：包的安装或更新。
• +：当成功添加某些内容时：包的新安装。
• ✘：当发生失败时。
• ✔：当一切顺利时：已更新或成功更新。

ship 子命令

主要命令：执行包的安装和更新。

$ cargo liner help ship
The default command if omitted: install and update configured
packages.

Self-updating is enabled by default.

Usage: cargo liner ship [OPTIONS]

Options:
  -n, --no-self
          Disable self-updating.
          
          Cannot be used in conjunction with `--only-self`.
          
          [default: false]
          
          [env: `CARGO_LINER_SHIP_NO_SELF`]
          
          [config: `defaults.ship.no-self`]

      --with-self
          Negation of `--no-self` that overrides it and restores the
          default behavior as if absent, i.e. self-update

  -s, --only-self
          Only self-update and do not install or update any other
          package.
          
          Cannot be used in conjunction with `--no-self`.
          
          [default: false]
          
          [env: `CARGO_LINER_SHIP_ONLY_SELF`]
          
          [config: `defaults.ship.only-self`]

      --no-only-self
          Negation of `--only-self` that overrides it and restores
          the default behavior as if absent, i.e. install or update
          other packages as well

  -c, --skip-check
          Skip the summary version check and directly call `cargo
          install` on each configured package.
          
          The version check is relatively quick and enables skipping
          calls to `cargo install` when no update is required, which
          saves quite a bit of time. However, if you wish, this
          option is still available in order not to run the check:
          doing so will probably take more time in the end most of
          the time, except if you have a very small amount of
          packages configured (e.g. one or two) or if all or almost
          all packages are not already installed.
          
          It can also be used as a workaround in case a certain
          operation fails in your particular environment, for
          example: reading from `.crates.toml` under the
          `$CARGO_HOME` or `$CARGO_INSTALL_ROOT` directory or making
          requests to the registry. These operations will thus be
          entirely skipped.
          
          [default: false]
          
          [env: `CARGO_LINER_SHIP_SKIP_CHECK`]
          
          [config: `defaults.ship.skip-check`]

      --no-skip-check
          Negation of `--skip-check` that overrides it and restores
          the default behavior as if absent, i.e. perform the usual
          version check

  -k, --no-fail-fast
          Disable the default fail-fast execution of `cargo
          install`s.
          
          By default, whenever a call to `cargo install` fails for
          any reason, the overall operation is stopped as soon as
          possible. In some cases, such as packages simply failing to
          compile, this is a bit too restrictive as it prevents
          installing the following packages. The option it therefore
          provided in order to make the installation keep on going by
          continuing to call `cargo install` on each configured
          package, even if some previous one failed. However, in case
          any of the packages fails to install and the option is
          used, an error will still be reported at the end,
          containing an indication of all the packages that failed to
          install.
          
          This is not to be confused with Cargo's `--keep-going`
          build option: it disables fast-failing between crate
          compilations, while the current one disables fast-failing
          between entire calls to `cargo install`; in fact,
          `--keep-going` is never passed onto Cargo. It is neither to
          be confused with `cargo test --no-fail-fast` since `cargo
          test` is never used.
          
          [default: false]
          
          [env: `CARGO_LINER_SHIP_NO_FAIL_FAST`]
          
          [config: `defaults.ship.no-fail-fast`]

      --fail-fast
          Negation of `--no-fail-fast` that overrides it and restores
          the default behavior as if absent, i.e. stop as soon as the
          first error occurs

  -f, --force
          Force overwriting existing crates or binaries.
          
          Passes the option flag onto each call of `cargo install`.
          It will, for example, redownload, recompile and reinstall
          every configured package when used in conjunction with
          `--skip-check`.
          
          [default: false]
          
          [env: `CARGO_LINER_SHIP_FORCE`]
          
          [config: `defaults.ship.force`]

      --no-force
          Negation of `--force` that overrides it and restores the
          default behavior as if absent, i.e. don't pass the argument
          onto Cargo

  -v, --verbose...
          Be more verbose. Use multiple times to be more and more so
          each time.
          
          When omitted, INFO and above messages of only this crate
          are logged. When used once, DEBUG and above messages of
          only this crate are logged and error backtraces are shown
          (`RUST_BACKTRACE=1`). When used twice, DEBUG and above
          messages of all crates are logged, `-v` is given to Cargo
          calls (details ran commands), and error backtraces are
          fully shown (`RUST_BACKTRACE=full`). When used three times
          or more, TRACE and above messages of all crates are logged,
          `-vv` is given to Cargo calls (includes build output) and
          error backtraces are fully shown (`RUST_BACKTRACE=full`).
          This takes precedence over the environment.

  -q, --quiet...
          Be quieter. Use multiple times to be more and more so each
          time.
          
          When omitted, INFO and above messages of only this crate
          are logged. When used once, WARN and above messages of only
          this crate are logged. When used twice, ERROR messages of
          all crates are logged. When used three times or more, no
          message will be logged, including Cargo's by passing `-q`
          to it and error reports are silenced. This takes precedence
          over the environment.

      --color <WHEN>
          Control the coloring of the logging output.
          
          This enables one to manually specify when should the logs
          and error reports be colored or not, for example if the
          automatic detection is either not wished or not functional.
          The value is also passed onto calls to Cargo.
          
          [default: auto]
          [possible values: auto, always, never]

  -h, --help
          Print help (see a summary with '-h')

只需在命令行中运行cargo liner ship即可

• 从配置文件中读取包。
• 从位于$CARGO_INSTALL_ROOT目录下的Cargo管理的.crates.toml文件中读取当前已安装的包，如果cargo config get能够从环境变量或install.root配置项中检索其值（在$CARGO_HOME/config.toml中），或者如果第一次尝试失败，将回退到在默认的$CARGO_HOME目录下搜索文件，其中简单的设置不存在也是一个原因。有关此内容的更多详细信息，请参阅cargo install文档。每次第一次尝试失败时，在尝试默认值之前，都会将其记录为DEBUG消息，因此请使用-vv来调查您的配置似乎没有被考虑。
• 使用cargo search检查每个包的最新可用版本。
• 对于需要安装或更新的每个包运行cargo install，同时遵守版本要求。
• 只有当没有提供--no-self时才进行自我更新。

cargoinstall

import 子命令

此命令旨在在安装工具并首次使用后使用：它将在配置文件中填充当前已安装的包。

$ cargo liner help import
Import the `$CARGO_HOME/.crates.toml` Cargo-edited save file as a new
Liner configuration file.

Star versions are used by default. The version transformation options
are mutually exclusive.

Usage: cargo liner import [OPTIONS]

Options:
  -e, --exact
          Import package versions as "exact versions", i.e. prepended
          with an equal operator.
          
          Cannot be used in conjunction with either `--compatible` or
          `--patch`. Default: `false`, i.e. use a star requirement.

  -c, --compatible
          Import package versions as "compatible versions", i.e.
          prepended with a caret operator.
          
          Cannot be used in conjunction with either `--exact` or
          `--patch`. Default: `false`, i.e. use a star requirement.

  -p, --patch
          Import package versions as "patch versions", i.e. prepended
          with a tilde operator.
          
          Cannot be used in conjunction with either `--exact` or
          `--compatible`. Default: `false`, i.e. use a star
          requirement.

  -f, --force
          Overwrite the current configuration file if it already
          exists.
          
          Default: `false`, i.e. return an error in case the file
          already exists.

  -s, --keep-self
          Also import this `cargo-liner` package into the
          configuration, for example in order to specify a certain
          version requirement later on.
          
          Default: `false`, i.e. exclude the current package from the
          list of packages to install or update in the resulting
          configuration file. Note however that the `ship` command
          will still self-update by default.

  -l, --keep-local
          Also import all locally-installed packages into the
          configuration. This means packages installed via `cargo
          install --path <path>` will be present in the
          configuration.
          
          Default: `false`, i.e. exclude all packages installed via
          `cargo install --path <path>` from the list of packages to
          install or update in the resulting configuration file.

  -v, --verbose...
          Be more verbose. Use multiple times to be more and more so
          each time.
          
          When omitted, INFO and above messages of only this crate
          are logged. When used once, DEBUG and above messages of
          only this crate are logged and error backtraces are shown
          (`RUST_BACKTRACE=1`). When used twice, DEBUG and above
          messages of all crates are logged, `-v` is given to Cargo
          calls (details ran commands), and error backtraces are
          fully shown (`RUST_BACKTRACE=full`). When used three times
          or more, TRACE and above messages of all crates are logged,
          `-vv` is given to Cargo calls (includes build output) and
          error backtraces are fully shown (`RUST_BACKTRACE=full`).
          This takes precedence over the environment.

  -q, --quiet...
          Be quieter. Use multiple times to be more and more so each
          time.
          
          When omitted, INFO and above messages of only this crate
          are logged. When used once, WARN and above messages of only
          this crate are logged. When used twice, ERROR messages of
          all crates are logged. When used three times or more, no
          message will be logged, including Cargo's by passing `-q`
          to it and error reports are silenced. This takes precedence
          over the environment.

      --color <WHEN>
          Control the coloring of the logging output.
          
          This enables one to manually specify when should the logs
          and error reports be colored or not, for example if the
          automatic detection is either not wished or not functional.
          The value is also passed onto calls to Cargo.
          
          [default: auto]
          [possible values: auto, always, never]

  -h, --help
          Print help (see a summary with '-h')

例如，如果您之前已安装

• bat@0.22.1
• cargo-make@0.36.3
• cargo-outdated@0.11.1

然后运行cargo liner import将产生以下配置文件，如果它尚不存在

[packages]
bat = "*"
cargo-make = "*"
cargo-outdated = "*"

默认情况下，此命令会从目标文件中排除

• cargo-liner：将重复专门的自我更新；存在-s/--keep-self选项标志以禁用此排除。
• 所有本地安装的包，即通过 cargo install --path=... 安装的包：避免将无法更新的包（因为它们在使用的注册表中没有保证存在）污染目标文件；存在 -l/--keep-local 选项标志以禁用此排除。

默认情况下，命令将导入具有星号版本要求的包。提供了 --exact、--compatible 和 --patch 选项，以自定义如何将当前安装的版本导入到版本要求中：--exact 将它们前置为 =，--compatible 为 ^，--patch 为 ~。

例如，使用已安装的这三个包，运行 cargo liner import --patch 将会得到

[packages]
bat = "~0.22.1"
cargo-make = "~0.36.3"
cargo-outdated = "~0.11.1"

文件当然可以按照预期手动编辑。

completions 子命令

这可以在 shell 中为当前项目启用 CLI 自动完成

$ cargo liner help completions
Generate an auto-completion script for the given shell.

The script is generated for `cargo-liner`, but with arguments rooted
on `cargo-liner liner`, thus making auto-completing work when typing
`cargo liner`. The generated script is emitted to standard output.

Usage: cargo liner completions [OPTIONS] <SHELL>

Arguments:
  <SHELL>
          The shell flavor to use when generating the completions
          
          [possible values: bash, elvish, fish, powershell, zsh]

Options:
  -v, --verbose...
          Be more verbose. Use multiple times to be more and more so
          each time.
          
          When omitted, INFO and above messages of only this crate
          are logged. When used once, DEBUG and above messages of
          only this crate are logged and error backtraces are shown
          (`RUST_BACKTRACE=1`). When used twice, DEBUG and above
          messages of all crates are logged, `-v` is given to Cargo
          calls (details ran commands), and error backtraces are
          fully shown (`RUST_BACKTRACE=full`). When used three times
          or more, TRACE and above messages of all crates are logged,
          `-vv` is given to Cargo calls (includes build output) and
          error backtraces are fully shown (`RUST_BACKTRACE=full`).
          This takes precedence over the environment.

  -q, --quiet...
          Be quieter. Use multiple times to be more and more so each
          time.
          
          When omitted, INFO and above messages of only this crate
          are logged. When used once, WARN and above messages of only
          this crate are logged. When used twice, ERROR messages of
          all crates are logged. When used three times or more, no
          message will be logged, including Cargo's by passing `-q`
          to it and error reports are silenced. This takes precedence
          over the environment.

      --color <WHEN>
          Control the coloring of the logging output.
          
          This enables one to manually specify when should the logs
          and error reports be colored or not, for example if the
          automatic detection is either not wished or not functional.
          The value is also passed onto calls to Cargo.
          
          [default: auto]
          [possible values: auto, always, never]

  -h, --help
          Print help (see a summary with '-h')

其结果可以被保存到配置为可以通过 shell source（或等效）的文件中，或者在每次启动时生成并 eval（或等效）。例如，在 Zsh 中，向 ~/.zshrc 中添加

[[ -f ~/.cargo/bin/cargo-liner ]] && eval "$(cargo liner -qqq completions zsh)"

将启用每个新 shell 中的完成功能，但前提是 Cargo Liner 确实已安装（这部分可能需要根据您的特定环境进行调整）。

贡献

请参阅贡献指南。请还注意行为准则。

版权声明

Sergej Tucakov 为本项目标志使用的动画。