inv[oke] 核心用法

参见

这个页面记录了 invoke 的核心参数、选项和行为（其中包括 基于 invoke 的自定义二进制文件 中的选项）。有关调用用户指定的任务和其他解析器相关的详细信息，请参见 调用任务。

核心选项和旗标

invoke 用法看起来像

$ inv[oke] [--core-opts] task1 [--task1-opts] ... taskN [--taskN-opts]

所有核心选项和标志如下；几乎所有这些都必须在任何任务名称之前给出，其中一些（如 --help ）是在命令行中的任何地方专门查找的。（有关解析的详细信息，请参见 Basic command line layout。）

--complete

打印（以换行符分隔）有效的制表符补全选项，适用于作为 ‘remainder’（即在 -- 之后）提供的 Invoke 命令。用于构建 shell 补全脚本。

例如，当本地任务树包含名为 foo 和 bar 的任务，并且 foo 接受标志 --foo-arg 和 --foo-arg-2 时，您可以像这样使用它:

# Empty input: just task names
$ inv --complete --
foo
bar

# Input not ending with a dash: task names still
$ inv --complete -- foo --foo-arg
foo
bar

# Input ending with a dash: current context's flag names
$ inv --complete -- foo -
--foo-arg
--foo-arg-2

有关如何最好地使用此选项的详细信息，请参阅 --print-completion-script。

--hide=STRING

设置默认值 run() 的 ‘hide’ 关键字参数。

--no-dedupe

禁用任务去重。

--prompt-for-sudo-password

在会话开始时（在执行任何任务之前），提示输入 sudo.password 配置值。这使得不希望将敏感信息存储在配置系统或 shell 环境中的用户可以依赖用户输入，而不会中断程序的正常流程。

--write-pyc

默认情况下，Invoke 禁用了字节码缓存，因为它可能会导致任务文件出现难以调试的问题，并且（对于 Invoke 通常使用的场景）不会带来明显的速度提升。如果你确实希望恢复 .pyc 文件，请使用此选项。

-c STRING, --collection=STRING

指定要加载的集合名称。

-d, --debug

启用调试输出。

--dry

回显命令而不是实际运行它们；具体来说，会导致任何 run 调用：

  • 表现得好像 echo 选项已打开，将要运行的命令打印到 stdout；

  • 跳过实际的子进程调用（在该机制开始运行之前返回）；

  • 返回具有‘空白’值的虚拟 Result 对象（空的 stdout/err 字符串，0 退出代码等）。

-D, --list-depth=INT

将 --list 显示限制为指定的层级数，例如 --list-depth 1 仅显示顶层任务和命名空间。

如果给 --list 提供了参数，则此深度是相对的；因此 --list build --list-depth 1 显示 build 子树顶层的所有内容。

如果未提供此选项，则默认行为是显示整个任务树的所有层级。

-e, --echo

在运行之前回显执行的命令。

-f, --config

指定要加载的 运行时配置文件。

请注意，你可以使用 INVOKE_RUNTIME_CONFIG 环境变量代替此选项。如果两者都提供，CLI 选项将优先。

-F, --list-format=STRING

更改用于显示 --list 输出的格式；可以是以下之一：

  • flat （默认）：单行、点分隔的任务名称列表。

  • nested：嵌套的（4 空格缩进）垂直列表，其中每个层级隐式包含其父级（带有前导点作为强烈的视觉提示，表明这些仍然是子集合任务。）

  • json：旨在供脚本或其他程序使用，此格式发出表示任务树的 JSON，树中的每个‘节点’（最外层的文档是根节点，因此是一个 JSON 对象）由以下键组成：

    • name：集合的字符串名称；对于根集合，这通常是模块名称，因此除非你在加载过程中提供替代的集合名称，否则它通常是 "tasks" （来自 tasks.py。）

    • help：集合文档字符串的第一行，如果它来自模块；否则为 null（或者如果模块缺少文档字符串。）

    • tasks：此集合的直接子项；包含以下形式对象的数组：

      • name：任务在其集合中的本地名称（即不是你在 flat 格式中可能看到的完整点路径；重建该路径留给使用者处理。）

      • help：任务文档字符串的第一行，如果没有则为 null。

      • aliases：此任务的字符串别名数组。

    • default：字符串命名此集合中的哪个任务（如果有）是默认任务。如果没有任务为默认任务，则为 null。

    • collections：此集合内任何子集合的数组，其成员将递归地具有与此最外层文档相同的结构。

    发出的 JSON 没有进行美化打印，但末尾有换行符。

-h STRING, --help=STRING

当不带任何任务名称时，显示核心帮助；当带有任务名称时（可以在任务名称之前 或 之后），显示该特定任务的帮助。

-l, --list=STRING

