Mirrors/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell synced 2024-11-14 00:47:30 +00:00
Code Issues Projects Releases Packages Wiki Activity
fish-shell/doc_src/cmds/complete.rst

154 lines
8.2 KiB
ReStructuredText
Raw Normal View History

docs: Add labels to all commands This allows us to use :ref: references, which don't require hardcoding it as html [ci skip]
2019-03-31 09:05:09 +00:00
.. _cmd-complete:
Fix grammar in completion docs
2023-07-09 02:55:12 +00:00
complete - edit command-specific tab-completions
Fix command section separator line lengths
2019-01-03 04:10:47 +00:00
================================================
Switch command docs from \section to reStructuredText
2018-12-17 01:39:33 +00:00
Migrate the 'synopsis' sections to .rst format
2018-12-18 01:58:24 +00:00
Synopsis
--------
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs synopsis: add HTML highlighing and automate manpage markup Recent synopsis changes move from literal code blocks to [RST line blocks]. This does not translate well to HTML: it's not rendered in monospace, so aligment is lost. Additionally, we don't get syntax highlighting in HTML, which adds differences to our code samples which are highlighted. We hard-wrap synopsis lines (like code blocks). To align continuation lines in manpages we need [backslashes in weird places]. Combined with the **, *, and `` markup, it's a bit hard to get the alignment right. Fix these by moving synopsis sources back to code blocks and compute HTML syntax highlighting and manpage markup with a custom Sphinx extension. The new Pygments lexer can tokenize a synopsis and assign the various highlighting roles, which closely matches fish's syntax highlighing: - command/keyword (dark blue) - parameter (light blue) - operator like and/or/not/&&/|| (cyan) - grammar metacharacter (black) For manpage output, we don't project the fish syntax highlighting but follow the markup convention in GNU's man(1): bold text type exactly as shown. italic text replace with appropriate argument. To make it easy to separate these two automatically, formalize that (italic) placeholders must be uppercase; while all lowercase text is interpreted literally (so rendered bold). This makes manpages more consistent, see string-join(1) and and(1). Implementation notes: Since we want manpage formatting but Sphinx's Pygments highlighing plugin does not support manpage output, add our custom "synopsis" directive. This directive parses differently when manpage output is specified. This means that the HTML and manpage build processes must not share a cache, because the parsed doctrees are cached. Work around this by using separate cache locations for build targets "sphinx-docs" (which creates HTML) and "sphinx-manpages". A better solution would be to only override Sphinx's ManualPageBuilder but that would take a bit more code (ideally we could override ManualPageWriter but Sphinx 4.3.2 doesn't really support that). --- Alternative solution: stick with line blocks but use roles like :command: or :option: (or custom ones). While this would make it possible to produce HTML that is consistent with code blocks (by adding a bit of CSS), the source would look uglier and is harder to maintain. (Let's say we want to add custom formatting to the [|] metacharacters in HTML. This is much easier with the proposed patch.) --- [RST line blocks]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks [backslashes in weird places]: https://github.com/fish-shell/fish-shell/pull/8626#discussion_r782837750
2022-01-09 14:09:46 +00:00
.. synopsis::
Fix grammar in completion docs
2023-07-09 02:55:12 +00:00
complete ((-c | --command) | (-p | --path)) COMMAND [OPTIONS]
docs: omnibus cleanup Includes harmonizing the display of options and arguments, standardising terminology, using the envvar directive more broadly, adding help options to all commands that support them, simplifying some language, and tidying up multiple formatting issues. string documentation is not changed.
2022-03-11 16:18:41 +00:00
complete (-C | --do-complete) [--escape] STRING
Migrate the 'synopsis' sections to .rst format
2018-12-18 01:58:24 +00:00
Convert \\subsection sections into rst format
2018-12-19 02:44:30 +00:00
Description
Fix command section separator line lengths
2019-01-03 04:10:47 +00:00
-----------
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: Improve complete docs A bit stuffy, some weird bits (I don't think GNU-style long options can typically be abbreviated, ``true --v`` and ``bash --hel`` don't work).
2020-09-09 16:56:25 +00:00
``complete`` defines, removes or lists completions for a command.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: Improve complete docs A bit stuffy, some weird bits (I don't think GNU-style long options can typically be abbreviated, ``true --v`` and ``bash --hel`` don't work).
2020-09-09 16:56:25 +00:00
For an introduction to writing your own completions, see :ref:`Writing your own completions <completion-own>` in
the fish manual.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
The following options are available:
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
**-c** or **--command** *COMMAND*
Specifies that *COMMAND* is the name of the command. If there is no **-c** or **-p**, one non-option argument will be used as the command.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
**-p** or **--path** *COMMAND*
Specifies that *COMMAND* is the absolute path of the command (optionally containing wildcards).
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
**-e** or **--erase**
Deletes the specified completion.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
**-s** or **--short-option** *SHORT_OPTION*
Adds a short option to the completions list.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
**-l** or **--long-option** *LONG_OPTION*
Make stylistic grammatical change to `complete` docs Use a hyphen when referring to "xxx-style" completions.
2022-09-26 18:39:43 +00:00
Adds a GNU-style long option to the completions list.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
`complete` docs: When to use old-style for short options There are many applications with "primitive" argument parsing capabalities that cannot handle munging two short options together (`-xf` for `-x -f`) or a short option and its required value (`-dall` for `-d all`). To prevent fish from suggesting munged arguments/payloads, the options (both long and short, not just long!) can be specified as `-o` or `--old-option` but none of this is documented.
2022-09-26 19:05:54 +00:00
**-o** or **--old-option** *OPTION*
Adds an old-style short or long option (see below for details).
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
**-a** or **--arguments** *ARGUMENTS*
Adds the specified option arguments to the completions list.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
**-k** or **--keep-order**
Keeps the order of *ARGUMENTS* instead of sorting alphabetically. Multiple ``complete`` calls with **-k** result in arguments of the later ones displayed first.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
**-f** or **--no-files**
This completion may not be followed by a filename.
complete: Add "--force-files" This allows a completion to specify that *it* takes files. Useful for things like `sudo -e`, because sudo usually doesn't take any files.
2019-05-30 17:12:49 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
**-F** or **--force-files**
This completion may be followed by a filename, even if another applicable ``complete`` specified **--no-files**.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
**-r** or **--require-parameter**
This completion must have an option argument, i.e. may not be followed by another option.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
**-x** or **--exclusive**
Short for **-r** and **-f**.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
**-w** or **--wraps** *WRAPPED_COMMAND*
Causes the specified command to inherit completions from *WRAPPED_COMMAND* (see below for details).
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
**-n** or **--condition** *CONDITION*
Allow complete to have multiple conditions This makes it so `complete -c foo -n test1 -n test2` registers *both* conditions, and when it comes time to check the candidate, tries both, in that order. If any fails it stops, if all succeed the completion is offered. The reason for this is that it helps with caching - we have a condition cache, but conditions like ```fish test (count (commandline -opc)) -ge 2; and contains -- (commandline -opc)[2] length test (count (commandline -opc)) -ge 2; and contains -- (commandline -opc)[2] sub ``` defeats it pretty easily, because the cache only looks at the entire script as a string - it can't tell that the first `test` is the same in both. So this means we separate it into ```fish complete -f -c string -n "test (count (commandline -opc)) -ge 2; and contains -- (commandline -opc)[2] length" -s V -l visible -d "Use the visible width, excluding escape sequences" +complete -f -c string -n "test (count (commandline -opc)) -ge 2" -n "contains -- (commandline -opc)[2] length" -s V -l visible -d "Use the visible width, excluding escape sequences" ``` which allows the `test` to be cached. In tests, this improves performance for the string completions by 30% by reducing all the redundant `test` calls. The `git` completions can also greatly benefit from this.
2022-05-20 17:02:42 +00:00
This completion should only be used if the *CONDITION* (a shell command) returns 0. This makes it possible to specify completions that should only be used in some cases. If multiple conditions are specified, fish will try them in the order they are specified until one fails or all succeeded.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: standardise on definition lists for options Harmonizes the option listing including formatting in a similar manner to the synopsis of each entry.
2022-03-11 15:56:20 +00:00
**-C** or **--do-complete** *STRING*
Makes ``complete`` try to find all possible completions for the specified string. If there is no *STRING*, the current commandline is used instead.
**--escape**
When used with ``-C``, escape special characters in completions.
Add --escape option to `complete -C` An example use case is an external completion pager: bind \cg "commandline -rt (complete -C --escape|fzf|cut -d\t -f1)\ " Fixes #3469
2022-01-15 14:57:29 +00:00
docs: omnibus cleanup Includes harmonizing the display of options and arguments, standardising terminology, using the envvar directive more broadly, adding help options to all commands that support them, simplifying some language, and tidying up multiple formatting issues. string documentation is not changed.
2022-03-11 16:18:41 +00:00
**-h** or **--help**
Displays help about using this command.
Fix grammar in completion docs
2023-07-09 02:55:12 +00:00
Command-specific tab-completions in ``fish`` are based on the notion of options and arguments. An option is a parameter which begins with a hyphen, such as ``-h``, ``-help`` or ``--help``. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU getopt library. These styles are:
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Clarify that optional option arguments must have no separating space Unless we use "complete --require-parameter", we must say "-w32", not "-w 32", because the second "32" is a positional argument. Notably, old options do not have this behavior, which is a bit weird, see #8465 Taken from a discussion in #8459
2021-11-22 20:08:56 +00:00
- Short options, like ``-a``. Short options are a single character long, are preceded by a single hyphen and can be grouped together (like ``-la``, which is equivalent to ``-l -a``). Option arguments may be specified by appending the option with the value (``-w32``), or, if ``--require-parameter`` is given, in the following parameter (``-w 32``).
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Move short old-style example to end
2022-10-01 00:17:07 +00:00
- Old-style options, long like ``-Wall`` or ``-name`` or even short like ``-a``. Old-style options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified by default following a space (``-foo null``) or after ``=`` (``-foo=null``).
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Make stylistic grammatical change to `complete` docs Use a hyphen when referring to "xxx-style" completions.
2022-09-26 18:39:43 +00:00
- GNU-style long options, like ``--colors``. GNU-style long options can be more than one character long, are preceded by two hyphens, and can't be grouped together. Option arguments may be specified after a ``=`` (``--quoting-style=shell``), or, if ``--require-parameter`` is given, in the following parameter (``--quoting-style shell``).
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: Improve complete docs A bit stuffy, some weird bits (I don't think GNU-style long options can typically be abbreviated, ``true --v`` and ``bash --hel`` don't work).
2020-09-09 16:56:25 +00:00
Multiple commands and paths can be given in one call to define the same completions for multiple commands.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: Improve complete docs A bit stuffy, some weird bits (I don't think GNU-style long options can typically be abbreviated, ``true --v`` and ``bash --hel`` don't work).
2020-09-09 16:56:25 +00:00
Multiple command switches and wrapped commands can also be given to define multiple completions in one call.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility
2018-12-19 20:02:45 +00:00
Invoking ``complete`` multiple times for the same command adds the new definitions on top of any existing completions defined for the command.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Make stylistic grammatical change to `complete` docs Use a hyphen when referring to "xxx-style" completions.
2022-09-26 18:39:43 +00:00
When ``-a`` or ``--arguments`` is specified in conjunction with long, short, or old-style options, the specified arguments are only completed as arguments for any of the specified options. If ``-a`` or ``--arguments`` is specified without any long, short, or old-style options, the specified arguments are used when completing non-option arguments to the command (except when completing an option argument that was specified with ``-r`` or ``--require-parameter``).
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Tweak documentation wording to include non-option arguments
2021-05-16 18:47:05 +00:00
Command substitutions found in ``ARGUMENTS`` should return a newline-separated list of arguments, and each argument may optionally have a tab character followed by the argument description. Description given this way override a description given with ``-d`` or ``--description``.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: Document how complete groups options Fixes #8146.
2021-07-23 17:29:16 +00:00
Descriptions given with ``--description`` are also used to group options given with ``-s``, ``-o`` or ``-l``. Options with the same (non-empty) description will be listed as one candidate, and one of them will be picked. If the description is empty or no description was given this is skipped.
docs: Improve complete docs A bit stuffy, some weird bits (I don't think GNU-style long options can typically be abbreviated, ``true --v`` and ``bash --hel`` don't work).
2020-09-09 16:56:25 +00:00
The ``-w`` or ``--wraps`` options causes the specified command to inherit completions from another command, "wrapping" the other command. The wrapping command can also have additional completions. A command can wrap multiple commands, and wrapping is transitive: if A wraps B, and B wraps C, then A automatically inherits all of C's completions. Wrapping can be removed using the ``-e`` or ``--erase`` options. Wrapping only works for completions specified with ``-c`` or ``--command`` and are ignored when specifying completions with ``-p`` or ``--path``.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: Improve complete docs A bit stuffy, some weird bits (I don't think GNU-style long options can typically be abbreviated, ``true --v`` and ``bash --hel`` don't work).
2020-09-09 16:56:25 +00:00
When erasing completions, it is possible to either erase all completions for a specific command by specifying ``complete -c COMMAND -e``, or by specifying a specific completion option to delete.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
docs: Improve complete docs A bit stuffy, some weird bits (I don't think GNU-style long options can typically be abbreviated, ``true --v`` and ``bash --hel`` don't work).
2020-09-09 16:56:25 +00:00
When ``complete`` is called without anything that would define or erase completions (options, arguments, wrapping, ...), it shows matching completions instead. So ``complete`` without any arguments shows all loaded completions, ``complete -c foo`` shows all loaded completions for ``foo``. Since completions are :ref:`autoloaded <syntax-function-autoloading>`, you will have to trigger them first.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Let `complete` show completions for one command if just given `-c` Currently only `complete` will list completions, and it will list all of them. That's a bit ridiculous, especially since `complete -c foo` just does nothing. So just make `complete -c foo` list all the completions for `foo`.
2020-09-09 16:03:39 +00:00
Examples
--------
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Make stylistic grammatical change to `complete` docs Use a hyphen when referring to "xxx-style" completions.
2022-09-26 18:39:43 +00:00
The short-style option ``-o`` for the ``gcc`` command needs a file argument:
Switch \fish sections to rst format
2018-12-19 03:14:04 +00:00
::
complete -c gcc -s o -r
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Make stylistic grammatical change to `complete` docs Use a hyphen when referring to "xxx-style" completions.
2022-09-26 18:39:43 +00:00
The short-style option ``-d`` for the ``grep`` command requires one of ``read``, ``skip`` or ``recurse``:
Switch \fish sections to rst format
2018-12-19 03:14:04 +00:00
::
complete -c grep -s d -x -a "read skip recurse"
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility
2018-12-19 20:02:45 +00:00
The ``su`` command takes any username as an argument. Usernames are given as the first colon-separated field in the file /etc/passwd. This can be specified as:
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Switch \fish sections to rst format
2018-12-19 03:14:04 +00:00
::
complete -x -c su -d "Username" -a "(cat /etc/passwd | cut -d : -f 1)"
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility
2018-12-19 20:02:45 +00:00
The ``rpm`` command has several different modes. If the ``-e`` or ``--erase`` flag has been specified, ``rpm`` should delete one or more packages, in which case several switches related to deleting packages are valid, like the ``nodeps`` switch.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
This can be written as:
Switch \fish sections to rst format
2018-12-19 03:14:04 +00:00
::
complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps -d "Don't check dependencies"
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility
2018-12-19 20:02:45 +00:00
where ``__fish_contains_opt`` is a function that checks the command line buffer for the presence of a specified set of options.
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility
2018-12-19 20:02:45 +00:00
To implement an alias, use the ``-w`` or ``--wraps`` option:
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Switch \fish sections to rst format
2018-12-19 03:14:04 +00:00
::
complete -c hub -w git
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Let `complete` show completions for one command if just given `-c` Currently only `complete` will list completions, and it will list all of them. That's a bit ridiculous, especially since `complete -c foo` just does nothing. So just make `complete -c foo` list all the completions for `foo`.
2020-09-09 16:03:39 +00:00
Now hub inherits all of the completions from git. Note this can also be specified in a function declaration (``function thing -w otherthing``).
::
docs: Fix markup for code blocks
2020-10-10 19:22:34 +00:00
Let `complete` show completions for one command if just given `-c` Currently only `complete` will list completions, and it will list all of them. That's a bit ridiculous, especially since `complete -c foo` just does nothing. So just make `complete -c foo` list all the completions for `foo`.
2020-09-09 16:03:39 +00:00
complete -c git
Copy doc_src to sphinx_doc_src and add a TOC
2018-12-16 21:08:41 +00:00
Move short old-style example to end
2022-10-01 00:17:07 +00:00
Shows all completions for ``git``.
Any command ``foo`` that doesn't support grouping multiple short options in one string (not supporting ``-xf`` as short for ``-x -f``) or a short option and its value in one string (not supporting ``-d9`` instead of ``-d 9``) should be specified as a single-character old-style option instead of as a short-style option; for example, ``complete -c foo -o s; complete -c foo -o v`` would never suggest ``foo -ov`` but rather ``foo -o -v``.
Reference in a new issue Copy permalink