USEFUL FUNCTIONS FOR WRITING COMPLETIONS

       fish  ships  with several functions that may be useful when writing command-specific completions. Most of
       these function names begin with the string __fish_. Such functions are internal to fish  and  their  name
       and interface may change in future fish versions. A few of these functions are described here.

       Functions beginning with the string __fish_print_ print a newline separated list of strings. For example,
       __fish_print_filesystems   prints   a   list   of  all  known  file  systems.  Functions  beginning  with
       __fish_complete_ print out a newline separated list of completions with descriptions. The description  is
       separated from the completion by a tab character.

       • __fish_complete_directories  STRING  DESCRIPTION  performs  path  completion  on  STRING, allowing only
         directories, and giving them the description DESCRIPTION.

       • __fish_complete_path STRING DESCRIPTION performs path completion on STRING, giving them the description
         DESCRIPTION.

       • __fish_complete_groups prints a list of all user groups with the groups members as description.

       • __fish_complete_pids prints a list of all processes IDs with the command name as description.

       • __fish_complete_suffix SUFFIX performs file completion but sorts files ending in SUFFIX first. This  is
         useful in conjunction with complete --keep-order.

       • __fish_complete_users prints a list of all users with their full name as description.

       • __fish_print_filesystems prints a list of all known file systems. Currently, this is a static list, and
         not dependent on what file systems the host operating system actually understands.

       • __fish_print_hostnames  prints  a list of all known hostnames. This function searches the fstab for nfs
         servers, ssh for known hosts and checks the /etc/hosts file.

       • __fish_print_interfaces prints a list of all known network interfaces.

WHERE TO PUT COMPLETIONS

       Completions can be defined on the  commandline  or  in  a  configuration  file,  but  they  can  also  be
       automatically  loaded.  Fish  automatically  searches  through  any  directories  in  the  list  variable
       $fish_complete_path, and any completions defined are automatically loaded when needed. A completion  file
       must have a filename consisting of the name of the command to complete and the suffix .fish.

       By default, Fish searches the following for completions, using the first available file that it finds:

       • A directory for end-users to keep their own completions, usually ~/.config/fish/completions (controlled
         by the XDG_CONFIG_HOME environment variable);

       • A  directory  for  systems  administrators  to install completions for all users on the system, usually
         /etc/fish/completions;

       • A     user-specified     directory      for      third-party      vendor      completions,      usually
         ~/.local/share/fish/vendor_completions.d (controlled by the XDG_DATA_HOME environment variable);

       • A  directory for third-party software vendors to ship their own completions for their software, usually
         /usr/share/fish/vendor_completions.d;

       • The completions shipped with fish, usually installed in /usr/share/fish/completions; and

       • Completions  automatically  generated  from  the  operating  system's   manual,   usually   stored   in
         ~/.cache/fish/generated_completions (controlled by XDG_CACHE_HOME environment variable).

       These  paths  are  controlled  by  parameters  set  at build, install, or run time, and may vary from the
       defaults listed above.

       This  wide  search  may  be  confusing.  If  you  are  unsure,  your  completions  probably   belong   in
       ~/.config/fish/completions.

       If  you  have  written  new  completions  for a common Unix command, please consider sharing your work by
       submitting it via the instructions in Further help and development.

       If you are developing another program and would like to ship completions with your program, install  them
       to  the  "vendor"  completions  directory.  As  this  path  may vary from system to system, the pkgconfig
       framework should be used to discover this path with the output of  pkg-config  --variable  completionsdir
       fish.

AUTHOR

       fish-shell developers

COPYRIGHT

       2024, fish-shell developers

4.0                                               Apr 20, 2025                               FISH-COMPLETIONS(1)