列出可用任务。默认显示所有任务；可以提供明确的命名空间，将显示的任务树‘根’仅限制在该命名空间内。（此参数可以包含句点，如任务名称一样，因此如果需要，可以仅显示整个树的一小部分深层内容。）

-p, --pty

在执行 shell 命令时使用 pty。

-r STRING, --search-root=STRING

更改用于查找任务模块的根目录。

-T INT, --command-timeout=INT

设置默认的命令执行超时时间为 INT 秒。映射到 timeouts.command 配置设置。

-V, --version

显示版本并退出。

-w, --warn-only

当 shell 命令失败时，警告而不是失败。

Shell 制表符补全

生成补全脚本

Invoke 的理念是实现通用 API，然后‘内置’一些基于这些 API 的常见用例；制表符补全也不例外。通用的制表符补全功能（为给定的命令行上下文输出与 shell 兼容的补全标记列表）由上述 --complete 核心 CLI 选项提供。

然而，你可能不需要自己使用该标志：我们分发了一些针对最常见 shell（如 bash 和 zsh）的现成包装脚本（以及其他 shell）。这些脚本可以使用 --print-completion-script 从 Invoke 或 任何 Invoke 驱动的命令行工具 自动生成；打印的脚本将包含生成它们的程序的正确二进制名称。

例如，以下命令打印（到 stdout）一个适用于 zsh 的脚本，指示 zsh 将其用于 inv 和 invoke 程序，并在运行时调用 invoke --complete 以获取动态补全信息:

$ invoke --print-completion-script zsh

备注

你可能希望获取此命令的输出或将其永久存储在某个地方；下一节将详细介绍。

同样，Fabric 工具继承自 Invoke，并且只有一个二进制名称（fab）；如果你想在 bash 中获得 Fabric 补全，你可以说:

$ fab --print-completion-script bash

在本节的其余部分，将在示例中使用 inv，但请记住，如果你使用的不是 Invoke 本身，请将其替换为你实际使用的程序！

获取脚本

根据你的需求、程序安装的位置以及你的 shell，有几种方法可以利用上述命令的输出：

  • 最简单且干扰最小的方法是内联 source 打印的补全脚本，这不会在磁盘上放置任何内容，并且只会影响当前的 shell 会话:

    $ source <(inv --print-completion-script zsh)

  • 如果你的系统全局 Python 解释器中提供了该程序（并且你不介意在每个 shell 会话启动时运行该程序——Python 的速度确实不是其强项），你可以将该代码片段添加到你的 shell 启动文件中，例如 ~/.zshrc 或 ~/.bashrc。

  • 如果该程序在全局范围内可用，但你 希望 避免在 shell 启动时运行额外的 Python 程序，你可以将命令的输出缓存到自己的文件中；此文件的位置完全取决于你以及你的 shell 配置。例如，你可以将其作为隐藏文件放入你的主目录:

    $ inv --print-completion-script zsh > ~/.invoke-completion.sh

    然后可能将以下内容添加到 ~/.zshrc 的末尾:

    source ~/.invoke-completion.sh

    但再次强调，这完全取决于你以及你的 shell。

    备注

    如果你使用的是 fish，你*必须*使用此策略，因为我们的 fish 补全脚本不适合直接获取。Fish shell 用户应将命令的输出定向到 ~/.config/fish/completions/ 目录中的一个文件。

  • 最后，如果你需要补全的程序仅安装在特定环境中（如 virtualenv），你可以使用上述任何一种技术：

    • 在这种情况下，缓存输出并在全局 shell 启动文件中引用它仍然有效，因为它不需要在 shell 加载时提供程序——仅在你实际尝试制表符补全时才需要。

    • 使用 source <(inv --print-completion-script yourshell) 方法*只要*你将其放在某个适当的每个环境启动文件中即可，这将根据你管理 Python 环境的方式而有所不同。例如，如果你使用 virtualenvwrapper，你可以在 /path/to/virtualenv/bin/postactivate 中附加 source 行。

利用制表符补全本身

你已经确保补全脚本在你的环境中激活——你获得了什么？

  • 默认情况下，在输入 inv 或 invoke 后按 Tab 键将显示当前目录/项目任务文件中的任务名称。

  • 在输入短横线（-）或双短横线（--）后按 Tab 键将显示当前上下文的有效选项/标志：如果尚未输入任务名称，则显示核心 Invoke 选项；否则显示最近输入任务的选项。

    • =在输入部分长选项时按 Tab 键将使用你的 shell 的本地子字符串补全功能完成匹配的长选项。例如，如果尚未输入任务名称，--e<tab> 将提供 --echo 作为补全选项。

  • 当最近输入/完成的标记是需要值的标志时，按 Tab 键将‘回退’到你的 shell 的本地文件名补全。

    • 例如，在输入任务名称之前，--config <tab> 将补全本地文件路径以帮助填写配置文件。