Debian Codegraph @

sites/docs/invoke.rst

raw
1 .. _inv:
2
3 ========================
4 ``inv[oke]`` core usage
5 ========================
6
7 .. seealso::
8 This page documents ``invoke``'s core arguments, options and behavior
9 (which includes options present in :ref:`custom Invoke-based binaries
10 <reusing-as-a-binary>`). For details on invoking user-specified tasks and
11 other parser-related details, see :doc:`/concepts/invoking-tasks`.
12
13
14 Core options and flags
15 ======================
16
17 ``invoke``'s usage looks like::
18
19 $ inv[oke] [--core-opts] task1 [--task1-opts] ... taskN [--taskN-opts]
20
21 All core options & flags are below; almost all of them must be given *before*
22 any task names, with a few (such as :option:`--help`) being specially looked
23 for anywhere in the command line. (For parsing details, see
24 :ref:`basic-cli-layout`.)
25
26 .. option:: --complete
27
28 Print (line-separated) valid tab-completion options for an Invoke command
29 line given as the 'remainder' (i.e. after a ``--``). Used for building
30 :ref:`shell completion scripts <tab-completion>`.
31
32 For example, when the local tasks tree contains tasks named ``foo`` and
33 ``bar``, and when ``foo`` takes flags ``--foo-arg`` and ``--foo-arg-2``,
34 you might use it like this::
35
36 # Empty input: just task names
37 $ inv --complete --
38 foo
39 bar
40
41 # Input not ending with a dash: task names still
42 $ inv --complete -- foo --foo-arg
43 foo
44 bar
45
46 # Input ending with a dash: current context's flag names
47 $ inv --complete -- foo -
48 --foo-arg
49 --foo-arg-2
50
51 For more details on how to make best use of this option, see
52 :option:`--print-completion-script`.
53
54 .. option:: --hide=STRING
55
56 Set default value of run()'s 'hide' kwarg.
57
58 .. option:: --no-dedupe
59
60 Disable task deduplication.
61
62 .. _print-completion-script:
63
64 .. option:: --print-completion-script=SHELL
65
66 Print a completion script for desired ``SHELL`` (e.g. ``bash``, ``zsh``,
67 etc). This can be sourced into the current session in order to enjoy
68 :ref:`tab-completion for tasks and options <tab-completion>`.
69
70 These scripts are bundled with Invoke's distributed codebase, and
71 internally make use of :option:`--complete`.
72
73 .. _prompt-for-sudo-password:
74
75 .. option:: --prompt-for-sudo-password
76
77 Prompt at the start of the session (before executing any tasks) for the
78 ``sudo.password`` configuration value. This allows users who don't want to
79 keep sensitive material in the config system or their shell environment to
80 rely on user input, without otherwise interrupting the flow of the program.
81
82 .. option:: --write-pyc
83
84 By default, Invoke disables bytecode caching as it can cause hard-to-debug
85 problems with task files and (for the kinds of things Invoke is typically
86 used for) offers no noticeable speed benefit. If you really want your
87 ``.pyc`` files back, give this option.
88
89 .. option:: -c STRING, --collection=STRING
90
91 Specify collection name to load.
92
93 .. option:: -d, --debug
94
95 Enable debug output.
96
97 .. option:: --dry
98
99 Echo commands instead of actually running them; specifically, causes any
100 ``run`` calls to:
101
102 - Act as if the ``echo`` option has been turned on, printing the
103 command-to-be-run to stdout;
104 - Skip actual subprocess invocation (returning before any of that machinery
105 starts running);
106 - Return a dummy `~invoke.runners.Result` object with 'blank' values (empty
107 stdout/err strings, ``0`` exit code, etc).
108
109 .. option:: -D, --list-depth=INT
110
111 Limit :option:`--list` display to the specified number of levels, e.g.
112 ``--list-depth 1`` to show only top-level tasks and namespaces.
113
114 If an argument is given to ``--list``, then this depth is relative; so
115 ``--list build --list-depth 1`` shows everything at the top level of the
116 ``build`` subtree.
117
118 Default behavior if this is not given is to show all levels of the entire
119 task tree.
120
121 .. option:: -e, --echo
122
123 Echo executed commands before running.
124
125 .. option:: -f, --config
126
127 Specify a :ref:`runtime configuration file <config-hierarchy>` to load.
128
129 Note that you may instead use the ``INVOKE_RUNTIME_CONFIG`` environment
130 variable in place of this option. If both are given, the CLI option will
131 win out.
132
133 .. option:: -F, --list-format=STRING
134
135 Change the format used to display the output of :option:`--list`; may be
136 one of:
137
138 - ``flat`` (the default): single, flat vertical list with dotted task
139 names.
140 - ``nested``: a nested (4-space indented) vertical list, where each level
141 implicitly includes its parent (with leading dots as a strong visual clue
142 that these are still subcollection tasks.)
143 - ``json``: intended for consumption by scripts or other programs, this
144 format emits JSON representing the task tree, with each 'node' in the
145 tree (the outermost document being the root node, and thus a JSON object)
146 consisting of the following keys:
147
148 - ``name``: String name of collection; for the root collection this is
149 typically the module name, so unless you're supplying alternate
150 collection name to the load process, it's usually ``"tasks"`` (from
151 ``tasks.py``.)
152 - ``help``: First line of collection's docstring, if it came from a
153 module; null otherwise (or if module lacked a docstring.)
154 - ``tasks``: Immediate children of this collection; an array of objects
155 of the following form:
156
157 - ``name``: Task's local name within its collection (i.e. not the full
158 dotted path you might see with the ``flat`` format; reconstructing
159 that path is left up to the consumer.)
160 - ``help``: First line of task's docstring, or null if it had none.
161 - ``aliases``: An array of string aliases for this task.
162
163 - ``default``: String naming which task within this collection, if any,
164 is the default task. Is null if no task is the default.
165 - ``collections``: An array of any sub-collections within this
166 collection, members of which which will have the same structure as this
167 outermost document, recursively.
168
169 The JSON emitted is not pretty-printed, but does end with a trailing
170 newline.
171
172 .. option:: -h STRING, --help=STRING
173
174 When given without any task names, displays core help; when given with a
175 task name (may come before *or* after the task name) displays help for that
176 particular task.
177
178 .. option:: -l, --list=STRING
179
180 List available tasks. Shows all tasks by default; may give an explicit
181 namespace to 'root' the displayed task tree to only that namespace. (This
182 argument may contain periods, as with task names, so it's possible to show
183 only a small, deep portion of the overall tree if desired.)
184
185 .. option:: -p, --pty
186
187 Use a pty when executing shell commands.
188
189 .. option:: -r STRING, --search-root=STRING
190
191 Change root directory used for finding task modules.
192
193 .. option:: -T INT, --command-timeout=INT
194
195 Set a default command execution timeout of INT seconds. Maps to the
196 ``timeouts.command`` config setting.
197
198 .. option:: -V, --version
199
200 Show version and exit.
201
202 .. option:: -w, --warn-only
203
204 Warn, instead of failing, when shell commands fail.
205
206
207 .. _tab-completion:
208
209 Shell tab completion
210 ====================
211
212 Generating a completion script
213 ------------------------------
214
215 Invoke's philosophy is to implement generic APIs and then "bake in" a few
216 common use cases built on top of those APIs; tab completion is no different.
217 Generic tab completion functionality (outputting a shell-compatible list of
218 completion tokens for a given command line context) is provided by the
219 :option:`--complete` core CLI option described above.
220
221 However, you probably won't need to use that flag yourself: we distribute a
222 handful of ready-made wrapper scripts aimed at the most common shells like
223 ``bash`` and ``zsh`` (plus others). These scripts can be automatically
224 generated from Invoke or :ref:`any Invoke-driven command-line tool
225 <reusing-as-a-binary>`, using :option:`--print-completion-script`; the printed
226 scripts will contain the correct binary name(s) for the program generating
227 them.
228
229 For example, the following command prints (to stdout) a script which works for
230 ``zsh``, instructs ``zsh`` to use it for the ``inv`` and ``invoke`` programs,
231 and calls ``invoke --complete`` at runtime to get dynamic completion
232 information::
233
234 $ invoke --print-completion-script zsh
235
236 .. note::
237 You'll probably want to source this command or store its output somewhere
238 permanently; more on that in the next section.
239
240 Similarly, the `Fabric <https://fabfile.org>`_ tool inherits from Invoke, and
241 only has a single binary name (``fab``); if you wanted to get Fabric completion
242 in ``bash``, you would say::
243
244 $ fab --print-completion-script bash
245
246 In the rest of this section, we'll use ``inv`` in examples, but please remember
247 to replace it with the program you're actually using, if it's not Invoke
248 itself!
249
250 Sourcing the script
251 -------------------
252
253 There are a few ways to utilize the output of the above commands, depending on
254 your needs, where the program is installed, and your shell:
255
256 - The simplest and least disruptive method is to ``source`` the printed
257 completion script inline, which doesn't place anything on disk, and will only
258 affect the current shell session::
259
260 $ source <(inv --print-completion-script zsh)
261
262 - If you've got the program available in your system's global Python
263 interpreter (and you're okay with running the program at the startup of each
264 shell session - Python's speed is admittedly not its strong point) you could
265 add that snippet to your shell's startup file, such as ``~/.zshrc`` or
266 ``~/.bashrc``.
267 - If the program's available globally but you'd prefer to *avoid* running an
268 extra Python program at shell startup, you can cache the output of the
269 command in its own file; where this file lives is entirely up to you and how
270 your shell is configured. For example, you might just drop it into your home
271 directory as a hidden file::
272
273 $ inv --print-completion-script zsh > ~/.invoke-completion.sh
274
275 and then perhaps add the following to the end of ``~/.zshrc``::
276
277 source ~/.invoke-completion.sh
278
279 But again, this is entirely up to you and your shell.
280
281 .. note::
282 If you're using ``fish``, you *must* use this tactic, as our fish
283 completion script is not suitable for direct sourcing. Fish shell users
284 should direct the output of the command to a file in the
285 ``~/.config/fish/completions/`` directory.
286
287 - Finally, if your copy of the needing-completion program is only installed in
288 a specific environment like a virtualenv, you can use either of the above
289 techniques:
290
291 - Caching the output and referencing it in a global shell startup file will
292 still work in this case, as it does not require the program to be
293 available when the shell loads -- only when you actually attempt to tab
294 complete.
295 - Using the ``source <(inv --print-completion-script yourshell)`` approach
296 will work *as long as* you place it in some appropriate per-environment
297 startup file, which will vary depending on how you manage Python
298 environments. For example, if you use ``virtualenvwrapper``, you could
299 append the ``source`` line in ``/path/to/virtualenv/bin/postactivate``.
300
301 Utilizing tab completion itself
302 -------------------------------
303
304 You've ensured that the completion script is active in your environment - what
305 have you gained?
306
307 - By default, tabbing after typing ``inv`` or ``invoke`` will display task
308 names from your current directory/project's tasks file.
309 - Tabbing after typing a dash (``-``) or double dash (``--``) will display
310 valid options/flags for the current context: core Invoke options if no task
311 names have been typed yet; options for the most recently typed task
312 otherwise.
313
314 - Tabbing while typing a partial long option will complete matching long
315 options, using your shell's native substring completion. E.g. if no task
316 names have been typed yet, ``--e<tab>`` will offer ``--echo`` as a
317 completion option.
318
319 - Hitting tab when the most recent typed/completed token is a flag which takes
320 a value, will 'fall through' to your shell's native filename completion.
321
322 - For example, prior to typing a task name, ``--config <tab>`` will
323 complete local file paths to assist in filling in a config file.