inv[oke] 核心用途

参见

本页文档 invoke 的核心参数、选项和行为（包括 custom Invoke-based binaries ）有关调用用户指定任务和其他与解析器相关的详细信息，请参见 调用任务 .

核心选项和标志

invoke 的用法如下：

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

所有核心选项和标志如下；几乎所有这些都必须给出 之前 任何任务名称，加上一些（例如 --help ）在命令行的任何地方被特别寻找。（有关分析详细信息，请参见 基本命令行布局 ）

--complete

将调用命令行的有效制表符完成选项打印（行分隔）为“余数”（即 -- ）用于建筑 shell completion scripts .

例如，当本地任务树包含名为 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”kwarg的默认值。

--no-dedupe

禁用任务重复数据消除。

--prompt-for-sudo-password

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

--write-pyc

默认情况下，调用禁用字节码缓存，因为它会导致任务文件难以调试的问题（以及通常用于调用的事物）不能提供明显的速度效益。如果你真的想 .pyc 文件返回，给这个选项。

-c STRING, --collection=STRING

指定要加载的集合名称。

-d, --debug

启用调试输出。

--dry

回送命令而不是实际运行它们；特别是，导致 run 呼叫：

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

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

  • 返回一个假人 Result 具有“blank”值的对象（空stdout/err字符串， 0 退出代码等）。

-D, --list-depth=INT

限制 --list 显示到指定数量的级别，例如 --list-depth 1 只显示顶级任务和命名空间。

如果一个论点 --list ，那么这个深度是相对的；所以 --list build --list-depth 1 显示了 build 子树。

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

-e, --echo

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

-f, --config

指定一个 runtime configuration file 加载。

请注意，您可以使用 INVOKE_RUNTIME_CONFIG 替换此选项的环境变量。如果两者都给出，那么cli选项将胜出。

-F, --list-format=STRING

更改用于显示输出的格式 --list ；可能是：

  • flat （默认值）：带有虚线任务名称的单列、平直列表。

  • nested ：嵌套（4空间缩进）垂直列表，其中每个级别隐式包含其父级（前导点作为强视觉线索，表明这些仍然是子集合任务）。

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

    • name ：集合的字符串名称；对于根集合，这通常是模块名称，因此除非向加载进程提供备用集合名称，否则通常是 "tasks" （从 tasks.py ）

    • help ：集合的docstring的第一行，如果它来自模块；否则为空（或者如果模块缺少docstring）。

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

      • name ：任务在其集合中的本地名称（即，不是使用 flat 格式化；重新构建该路径由使用者决定。）

      • help ：任务的docstring的第一行，如果没有，则为空。

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

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

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

    发出的json不是很好地打印出来的，而是以一个尾随的换行符结尾。

-h STRING, --help=STRING

如果给定时没有任何任务名称，则显示核心帮助；如果给定时有任务名称（可能在 or 在任务名称之后）显示该特定任务的帮助。

-l, --list=STRING

列出可用任务。默认情况下显示所有任务；可能会将显式命名空间指定给“root”；显示的任务树仅指定给该命名空间。（此参数可能包含句点，与任务名称一样，因此如果需要，可以仅显示整个树的一小部分深度部分。）

-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的基础上“引入”一些常见的用例；tab完成也不例外。通用的制表符完成功能（为给定的命令行上下文输出与shell兼容的完成标记列表）由 --complete 上面描述的core cli选项。

但是，您可能不需要自己使用该标志：我们分发了一些现成的包装脚本，这些脚本针对最常见的shell，如 bash 和 zsh （加上其他）。这些脚本可以从调用或调用自动生成。 any Invoke-driven command-line tool 使用 --print-completion-script ；打印的脚本将包含生成它们的程序的正确二进制名称。

例如，下面的命令打印（到stdout）一个用于 zsh 指导 zsh 把它用在 inv 和 invoke 程序和呼叫 invoke --complete 在运行时获取动态完成信息：

$ invoke --print-completion-script zsh

备注

您可能希望将此命令作为源或将其输出永久存储在某个地方；下一节将详细介绍这一点。

类似地， Fabric 工具继承自Invoke，并且只有一个二进制名 (fab )；如果您想要在 bash ，你会说：：

$ fab --print-completion-script bash

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

源代码脚本

根据您的需要、程序的安装位置和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

    但再一次，这完全取决于你和你的壳。

    备注

    如果你在用 fish 你 must 使用此策略，因为我们的鱼完成脚本不适合直接采购。fish shell用户应该将命令的输出指向 ~/.config/fish/completions/ 目录。

  • 最后，如果需要完成程序的副本只安装在一个特定环境（如ValueLeNV）中，则可以使用上述任一技术：

    • 在这种情况下，缓存输出并在全局shell启动文件中引用它仍然可以工作，因为它不要求程序在shell加载时可用——仅当您实际尝试制表符complete时。

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

利用制表符完成本身

您已确保完成脚本在您的环境中处于活动状态—您获得了什么？

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

  • 键入破折号后的制表符 (- ）或双破折号 (-- ）将显示当前上下文的有效选项/标志：如果尚未键入任务名称，则显示核心调用选项；否则显示最近键入的任务的选项。

    • 键入部分long选项时的制表符将使用shell的原生子字符串完成与long选项的匹配。例如，如果尚未键入任务名称， --e<tab> 将提供 --echo 作为完成选项。

  • 当最新键入/完成的标记是一个接受值的标志时，点击tab键将“通过”shell的本机文件名完成。

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