Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FISH-DOC(1)			  fish-shell			   FISH-DOC(1)

NAME
       fish-doc	- fish-shell Documentation

       This is the documentation for fish, the friendly	interactive shell.

       A  shell	 is a program that helps you operate your computer by starting
       other programs. fish offers a command-line interface focused on usabil-
       ity and interactive use.

       Unlike other shells, fish does not follow the POSIX standard, but still
       uses roughly the	same model.

       Some of the special features of fish are:

       o Extensive UI: Syntax highlighting,  autosuggestions,  tab  completion
	 and selection lists that can be navigated and filtered.

       o No  configuration needed: fish	is designed to be ready	to use immedi-
	 ately,	without	requiring extensive configuration.

       o Easy scripting: New functions can be added on the fly.	The syntax  is
	 easy to learn and use.

       This page explains how to install and set up fish and where to get more
       information.

FURTHER	READING
       If this is your first time using	fish, see the tutorial.

       If you are already familiar with	other shells like bash and want	to see
       the scripting differences, see Fish For Bash Users.

       For a comprehensive overview of fish's scripting	language, see The Fish
       Language.

       For information on using	fish interactively, see	Interactive use.

INSTALLATION AND START
       This section describes how to install, uninstall, start,	and  exit  the
       fish shell. It also explains how	to make	fish the default shell.

   Installation
       Up-to-date  instructions	 for installing	the latest version of fish are
       on the fish homepage.

       To install the development version of fish, see the instructions	on the
       project's GitHub	page.

   Starting and	Exiting
       Once  fish  has been installed, open a terminal.	If fish	is not the de-
       fault shell:

       o Type fish to start a fish shell:

	    > fish

       o Type exit to exit a fish shell:

	    > exit

   Executing Bash
       If fish is your default shell and you want to copy  commands  from  the
       internet	 that are written in bash (the default shell on	most systems),
       you can proceed in one of the following two ways:

       o Use the bash command with the -c switch to read from a	string:

	    > bash -c 'some bash command'

       o Use bash without a switch to open a bash shell	you can	use  and  exit
	 afterward:

	    > bash
	    $ some bash	command
	    $ exit
	    > _

   Default Shell
       To make fish your default shell:

       o Add the line /usr/local/bin/fish to /etc/shells.

       o Change	your default shell with	chsh -s	/usr/local/bin/fish.

       For detailed instructions see Switching to fish.

   Uninstalling
       For uninstalling	fish: see FAQ: Uninstalling fish.

   Shebang Line
       Because	shell  scripts	are  written in	many different languages, they
       need to carry information about which interpreter should	be used	to ex-
       ecute  them. For	this, they are expected	to have	a first	line, the she-
       bang line, which	names the interpreter executable.

       A script	written	in bash	would need a first line	like this:

	  #!/bin/bash

       When the	shell tells the	kernel to execute the file, it	will  use  the
       interpreter /bin/bash.

       For  a  script written in another language, just	replace	/bin/bash with
       the interpreter for that	language (for example: /usr/bin/python	for  a
       python script, or /usr/local/bin/fish for a fish	script).

       This  line  is only needed when scripts are executed without specifying
       the interpreter.	For functions inside fish or when executing  a	script
       with  fish  /path/to/script,  a shebang is not required (but it doesn't
       hurt!).

CONFIGURATION FILES
       When fish is started, it	reads and runs its configuration files.	 Where
       these are depends on build configuration	and environment	variables.

       The   main   file  is  ~/.config/fish/config.fish  (or  more  precisely
       $XDG_CONFIG_HOME/fish/config.fish).

       Configuration files are evaluated in the	following order:

       o Configuration snippets	in files ending	in .fish, in the directories:

	 o $__fish_config_dir/conf.d (by default, ~/.config/fish/conf.d/)

	 o $__fish_sysconf_dir/conf.d (by default, /etc/fish/conf.d/)

	 o Directories for third-party software	vendors	to ship	their own con-
	   figuration  snippets	for their software. Fish searches the directo-
	   ries	in the XDG_DATA_DIRS  environment  variable  for  a  fish/ven-
	   dor_conf.d  directory; if that variable is not defined, the default
	   is  /usr/share/fish/vendor_conf.d  and   /usr/local/share/fish/ven-
	   dor_conf.d, unless your distribution	customized this.

	 If  there are multiple	files with the same name in these directories,
	 only the first	will be	executed.  They	are executed in	order of their
	 filename, sorted (like	globs) in a natural order (i.e.	"01" sorts be-
	 fore "2").

       o System-wide configuration files,  where  administrators  can  include
	 initialization	that should be run for all users on the	system - simi-
	 lar to	/etc/profile for POSIX-style shells -  in  $__fish_sysconf_dir
	 (usually /etc/fish/config.fish).

       o User  initialization,	usually	 in  ~/.config/fish/config.fish	 (con-
	 trolled by the	XDG_CONFIG_HOME	environment variable,  and  accessible
	 as $__fish_config_dir).

       ~/.config/fish/config.fish  is  sourced	after the snippets. This is so
       users can copy snippets and override some of their behavior.

       These files are all executed on the startup of every shell. If you want
       to  run	a  command only	on starting an interactive shell, use the exit
       status of the command status --is-interactive to	determine if the shell
       is  interactive.	 If  you want to run a command only when using a login
       shell, use status --is-login instead. This will speed up	 the  starting
       of non-interactive or non-login shells.

       If you are developing another program, you may wish to install configu-
       ration which is run for all users of the	fish shell on a	 system.  This
       is discouraged; if not carefully	written, they may have side-effects or
       slow the	startup	of the shell. Additionally, users of other shells will
       not  benefit from the Fish-specific configuration. However, if they are
       absolutely required, you	may install them to the	"vendor" configuration
       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 confdir fish.

       Examples:

       If you want to add the directory	~/linux/bin to your PATH variable when
       using a login shell, add	this to	your ~/.config/fish/config.fish	file:

	  if status --is-login
	      set -gx PATH $PATH ~/linux/bin
	  end

       (alternatively use fish_add_path	like fish_add_path ~/linux/bin,	 which
       only adds the path if it	isn't included yet)

       If you want to run a set	of commands when fish exits, use an event han-
       dler that is triggered by the exit of the shell:

	  function on_exit --on-event fish_exit
	      echo fish	is now exiting
	  end

FURTHER	HELP AND DEVELOPMENT
       If you have a question not answered by this  documentation,  there  are
       several avenues for help:

       o The GitHub page

       o The official Gitter channel

       o The official mailing list at fish-users@lists.sourceforge.net

       If  you	have an	improvement for	fish, you can submit it	via the	GitHub
       page.

OTHER HELP PAGES
   Frequently asked questions
   What	is the equivalent to this thing	from bash (or other shells)?
       See Fish	for bash users

   How do I set	or clear an environment	variable?
       Use the set command:

	  set -x key value # typically set -gx key value
	  set -e key

       Since fish 3.1 you can set an environment variable for just one command
       using the key=value some	command	syntax,	like in	other shells.  The two
       lines below behave identically -	unlike other shells, fish will	output
       value both times:

	  key=value echo $key
	  begin; set -lx key value; echo $key; end

       Note  that "exported" is	not a scope, but an additional bit of state. A
       variable	can be global and exported or local and	exported or even  uni-
       versal and exported. Typically it makes sense to	make an	exported vari-
       able global.

   How do I check whether a variable is	defined?
       Use set -q var.	For example, if	set -q	var;  echo  variable  defined;
       end.   To check multiple	variables you can combine with and and or like
       so:

	  if set -q var1; or set -q var2
	      echo either variable defined
	  end

       Keep in mind that a defined variabled could also	be  empty,  either  by
       having no elements (if set like set var)	or only	empty elements (if set
       like set	var ""). Read on for how to deal with those.

   How do I check whether a variable is	not empty?
       Use string length -q -- $var.  For example,  if	string	length	-q  --
       $var;  echo  not	 empty;	end.  Note that	string length will interpret a
       list of multiple	variables as a disjunction (meaning any/or):

	  if string length -q -- $var1 $var2 $var3
	      echo at least one	of these variables is not empty
	  end

       Alternatively, use test -n "$var", but remember that the	variable  must
       be double-quoted.  For example, if test -n "$var"; echo not empty; end.
       The test	command	provides its own and (-a) and or (-o):

	  if test -n "$var1" -o	-n "$var2" -o -n "$var3"
	      echo at least one	of these variables is not empty
	  end

       If you want to know if a	variable has no	elements, use set -q var[1].

   Why doesn't set -Ux (exported universal variables) seem to work?
       A global	variable of the	same name already exists.

       Environment variables such as EDITOR or TZ can be set universally using
       set  -Ux.  However, if there is an environment variable already set be-
       fore fish starts	(such as by login scripts or  system  administrators),
       it  is imported into fish as a global variable. The variable scopes are
       searched	from the "inside out", which means that	 local	variables  are
       checked	first,	followed  by  global  variables, and finally universal
       variables.

       This means that the global value	takes precedence  over	the  universal
       value.

       To  avoid this problem, consider	changing the setting which fish	inher-
       its. If this is not possible, add a  statement  to  your	 configuration
       file (usually ~/.config/fish/config.fish):

	  set -gx EDITOR vim

   How	do I run a command every login?	What's fish's equivalent to .bashrc or
       .profile?
       Edit the	file ~/.config/fish/config.fish	[1], creating it  if  it  does
       not exist (Note the leading period).

       [1]  The	 "~/.config"  part  of	this  can be set via $XDG_CONFIG_HOME,
	    that's just	the default.

   How do I set	my prompt?
       The prompt is the output	of the fish_prompt function. Put it in ~/.con-
       fig/fish/functions/fish_prompt.fish. For	example, a simple prompt is:

	  function fish_prompt
	      set_color	$fish_color_cwd
	      echo -n (prompt_pwd)
	      set_color	normal
	      echo -n '	> '
	  end

       You  can	 also  use the Web configuration tool, fish_config, to preview
       and choose from a gallery of sample prompts.

       If you want to modify your existing prompt,  you	 can  use  funced  and
       funcsave	like:

	  >_ funced fish_prompt
	  # This opens up your editor (set in $EDITOR).
	  # Modify the function,
	  # save the file and repeat to	your liking.
	  # Once you are happy with it:
	  >_ funcsave fish_prompt

       This also applies to fish_right_prompt and fish_mode_prompt.

   Why does my prompt show a [I]?
       That's the fish_mode_prompt. It is displayed by default when you've ac-
       tivated vi mode using fish_vi_key_bindings.

       If you haven't activated	vi mode	on purpose, you	might have installed a
       third-party theme that does it.

       If   you	  want	 to   change  or  disable  this	 display,  modify  the
       fish_mode_prompt	function, for instance via funced.

   How do I customize my syntax	highlighting colors?
       Use the web configuration tool, fish_config, or	alter  the  fish_color
       family of environment variables.

   How do I change the greeting	message?
       Change  the value of the	variable fish_greeting or create a fish_greet-
       ing function. For example, to remove the	greeting use:

	  set -U fish_greeting

       Or if you prefer	not to use a universal variable, use:

	  set -g fish_greeting

       in config.fish.

   I'm seeing weird output before each prompt when using screen. What's	wrong?
       Quick answer:

       Run the following command in fish:

	  function fish_title; end; funcsave fish_title

       Problem solved!

       The long	answer:

       Fish is trying to set the titlebar  message  of	your  terminal.	 While
       screen  itself  supports	this feature, your terminal does not. Unfortu-
       nately, when the	underlying terminal doesn't support setting the	title-
       bar,  screen simply passes through the escape codes and text to the un-
       derlying	terminal instead of ignoring them. It is impossible to	detect
       and  resolve  this  problem  from  inside fish since fish has no	way of
       knowing what the	underlying terminal type is. For now, the only way  to
       fix this	is to unset the	titlebar message, as suggested above.

       Note  that  fish	 has a default titlebar	message, which will be used if
       the fish_title function is undefined. So	simply unsetting the  fish_ti-
       tle function will not work.

   How do I run	a command from history?
       Type  some part of the command, and then	hit the	^a (up) or ^a (down) ar-
       row keys	to navigate through history matches.  Additional  default  key
       bindings	 include  Control+P  (up) and Control+N	(down).	See Searchable
       command history for more	information.

   Why doesn't history substitution ("!$" etc.)	work?
       Because history substitution is an awkward interface that was  invented
       before  interactive  line  editing was even possible. Instead of	adding
       this pseudo-syntax, fish	opts for nice  history	searching  and	recall
       features.   Switching requires a	small change of	habits:	if you want to
       modify an old line/word,	first recall it, then edit.

       As a special case, most of the time history  substitution  is  used  as
       sudo  !!.  In  that case	just press Alt+S, and it will recall your last
       commandline with	sudo prefixed (or toggle a sudo	prefix on the  current
       commandline if there is anything).

       In general, fish's history recall works like this:

       o Like other shells, the	Up arrow, ^a recalls whole lines, starting from
	 the last executed line.  A single press replaces "!!",	later  presses
	 replace "!-3" and the like.

       o If the	line you want is far back in the history, type any part	of the
	 line and then press Up	one or more times.  This will filter  the  re-
	 called	 lines to ones that include this text, and you will get	to the
	 line you want much faster.  This replaces "!vi",  "!?bar.c"  and  the
	 like.

       o Alt+^a	recalls	 individual arguments, starting	from the last argument
	 in the	last executed line.   A	 single	 press	replaces  "!$",	 later
	 presses  replace  "!!:4" and such. As an alternate key	binding, Alt+.
	 can be	used.

       o If the	argument you want is far back in history (e.g. 2 lines back  -
	 that's	 a  lot	 of words!), type any part of it and then press	Alt+^a.
	 This will show	only arguments containing that part and	you  will  get
	 what you want much faster.  Try it out, this is very convenient!

       o If  you  want	to reuse several arguments from	the same line ("!!:3*"
	 and the like),	consider recalling the whole line  and	removing  what
	 you don't need	(Alt+D and Alt+Backspace are your friends).

       See documentation for more details about	line editing in	fish.

   How do I run	a subcommand? The backtick doesn't work!
       fish uses parentheses for subcommands. For example:

	  for i	in (ls)
	      echo $i
	  end

   My command (pkg-config) gives its output as a single	long string?
       Unlike  other  shells,  fish  splits command substitutions only on new-
       lines, not spaces or tabs or the	characters in $IFS.

       That means if you run

	  echo x(printf	'%s ' a	b c)x

       It will print xa	b c x, because the "a b	c " is used in one piece.  But
       if you do

	  echo x(printf	'%s\n' a b c)x

       it will print xax xbx xcx.

       In the overwhelming majority of cases, splitting	on spaces is unwanted,
       so this is an improvement.

       However sometimes, especially with pkg-config and related tools,	split-
       ting on spaces is needed.

       In these	cases use string split -n " " like:

	  g++ example_01.cpp (pkg-config --cflags --libs gtk+-2.0 | string split -n " ")

       The -n is so empty elements are removed like POSIX shells would do.

   How do I get	the exit status	of a command?
       Use  the	 $status  variable. This replaces the $? variable used in some
       other shells.

	  somecommand
	  if test $status -eq 7
	      echo "That's my lucky number!"
	  end

       If you are just interested in success or	failure, you can run the  com-
       mand directly as	the if-condition:

	  if somecommand
	      echo "Command succeeded"
	  else
	      echo "Command failed"
	  end

       Or  if  you  just want to do one	command	in case	the first succeeded or
       failed, use and or or:

	  somecommand
	  or someothercommand

       See the documentation for test and if for more information.

   My command prints No	matches	for wildcard but works in bash
       In short: quote or escape the wildcard:

	  scp user@ip:/dir/"string-*"

       When fish sees an unquoted *,  it  performs  wildcard  expansion.  That
       means it	tries to match filenames to the	given string.

       If  the	wildcard doesn't match any files, fish prints an error instead
       of running the command:

	  > echo *this*does*not*exist
	  fish:	No matches for wildcard	'*this*does*not*exist'.	See `help expand`.
	  echo *this*does*not*exist 2>|	xsel --clipboard
	       ^

       Now, bash also tries to match files in this case, but when  it  doesn't
       find a match, it	passes along the literal wildcard string instead.

       That means that commands	like the above

	  scp user@ip:/dir/string-*

       or

	  apt install postgres-*

       appear  to  work, because most of the time the string doesn't match and
       so it passes along the string-*,	which is then interpreted by  the  re-
       ceiving program.

       But  it	also  means that these commands	can stop working at any	moment
       once a matching file is encountered (because it has been	created	or the
       command is executed in a	different working directory), and to deal with
       that bash needs workarounds like

	  for f	in ./*.mpg; do
		# We need to test if the file really exists because
		# the wildcard might have failed to match.
		test -f	"$f" ||	continue
		mympgviewer "$f"
	  done

       (from http://mywiki.wooledge.org/BashFAQ/004)

       For these reasons, fish does not	do this, and instead expects asterisks
       to be quoted or escaped if they aren't supposed to be expanded.

       This is similar to bash's "failglob" option.

   I  accidentally  entered  a directory path and fish changed directory. What
       happened?
       If fish is unable to locate a command with a given name,	and it	starts
       with  .,	 / or ~, fish will test	if a directory of that name exists. If
       it does,	it is implicitly assumed that you want to change  working  di-
       rectory.	 For example, the fastest way to switch	to your	home directory
       is to simply press ~ and	enter.

   How can I use - as a	shortcut for cd	-?
       In fish versions	prior to 2.5.0 it was possible to  create  a  function
       named  -	that would do cd -. Changes in the 2.5.0 release included sev-
       eral bug	fixes that enforce the rule that a bare	hyphen is not a	 valid
       function	 (or  variable)	name. However, you can achieve the same	effect
       via an abbreviation:

	  abbr -a -- - 'cd -'

   The open command doesn't work.
       The open	command	uses the MIME type database  and  the  .desktop	 files
       used  by	Gnome and KDE to identify filetypes and	default	actions. If at
       least one of these environments is installed, but the open  command  is
       not  working, this probably means that the relevant files are installed
       in a non-standard location. Consider asking for more help.

   Why won't SSH/SCP/rsync connect properly when fish is my login shell?
       This problem may	show up	as messages like "Received message too	long",
       "open  terminal	failed:	not a terminal", "Bad packet length", or "Con-
       nection refused"	with  strange  output  in  ssh_exchange_identification
       messages	in the debug log.

       This  usually  happens  because	fish reads the user configuration file
       (~/.config/fish/config.fish) always, whether it's in an interactive  or
       login or	non-interactive	or non-login shell.

       This  simplifies	 matters, but it also means when config.fish generates
       output, it will do that even in non-interactive	shells	like  the  one
       ssh/scp/rsync start when	they connect.

       Anything	 in  config.fish  that	produces output	should be guarded with
       status is-interactive (or status	is-login if you	prefer):

	  if status is-interactive
	    ...
	  end

       The same	applies	for example when you start tmux	in config.fish without
       guards,	which will cause a message like	sessions should	be nested with
       care, unset $TMUX to force.

   I'm getting weird graphical glitches	(a staircase effect, ghost characters,
       cursor in the wrong position,...)?
       In  a  terminal,	the application	running	inside it and the terminal it-
       self need to agree on the width of characters in	order to handle	cursor
       movement.

       This  is	more important to fish than other shells because features like
       syntax highlighting and autosuggestions are implemented by  moving  the
       cursor.

       Sometimes,  there  is  disagreement  on	the  width. There are numerous
       causes and fixes	for this:

       o It is possible	the character is simply	too new	 for  your  system  to
	 know -	in this	case you need to refrain from using it.

       o Fish or your terminal might not know about the	character or handle it
	 wrong - in this case fish or your terminal needs to be	fixed, or  you
	 need to update	to a fixed version.

       o The  character	 has an	"ambiguous" width and fish thinks that means a
	 width of X while your terminal	thinks it's Y. In this case you	either
	 need  to  change  your	 terminal's configuration or set $fish_ambigu-
	 ous_width to the correct value.

       o The character is an emoji and the host	system only  supports  Unicode
	 8,  while  you	are running the	terminal on a system that uses Unicode
	 >= 9. In this case set	$fish_emoji_width to 2.

       This also means that a few things are unsupportable:

       o Non-monospace fonts - there is	no way for fish	 to  figure  out  what
	 width	a  specific character has as it	has no influence on the	termi-
	 nal's font rendering.

       o Different widths for multiple ambiguous width characters -  there  is
	 no way	for fish to know which width you assign	to each	character.

   How do I make fish my default shell?
       If  you	installed  fish	manually (e.g. by compiling it,	not by using a
       package manager), you first need	to add fish to the list	of  shells  by
       executing  the  following  command  (assuming  you  installed  fish  in
       /usr/local):

	  echo /usr/local/bin/fish | sudo tee -a /etc/shells

       If you installed	a prepackaged version of  fish,	 the  package  manager
       should have already done	this for you.

       In order	to change your default shell, type:

	  chsh -s /usr/local/bin/fish

       You  may	 need  to adjust the above path	to e.g.	/usr/bin/fish. Use the
       command which fish if you are unsure of where fish is installed.

       Unfortunately, there is no way to make the changes take effect at once.
       You will	need to	log out	and back in again.

   Uninstalling	fish
       If  you want to uninstall fish, first make sure fish is not set as your
       shell. Run chsh -s /bin/bash if you are not sure.

       If you installed	it with	a package manager, just	use that package  man-
       ager's uninstall	function. If you built fish yourself, assuming you in-
       stalled it to /usr/local, do this:

	  rm -Rf /usr/local/etc/fish /usr/local/share/fish ~/.config/fish
	  rm /usr/local/share/man/man1/fish*.1
	  cd /usr/local/bin
	  rm -f	fish fish_indent

   Where can I find extra tools	for fish?
       The fish	user community extends fish in	unique	and  useful  ways  via
       scripts that aren't always appropriate for bundling with	the fish pack-
       age. Typically because they solve a niche problem unlikely to appeal to
       a  broad	 audience.  You	 can find those	extensions, including prompts,
       themes and useful functions, in various third-party repositories. These
       include:

       o Fisher

       o Fundle

       o Oh My Fish

       o Tacklebox

       This  is	not an exhaustive list and the fish project has	no opinion re-
       garding the merits of the repositories  listed  above  or  the  scripts
       found therein.

   Interactive use
       Fish  prides  itself  on	being really nice to use interactively.	That's
       down to a few features we'll explain in the next	few sections.

       Fish is used by giving commands in the fish language, see The Fish Lan-
       guage for information on	that.

   Help
       Fish  has an extensive help system. Use the help	command	to obtain help
       on a specific subject or	command. For  instance,	 writing  help	syntax
       displays	the syntax section of this documentation.

       Fish also has man pages for its commands, and translates	the help pages
       to man pages. For example, man set will show the	documentation for  set
       as a man	page.

       Help  on	a specific builtin can also be obtained	with the -h parameter.
       For instance, to	obtain help on the fg builtin, either type  fg	-h  or
       help fg.

       This  page can be viewed	via help index (or just	help) or man fish-doc.
       The tutorial can	be viewed with help tutorial or	man fish-tutorial.

   Autosuggestions
       fish suggests commands as you type, based on command  history,  comple-
       tions,  and valid file paths. As	you type commands, you will see	a sug-
       gestion offered after the cursor, in a muted gray color (which  can  be
       changed with the	fish_color_autosuggestion variable).

       To  accept  the	autosuggestion	(replacing the command line contents),
       press ^a or Control+F. To	accept the first suggested word,  press	 Alt+^a
       or  Alt+F.  If the autosuggestion is not	what you want, just ignore it:
       it won't	execute	unless you accept it.

       Autosuggestions are a powerful way to quickly summon frequently entered
       commands,  by  typing  the first	few characters.	They are also an effi-
       cient technique for navigating through directory	hierarchies.

   Tab Completion
       Tab completion is a time	saving feature of any modern shell.  When  you
       type Tab, fish tries to guess the rest of the word under	the cursor. If
       it finds	just one possibility, it inserts it. If	it finds more, it  in-
       serts  the longest unambiguous part and then opens a menu (the "pager")
       that you	can navigate to	find what you're looking for.

       The pager can be	navigated with the arrow keys, Page Up	/  Page	 Down,
       Tab or Shift+Tab. Pressing Control+S (the pager-toggle-search binding -
       / in vi-mode) opens up a	search menu that you can  use  to  filter  the
       list.

       Fish provides some general purpose completions:

       o Commands (builtins, functions and regular programs).

       o Shell variable	names.

       o Usernames for tilde expansion.

       o Filenames, even on strings with wildcards such	as * and **.

       It  also	 provides  a large number of program specific scripted comple-
       tions. Most of these completions	are simple options like	the -l	option
       for ls, but some	are more advanced. For example:

       o The  programs	man and	whatis show all	installed manual pages as com-
	 pletions.

       o The make program uses all targets in the Makefile in the current  di-
	 rectory as completions.

       o The mount command uses	all mount points specified in fstab as comple-
	 tions.

       o The ssh command uses all hosts	that are  stored  in  the  known_hosts
	 file as completions. (See the ssh documentation for more information)

       o The su	command	shows the users	on the system

       o The apt-get, rpm and yum commands show	installed or installable pack-
	 ages

       You can also write your own completions or install some	you  got  from
       someone else. For that, see Writing your	own completions.

   Syntax highlighting
       Fish  interprets	 the command line as it	is typed and uses syntax high-
       lighting	to provide feedback. The most important	feedback is the	detec-
       tion of potential errors. By default, errors are	marked red.

       Detected	errors include:

       o Non existing commands.

       o Reading from or appending to a	non existing file.

       o Incorrect use of output redirects

       o Mismatched parenthesis

       When  the cursor	is over	a parenthesis or a quote, fish also highlights
       its matching quote or parenthesis.

       To customize the	syntax highlighting, you can set the environment vari-
       ables listed in the Variables for changing highlighting colors section.

   Syntax highlighting variables
       The  colors  used  by fish for syntax highlighting can be configured by
       changing	the values of a	various	variables. The value  of  these	 vari-
       ables  can  be one of the colors	accepted by the	set_color command. The
       modifier	switches accepted by set_color like --bold, --dim,  --italics,
       --reverse and --underline are also accepted.

       Example:	to make	errors highlighted and red, use:

	  set fish_color_error red --bold

       The following variables are available to	change the highlighting	colors
       in fish:

	      +--------------------------+----------------------------+
	      |Variable			 | Meaning		      |
	      +--------------------------+----------------------------+
	      |fish_color_normal	 | default color	      |
	      +--------------------------+----------------------------+
	      |fish_color_command	 | commands like echo	      |
	      +--------------------------+----------------------------+
	      |fish_color_keyword	 | keywords like  if  -	 this |
	      |				 | falls  back on the command |
	      |				 | color if unset	      |
	      +--------------------------+----------------------------+
	      |fish_color_quote		 | quoted text like "abc"     |
	      +--------------------------+----------------------------+
	      |fish_color_redirection	 | IO	 redirections	 like |
	      |				 | >/dev/null		      |
	      +--------------------------+----------------------------+
	      |fish_color_end		 | process   separators	 like |
	      |				 | ';' and '&'		      |
	      +--------------------------+----------------------------+
	      |fish_color_error		 | syntax errors	      |
	      +--------------------------+----------------------------+
	      |fish_color_param		 | ordinary  command  parame- |
	      |				 | ters			      |
	      +--------------------------+----------------------------+

	      |fish_color_comment	 | comments  like  '#  impor- |
	      |				 | tant'		      |
	      +--------------------------+----------------------------+
	      |fish_color_selection	 | selected text in vi visual |
	      |				 | mode			      |
	      +--------------------------+----------------------------+
	      |fish_color_operator	 | parameter expansion opera- |
	      |				 | tors	like '*' and '~'      |
	      +--------------------------+----------------------------+
	      |fish_color_escape	 | character escapes like 'n' |
	      |				 | and 'x70'		      |
	      +--------------------------+----------------------------+
	      |fish_color_autosuggestion | autosuggestions  (the pro- |
	      |				 | posed rest of a command)   |
	      +--------------------------+----------------------------+
	      |fish_color_cwd		 | the current working direc- |
	      |				 | tory	in the default prompt |
	      +--------------------------+----------------------------+
	      |fish_color_user		 | the	username  in  the de- |
	      |				 | fault prompt		      |
	      +--------------------------+----------------------------+
	      |fish_color_host		 | the hostname	 in  the  de- |
	      |				 | fault prompt		      |
	      +--------------------------+----------------------------+
	      |fish_color_host_remote	 | the	hostname  in  the de- |
	      |				 | fault  prompt  for  remote |
	      |				 | sessions (like ssh)	      |
	      +--------------------------+----------------------------+
	      |fish_color_cancel	 | the	'^C'  indicator	 on a |
	      |				 | canceled command	      |
	      +--------------------------+----------------------------+
	      |fish_color_search_match	 | history search matches and |
	      |				 | selected    pager	items |
	      |				 | (background only)	      |
	      +--------------------------+----------------------------+

       If a variable isn't set,	fish usually tries $fish_color_normal,	except
       for $fish_color_keyword,	where it tries $fish_color_command first.

   Pager color variables
       fish  will  sometimes  present a	list of	choices	in a table, called the
       pager.

       Example:	to set the background of each pager row, use:

	  set fish_pager_color_background --background=white

       To have black text on alternating white and gray	backgrounds:

	  set fish_pager_color_prefix black
	  set fish_pager_color_completion black
	  set fish_pager_color_description black
	  set fish_pager_color_background --background=white
	  set fish_pager_color_secondary_background --background=brwhite

       Variables affecting the pager colors:

	      +--------------------------+----------------------------+
	      |Variable			 | Meaning		      |
	      +--------------------------+----------------------------+
	      |fish_pager_color_progress | the progress	 bar  at  the |
	      |				 | bottom left corner	      |
	      +--------------------------+----------------------------+
	      |fish_pager_color_back-	 | the background color	of  a |
	      |ground			 | line			      |
	      +--------------------------+----------------------------+

	      |fish_pager_color_prefix	 | the	prefix	string,	 i.e. |
	      |				 | the string that is  to  be |
	      |				 | completed		      |
	      +--------------------------+----------------------------+
	      |fish_pager_color_comple-	 | the	 completion   itself, |
	      |tion			 | i.e.	 the proposed rest of |
	      |				 | the string		      |
	      +--------------------------+----------------------------+
	      |fish_pager_color_descrip- | the completion description |
	      |tion			 |			      |
	      +--------------------------+----------------------------+
	      |fish_pager_color_se-	 | background of the selected |
	      |lected_background	 | completion		      |
	      +--------------------------+----------------------------+
	      |fish_pager_color_se-	 | prefix  of  the   selected |
	      |lected_prefix		 | completion		      |
	      +--------------------------+----------------------------+
	      |fish_pager_color_se-	 | suffix  of  the   selected |
	      |lected_completion	 | completion		      |
	      +--------------------------+----------------------------+
	      |fish_pager_color_se-	 | description	of  the	  se- |
	      |lected_description	 | lected completion	      |
	      +--------------------------+----------------------------+
	      |fish_pager_color_sec-	 | background of every second |
	      |ondary_background	 | unselected completion      |
	      +--------------------------+----------------------------+
	      |fish_pager_color_sec-	 | prefix of every second un- |
	      |ondary_prefix		 | selected completion	      |
	      +--------------------------+----------------------------+
	      |fish_pager_color_sec-	 | suffix of every second un- |
	      |ondary_completion	 | selected completion	      |
	      +--------------------------+----------------------------+
	      |fish_pager_color_sec-	 | description of every	 sec- |
	      |ondary_description	 | ond unselected completion  |
	      +--------------------------+----------------------------+

       When  the  secondary or selected	variables aren't set, the normal vari-
       ables are used, except for $fish_pager_color_selected_background, where
       the background of $fish_color_search_match is tried first.

   Abbreviations
       To  avoid  needless  typing, a frequently-run command like git checkout
       can be abbreviated to gco using the abbr	command.

	  abbr -a gco git checkout

       After entering gco and pressing Space  or  Enter,  the  full  text  git
       checkout	will appear in the command line.

       This  is	 an alternative	to aliases, and	has the	advantage that you see
       the actual command before using it, and	the  actual  command  will  be
       stored in history.

   Programmable	title
       When  using  most  virtual terminals, it	is possible to set the message
       displayed in the	titlebar of the	terminal window. This can be done  au-
       tomatically in fish by defining the fish_title function.	The fish_title
       function	is executed before and after a new command is executed or  put
       into  the  foreground and the output is used as a titlebar message. The
       status current-command builtin will always return the name of  the  job
       to  be  put into	the foreground (or fish	if control is returning	to the
       shell) when the fish_prompt _cmd-fish_prompt_ function is  called.  The
       first  argument	to  fish_title will contain the	most recently executed
       foreground command as a string, starting	with fish 2.2.

       Examples: The default fish title	is:

	  function fish_title
	      echo (status current-command) ' '
	      pwd
	  end

       To show the last	command	in the title:

	  function fish_title
	      echo $argv[1]
	  end

   Programmable	prompt
       When fish waits for input, it will display a prompt by  evaluating  the
       fish_prompt  and	 fish_right_prompt functions. The output of the	former
       is displayed on the left	and the	latter's output	on the right  side  of
       the  terminal.  The output of fish_mode_prompt will be prepended	on the
       left, though the	default	function only does this	when in	vi-mode.

   Configurable	greeting
       If a function named fish_greeting exists, it will be run	when  entering
       interactive   mode.   Otherwise,	  if  an  environment  variable	 named
       fish_greeting exists, it	will be	printed.

   Private mode
       If $fish_private_mode is	set to a non-empty value, commands will	not be
       written to the history file on disk.

       You  can	 also  launch with fish	--private (or fish -P for short). This
       both hides old history and prevents writing history to  disk.  This  is
       useful  to avoid	leaking	personal information (e.g. for screencasts) or
       when dealing with sensitive information.

       You can query the variable fish_private_mode (if	 test  -n  "$fish_pri-
       vate_mode"  ...)	 if you	would like to respect the user's wish for pri-
       vacy and	alter the behavior of your own fish scripts.

   Command line	editor
       The fish	editor features	copy and paste,	a searchable history and  many
       editor functions	that can be bound to special keyboard shortcuts.

       Like  bash  and other shells, fish includes two sets of keyboard	short-
       cuts (or	key bindings): one inspired by the Emacs text editor, and  one
       by  the	Vi  text  editor.  The	default	editing	mode is	Emacs. You can
       switch to Vi mode by running fish_vi_key_bindings and switch back  with
       fish_default_key_bindings.  You	can also make your own key bindings by
       creating	a function and setting the fish_key_bindings variable  to  its
       name. For example:

	  function fish_hybrid_key_bindings --description \
	  "Vi-style bindings that inherit emacs-style bindings in all modes"
	      for mode in default insert visual
		  fish_default_key_bindings -M $mode
	      end
	      fish_vi_key_bindings --no-erase
	  end
	  set -g fish_key_bindings fish_hybrid_key_bindings

       While the key bindings included with fish include many of the shortcuts
       popular from the	respective text	editors, they are not a	 complete  im-
       plementation.  They include a shortcut to open the current command line
       in your preferred editor	(Alt+E by default) if you need the full	 power
       of your editor.

   Shared bindings
       Some  bindings are common across	Emacs and Vi mode, because they	aren't
       text editing bindings, or because what Vi/Vim does for a	particular key
       doesn't make sense for a	shell.

       o Tab  completes	the current token. Shift+Tab completes the current to-
	 ken and starts	the pager's search mode.

       o ^a (Left) and ^a	(Right)	move the cursor	left or	right by  one  charac-
	 ter. If the cursor is already at the end of the line, and an autosug-
	 gestion is available, ^a accepts the autosuggestion.

       o Enter executes	the current commandline	or inserts a newline  if  it's
	 not complete yet (e.g.	a ) or end is missing).

       o Alt+Enter inserts a newline at	the cursor position.

       o Alt+^a	and  Alt+^a move	the cursor one word left or right (to the next
	 space or punctuation mark), or	moves forward/backward in  the	direc-
	 tory  history	if the command line is empty. If the cursor is already
	 at the	end of the line, and an	autosuggestion is available, Alt+^a (or
	 Alt+F)	accepts	the first word in the suggestion.

       o Control+^a and Control+^a move the cursor one word left or right. These
	 accept	one word of the	autosuggestion - the part they'd move over.

       o Shift+^a and Shift+^a move the cursor one word left or  right,  without
	 stopping on punctuation. These	accept one big word of the autosugges-
	 tion.

       o ^a (Up)	and ^a (Down) (or Control+P and Control+N for  emacs  aficiona-
	 dos)  search  the  command history for	the previous/next command con-
	 taining the string that was specified on the commandline  before  the
	 search	 was  started.	If  the	 commandline was empty when the	search
	 started, all commands match. See the history section for more	infor-
	 mation	on history searching.

       o Alt+^a	and Alt+^a search the command history for the previous/next to-
	 ken containing	the token under	 the  cursor  before  the  search  was
	 started.  If  the  commandline	 was  not  on  a token when the	search
	 started, all tokens match. See	the history section for	more  informa-
	 tion on history searching.

       o Control+C cancels the entire line.

       o Control+D  delete  one	 character  to the right of the	cursor.	If the
	 command line is empty,	Control+D will exit fish.

       o Control+U moves contents from the beginning of	line to	the cursor  to
	 the killring.

       o Control+L clears and repaints the screen.

       o Control+R  searches the history if there is something in the command-
	 line. This is mainly to ease the transition from other	shells,	 where
	 ctrl+r	initiates the history search.

       o Control+W  moves  the	previous  path component (everything up	to the
	 previous "/", ":" or "@") to the Copy and paste (Kill Ring).

       o Control+X copies the current buffer to	the system's  clipboard,  Con-
	 trol+V	inserts	the clipboard contents.

       o Alt+D moves the next word to the Copy and paste (Kill Ring).

       o Alt+H	(or  F1) shows the manual page for the current command,	if one
	 exists.

       o Alt+L lists the contents of the current directory, unless the	cursor
	 is  over a directory argument,	in which case the contents of that di-
	 rectory will be listed.

       o Alt+O opens the file at the cursor in a pager.

       o Alt+P adds the	string &| less;	to the end of the job under  the  cur-
	 sor. The result is that the output of the command will	be paged.

       o Alt+W prints a	short description of the command under the cursor.

       o Alt+E edit the	current	command	line in	an external editor. The	editor
	 is chosen from	the first available of the $VISUAL  or	$EDITOR	 vari-
	 ables.

       o Alt+V Same as Alt+E.

       o Alt+S Prepends	sudo to	the current commandline. If the	commandline is
	 empty,	prepend	sudo to	the last commandline.

       o Control+Space Inserts a space without expanding an abbreviation.  For
	 vi-mode this only applies to insert-mode.

   Emacs mode commands
       o Home or Control+A moves the cursor to the beginning of	the line.

       o End  or  Control+E moves to the end of	line. If the cursor is already
	 at the	end of the line, and an	autosuggestion is  available,  End  or
	 Control+E accepts the autosuggestion.

       o Control+B,  Control+F	move the cursor	one character left or right or
	 accept	the autosuggestion just	like the ^a (Left) and ^a	(Right)	shared
	 bindings (which are available as well).

       o Control+N, Control+P move the cursor up/down or through history, like
	 the up	and down arrow shared bindings.

       o Delete	or Backspace removes one character forwards or	backwards  re-
	 spectively.

       o Control+K  moves  contents  from the cursor to	the end	of line	to the
	 Copy and paste	(Kill Ring).

       o Alt+C capitalizes the current word.

       o Alt+U makes the current word uppercase.

       o Control+T transposes the last two characters.

       o Alt+T transposes the last two words.

       o Control+Z, Control+_ (Control+/ on some terminals) undo the most  re-
	 cent edit of the line.

       o Alt+/ reverts the most	recent undo.

       You can change these key	bindings using the bind	builtin.

   Vi mode commands
       Vi  mode	 allows	 for  the  use of Vi-like commands at the prompt. Ini-
       tially, insert mode is active. Escape enters command mode. The commands
       available  in  command,	insert and visual mode are described below. Vi
       mode shares some	bindings with Emacs mode.

       It is also possible to add all emacs-mode bindings to vi-mode by	 using
       something like:

	  function fish_user_key_bindings
	      #	Execute	this once per mode that	emacs bindings should be used in
	      fish_default_key_bindings	-M insert

	      #	Then execute the vi-bindings so	they take precedence when there's a conflict.
	      #	Without	--no-erase fish_vi_key_bindings	will default to
	      #	resetting all bindings.
	      #	The argument specifies the initial mode	(insert, "default" or visual).
	      fish_vi_key_bindings --no-erase insert
	  end

       When  in	vi-mode, the fish_mode_prompt function will display a mode in-
       dicator to the left of the prompt. To disable this feature, override it
       with  an	 empty	function.  To display the mode elsewhere (like in your
       right prompt), use the output of	the fish_default_mode_prompt function.

       When a binding switches the mode, it will repaint the mode-prompt if it
       exists, and the rest of the prompt only if it doesn't. So if you	want a
       mode-indicator in your fish_prompt, you need to erase  fish_mode_prompt
       e.g.    by    adding    an    empty    file   at	  ~/.config/fish/func-
       tions/fish_mode_prompt.fish. (Bindings that change the  mode  are  sup-
       posed to	call the repaint-mode bind function, see bind)

       The  fish_vi_cursor  function will be used to change the	cursor's shape
       depending on the	mode in	supported terminals. The following snippet can
       be used to manually configure cursors after enabling vi-mode:

	  # Emulates vim's cursor shape	behavior
	  # Set	the normal and visual mode cursors to a	block
	  set fish_cursor_default block
	  # Set	the insert mode	cursor to a line
	  set fish_cursor_insert line
	  # Set	the replace mode cursor	to an underscore
	  set fish_cursor_replace_one underscore
	  # The	following variable can be used to configure cursor shape in
	  # visual mode, but due to fish_cursor_default, is redundant here
	  set fish_cursor_visual block

       Additionally, blink can be added	after each of the cursor shape parame-
       ters to set a blinking cursor in	the specified shape.

       If the cursor shape does	not appear to be changing  after  setting  the
       above  variables,  it's	likely your terminal emulator does not support
       the capabilities	necessary to do	this. It may also be  the  case,  how-
       ever,  that  fish_vi_cursor  has	 not detected your terminal's features
       correctly (for example, if you are using	tmux). If this	is  the	 case,
       you  can	 force	fish_vi_cursor	to  set	 the  cursor  shape by setting
       $fish_vi_force_cursor in	config.fish. You'll have to restart  fish  for
       any  changes to take effect. If cursor shape setting remains broken af-
       ter this, it's almost certainly an issue	with your  terminal  emulator,
       and not fish.

   Command mode
       Command mode is also known as normal mode.

       o H moves the cursor left.

       o L moves the cursor right.

       o I enters insert mode at the current cursor position.

       o V enters visual mode at the current cursor position.

       o A enters insert mode after the	current	cursor position.

       o Shift+A enters	insert mode at the end of the line.

       o 0  (zero) moves the cursor to beginning of line (remaining in command
	 mode).

       o D+D deletes the current line and moves	it to the Copy and paste (Kill
	 Ring).

       o Shift+D  deletes  text	after the current cursor position and moves it
	 to the	Copy and paste (Kill Ring).

       o P pastes text from the	Copy and paste (Kill Ring).

       o U search history backwards.

       o [ and ] search	the command history for	the previous/next  token  con-
	 taining the token under the cursor before the search was started. See
	 the history section for more information on history searching.

       o Backspace moves the cursor left.

   Insert mode
       o Escape	enters command mode.

       o Backspace removes one character to the	left.

   Visual mode
       o ^a (Left) and ^a	(Right)	extend the selection backward/forward  by  one
	 character.

       o B and W extend	the selection backward/forward by one word.

       o D  and	X move the selection to	the Copy and paste (Kill Ring) and en-
	 ter command mode.

       o Escape	and Control+C enter command mode.

       o c and s remove	the selection and switch to insert mode

       o d and x remove	the selection and switch to normal mode

       o X removes the entire line and switches	to normal mode

       o y copies the selection	and switches to	normal mode

       o ~ toggles the case (upper/lower) on the  selection  and  switches  to
	 normal	mode

       o "*y copies the	selection to the clipboard and switches	to normal mode

   Custom bindings
       In  addition  to	the standard bindings listed here, you can also	define
       your own	with bind:

	  # Just clear the commandline on control-c
	  bind \cc 'commandline	-r ""'

       Put  bind  statements   into   config.fish   or	 a   function	called
       fish_user_key_bindings.

       The  key	 sequence  (the	\cc) here depends on your setup, in particular
       the terminal. To	find out what the terminal sends use fish_key_reader:

	  > fish_key_reader # pressing control-c
	  Press	a key:
		      hex:    3	 char: \cC
	  Press	[ctrl-C] again to exit
	  bind \cC 'do something'

	  > fish_key_reader # pressing the right-arrow
	  Press	a key:
		      hex:   1B	 char: \c[  (or	\e)
	  (  0.077 ms)	hex:   5B  char: [
	  (  0.037 ms)	hex:   43  char: C
	  bind \e\[C 'do something'

       Note that some key combinations are  indistinguishable  or  unbindable.
       For  instance  control-i	is the same as the tab key. This is a terminal
       limitation that fish can't do anything about.

       Also, Escape is the same	thing as Alt in	a terminal. To distinguish be-
       tween  pressing	Escape and then	another	key, and pressing Alt and that
       key (or an escape sequence the key sends), fish	waits  for  a  certain
       time  after  seeing  an	escape character. This is configurable via the
       fish_escape_delay_ms variable.

       If you want to be able to press Escape and then a character and have it
       count as	Alt+that character, set	it to a	higher value, e.g.:

	  set -g fish_escape_delay_ms 100

   Copy	and paste (Kill	Ring)
       Fish  uses  an  Emacs-style kill	ring for copy and paste	functionality.
       For example, use	Control+K (kill-line) to cut from the  current	cursor
       position	 to the	end of the line. The string that is cut	(a.k.a.	killed
       in emacs-ese) is	inserted into a	list of	kills, called the  kill	 ring.
       To  paste  the latest value from	the kill ring (emacs calls this	"yank-
       ing") use Control+Y (the	yank input function). After pasting, use Alt+Y
       (yank-pop) to rotate to the previous kill.

       Copy  and paste from outside are	also supported,	both via the Control+X
       / Control+V bindings (the fish_clipboard_copy and  fish_clipboard_paste
       functions  [1])	and  via the terminal's	paste function,	for which fish
       enables "Bracketed Paste	Mode", so it can tell a	 paste	from  manually
       entered	text.	In addition, when pasting inside single	quotes,	pasted
       single quotes and backslashes are automatically escaped so that the re-
       sult  can  be used as a single token simply by closing the quote	after.
       Kill ring entries are stored in fish_killring variable.

       [1]  These   rely   on	external   tools.   Currently	xsel,	xclip,
	    wl-copy/wl-paste and pbcopy/pbpaste	are supported.

   Multiline editing
       The  fish  commandline  editor can be used to work on commands that are
       several lines long. There are three ways	to make	a  command  span  more
       than a single line:

       o Pressing the Enter key	while a	block of commands is unclosed, such as
	 when one or more block	commands such as for, begin or if do not  have
	 a corresponding end command.

       o Pressing Alt+Enter instead of pressing	the Enter key.

       o By inserting a	backslash (\) character	before pressing	the Enter key,
	 escaping the newline.

       The fish	commandline editor works exactly the same in single line  mode
       and in multiline	mode. To move between lines use	the left and right ar-
       row keys	and other such keyboard	shortcuts.

   Searchable command history
       After a command has been	executed, it  is  remembered  in  the  history
       list.  Any duplicate history items are automatically removed. By	press-
       ing the up and down keys, you can search	forwards and backwards in  the
       history.	 If the	current	command	line is	not empty when starting	a his-
       tory search, only the commands containing the string entered  into  the
       command line are	shown.

       By  pressing  Alt+^a  and	Alt+^a, a history search	is also	performed, but
       instead of searching for	a complete commandline,	 each  commandline  is
       broken  into  separate elements just like it would be before execution,
       and the history is searched for an element matching that	under the cur-
       sor.

       History searches	are case-insensitive unless the	search string contains
       an uppercase character. You can stop  a	search	to  edit  your	search
       string by pressing Esc or Page Down.

       Prefixing  the  commandline  with  a space will prevent the entire line
       from being stored in the	history.

       The command history is stored in	the file ~/.local/share/fish/fish_his-
       tory  (or  $XDG_DATA_HOME/fish/fish_history if that variable is set) by
       default.	However, you can set the fish_history environment variable  to
       change  the  name of the	history	session	(resulting in a	<session>_his-
       tory file); both	before starting	the shell and while the	shell is  run-
       ning.

       See the history command for other manipulations.

       Examples:

       To search for previous entries containing the word 'make', type make in
       the console and press the up key.

       If the commandline reads	cd m, place the	cursor over  the  m  character
       and press Alt+^a to search for previously	typed words containing 'm'.

   Navigating directories
       The current working directory can be displayed with the pwd command, or
       the $PWD	special	variable.

   Directory history
       Fish automatically keeps	a trail	of the recent visited directories with
       cd by storing this history in the dirprev and dirnext variables.

       Several commands	are provided to	interact with this directory history:

       o dirh prints the history

       o cdh displays a	prompt to quickly navigate the history

       o prevd moves backward through the history. It is bound to Alt+^a

       o nextd moves forward through the history. It is	bound to Alt+^a

   Directory stack
       Another	set  of	 commands, usually also	available in other shells like
       bash, deal with the directory stack. Stack handling  is	not  automatic
       and needs explicit calls	of the following commands:

       o dirs prints the stack

       o pushd	adds  a	directory on top of the	stack and makes	it the current
	 working directory

       o popd removes the directory on top of the stack	and changes  the  cur-
	 rent working directory

   The fish language
       This document is	a comprehensive	overview of fish's scripting language.

       For interactive features	see Interactive	use.

   Syntax overview
       Shells  like  fish  are used by giving them commands. A command is exe-
       cuted by	writing	the name of the	command	followed by any	arguments. For
       example:

	  echo hello world

       This  calls  the	echo command. echo writes its arguments	to the screen.
       In this example the output is hello world.

       Everything in fish is done with commands. There are  commands  for  re-
       peating	other commands,	commands for assigning variables, commands for
       treating	a group	of commands as a single	command,  etc.	All  of	 these
       commands	follow the same	basic syntax.

       To  learn  more	about the echo command,	read its manual	page by	typing
       man echo. man is	a command for displaying a  manual  page  on  a	 given
       topic.  It takes	the name of the	manual page to display as an argument.
       There are manual	pages for almost every command.	There are also	manual
       pages  for  many	 other	things,	such as	system libraries and important
       files.

       Every program on	your computer can be used as a command in fish.	If the
       program	file  is  located in one of the	PATH directories, you can just
       type the	name of	the program to use it. Otherwise the  whole  filename,
       including   the	 directory  (like  /home/me/code/checkers/checkers  or
       ../checkers) is required.

       Here is a list of some useful commands:

       o cd: Change the	current	directory

       o ls: List files	and directories

       o man: Display a	manual page

       o mv: Move (rename) files

       o cp: Copy files

       o open: Open files with the default application	associated  with  each
	 filetype

       o less: Display the contents of files

       Commands	 and arguments are separated by	the space character ' '. Every
       command ends with either	a newline (by pressing the return  key)	 or  a
       semicolon ;. Multiple commands can be written on	the same line by sepa-
       rating them with	semicolons.

       A switch	is a very common special type of argument. Switches almost al-
       ways start with one or more hyphens - and alter the way a command oper-
       ates. For example, the ls command usually lists the names of all	 files
       and  directories	 in  the  current  working  directory. By using	the -l
       switch, the behavior of ls is changed to	not only display the filename,
       but  also  the  size, permissions, owner, and modification time of each
       file.

       Switches	differ between commands	and are	usually	documented on  a  com-
       mand's  manual  page. There are some switches, however, that are	common
       to most commands. For example, --help will usually display a help text,
       --version  will	usually	display	the command version, and -i will often
       turn on interactive prompting before taking action.

   Terminology
       Here we define some of the terms	used on	this page and  throughout  the
       rest of the fish	documentation:

       o Argument: A parameter given to	a command.

       o Builtin:  A command that is implemented by the	shell. Builtins	are so
	 closely tied to the operation of the shell that it is	impossible  to
	 implement them	as external commands.

       o Command:  A  program  that the	shell can run, or more specifically an
	 external program that the shell runs in another process.

       o Function: A block of commands that can	be called as if	 they  were  a
	 single	command. By using functions, it	is possible to string together
	 multiple simple commands into one more	advanced command.

       o Job: A	running	pipeline or command.

       o Pipeline: A set of commands strung together so	that the output	of one
	 command is the	input of the next command.

       o Redirection:  An  operation  that  changes one	of the input or	output
	 streams associated with a job.

       o Switch	or Option: A special kind of argument that alters the behavior
	 of a command. A switch	almost always begins with one or two hyphens.

   Quotes
       Sometimes  features  like parameter expansion and character escapes get
       in the way. When	that happens, you can use quotes, either single	(') or
       double ("). Between single quotes, fish performs	no expansions. Between
       double quotes, fish only	performs variable expansion. No	other kind  of
       expansion  (including  brace  expansion or parameter expansion) is per-
       formed, and escape sequences (for  example,  \n)	 are  ignored.	Within
       quotes,	whitespace  is not used	to separate arguments, allowing	quoted
       arguments to contain spaces.

       The only	meaningful escape sequences in single quotes are \', which es-
       capes  a	 single	 quote and \\, which escapes the backslash symbol. The
       only meaningful escapes in double quotes	are \",	which escapes a	double
       quote,  \$,  which escapes a dollar character, \	followed by a newline,
       which deletes the backslash and the newline, and	\\, which escapes  the
       backslash symbol.

       Single  quotes  have  no	 special meaning within	double quotes and vice
       versa.

       Example:

	  rm "cumbersome filename.txt"

       removes the file	cumbersome filename.txt, while

	  rm cumbersome	filename.txt

       removes two files, cumbersome and filename.txt.

       Another example:

	  grep 'enabled)$' foo.txt

       searches	for lines ending in enabled) in	foo.txt	(the $ is  special  to
       grep: it	matches	the end	of the line).

   Escaping Characters
       Some  characters	 cannot	 be  written directly on the command line. For
       these characters, so-called escape sequences are	provided. These	are:

       o \a represents the alert character.

       o \e represents the escape character.

       o \f represents the form	feed character.

       o \n represents a newline character.

       o \r represents the carriage return character.

       o \t represents the tab character.

       o \v represents the vertical tab	character.

       o \xHH, where HH	is a hexadecimal number, represents the	ASCII  charac-
	 ter with the specified	value. For example, \x9	is the tab character.

       o \XHH,	where  HH  is  a hexadecimal number, represents	a byte of data
	 with the specified value. If you are using a multibyte	encoding, this
	 can  be used to enter invalid strings.	Only use this if you know what
	 you are doing.

       o \ooo, where ooo is an octal number, represents	 the  ASCII  character
	 with the specified value. For example,	\011 is	the tab	character.

       o \uXXXX,  where	 XXXX  is  a hexadecimal number, represents the	16-bit
	 Unicode character with	the specified value. For example, \u9  is  the
	 tab character.

       o \UXXXXXXXX,  where  XXXXXXXX  is a hexadecimal	number,	represents the
	 32-bit	Unicode	character with the specified value. For	 example,  \U9
	 is the	tab character.

       o \cX,  where X is a letter of the alphabet, represents the control se-
	 quence	generated by pressing the control key and the  specified  let-
	 ter. For example, \ci is the tab character

       Some  characters	 have  special	meaning	 to the	shell. For example, an
       apostrophe ' disables expansion (see Quotes).  To  tell	the  shell  to
       treat these characters literally, escape	them with a backslash. For ex-
       ample, the command:

	  echo \'hello world\'

       outputs 'hello world' (including	the apostrophes), while	the command:

	  echo 'hello world'

       outputs hello world (without the	apostrophes). In the former  case  the
       shell treats the	apostrophes as literal ' characters, while in the lat-
       ter case	it treats them as special expansion modifiers.

       The special characters and their	escape sequences are:

       o \  (backslash space) escapes the  space  character.  This  keeps  the
	 shell from splitting arguments	on the escaped space.

       o \$ escapes the	dollar character.

       o \\ escapes the	backslash character.

       o \* escapes the	star character.

       o \?  escapes the question mark character (this is not necessary	if the
	 qmark-noglob feature flag is enabled).

       o \~ escapes the	tilde character.

       o \# escapes the	hash character.

       o \( escapes the	left parenthesis character.

       o \) escapes the	right parenthesis character.

       o \{ escapes the	left curly bracket character.

       o \} escapes the	right curly bracket character.

       o \[ escapes the	left bracket character.

       o \] escapes the	right bracket character.

       o \< escapes the	less than character.

       o \> escapes the	more than character.

       o \^ escapes the	circumflex character.

       o \& escapes the	ampersand character.

       o \| escapes the	vertical bar character.

       o \; escapes the	semicolon character.

       o \" escapes the	quote character.

       o \' escapes the	apostrophe character.

   Input/Output	Redirection
       Most programs use three input/output (I/O) streams:

       o Standard input	(stdin)	for reading. Defaults to reading from the key-
	 board.

       o Standard  output  (stdout) for	writing	output.	Defaults to writing to
	 the screen.

       o Standard error	(stderr) for writing errors and	warnings. Defaults  to
	 writing to the	screen.

       Each  stream has	a number called	the file descriptor (FD): 0 for	stdin,
       1 for stdout, and 2 for stderr.

       The destination of a stream can be changed using	something called redi-
       rection.	 For  example, echo hello > output.txt,	redirects the standard
       output of the echo command to a text file.

       o To read standard input	from a file, use <SOURCE_FILE.

       o To write standard output to a file, use >DESTINATION.

       o To write standard error to a file, use	2>DESTINATION. [1]

       o To append standard output to a	file, use >>DESTINATION_FILE.

       o To append standard error to a file, use 2>>DESTINATION_FILE.

       o To not	overwrite ("clobber") an existing file,	use  >?DESTINATION  or
	 2>?DESTINATION. This is known as the "noclobber" redirection.

       DESTINATION can be one of the following:

       o A  filename.  The output will be written to the specified file. Often
	 >/dev/null to silence output by writing it to the special  "sinkhole"
	 file.

       o An  ampersand	(&)  followed by the number of another file descriptor
	 like &2 for standard error. The output	will be	written	to the	desti-
	 nation	descriptor.

       o An  ampersand followed	by a minus sign	(&-). The file descriptor will
	 be closed.

       As a convenience, the redirection &> can	be used	to direct both	stdout
       and stderr to the same destination. For example,	echo hello &> all_out-
       put.txt redirects both stdout and stderr	to  the	 file  all_output.txt.
       This is equivalent to echo hello	> all_output.txt 2>&1.

       Any  arbitrary  file  descriptor	can used in a redirection by prefixing
       the redirection with the	FD number.

       o To redirect the input of descriptor N,	use N<DESTINATION.

       o To redirect the output	of descriptor N, use N>DESTINATION.

       o To append the output of descriptor  N	to  a  file,  use  N>>DESTINA-
	 TION_FILE.

       For  example,  echo  hello  2>  output.stderr writes the	standard error
       (file descriptor	2) to output.stderr.

       It is an	error to redirect a builtin, function, or block	to a file  de-
       scriptor	above 2. However this is supported for external	commands.

       [1]  Previous  versions of fish also allowed specifying this as ^DESTI-
	    NATION, but	that made another character special so it  was	depre-
	    cated and will be removed in the future. See feature flags.

   Piping
       Another way to redirect streams is a pipe. A pipe connects streams with
       each other. Usually the standard	output of  one	command	 is  connected
       with the	standard input of another. This	is done	by separating commands
       with the	pipe character |. For example:

	  cat foo.txt |	head

       The command cat foo.txt sends the contents of foo.txt to	 stdout.  This
       output  is  provided  as	 input	for the	head program, which prints the
       first 10	lines of its input.

       It is possible to pipe a	different output file descriptor by prepending
       its FD number and the output redirect symbol to the pipe. For example:

	  make fish 2>|	less

       will attempt to build fish, and any errors will be shown	using the less
       pager. [2]

       As a convenience, the pipe &| redirects both stdout and stderr  to  the
       same process. This is different from bash, which	uses |&.

       [2]  A  "pager" here is a program that takes output and "paginates" it.
	    less doesn't just do pages,	it allows  arbitrary  scrolling	 (even
	    back!).

   Job control
       When  you start a job in	fish, fish itself will pause, and give control
       of the terminal to the program just started.  Sometimes,	 you  want  to
       continue	using the commandline, and have	the job	run in the background.
       To create a background job, append an & (ampersand)  to	your  command.
       This  will  tell	fish to	run the	job in the background. Background jobs
       are very	useful when running programs that have a graphical user	inter-
       face.

       Example:

	  emacs	&

       will  start  the	emacs text editor in the background. fg	can be used to
       bring it	into the foreground again when needed.

       Most programs allow you to suspend the program's	execution  and	return
       control	to  fish  by pressing Control+Z	(also referred to as ^Z). Once
       back at the fish	commandline, you can start other programs and do  any-
       thing  you want.	If you then want you can go back to the	suspended com-
       mand by using the fg (foreground) command.

       If you instead want to put a suspended job into the background, use the
       bg command.

       To  get	a listing of all currently started jobs, use the jobs command.
       These listed jobs can be	removed	with the disown	command.

       At the moment, functions	cannot be started in the background. Functions
       that are	stopped	and then restarted in the background using the bg com-
       mand will not execute correctly.

   Functions
       Functions are programs written in the fish syntax. They group  together
       various commands	and their arguments using a single name.

       For example, here's a simple function to	list directories:

	  function ll
	      ls -l $argv
	  end

       The first line tells fish to define a function by the name of ll, so it
       can be used by simply writing ll	on the commandline.  The  second  line
       tells fish that the command ls -l $argv should be called	when ll	is in-
       voked. $argv is a list variable,	which always  contains	all  arguments
       sent  to	the function. In the example above, these are simply passed on
       to the ls command. The end on the third line ends the definition.

       Calling this as ll /tmp/	will end up running ls -l  /tmp/,  which  will
       list the	contents of /tmp.

       This is a kind of function known	as a wrapper or	"alias".

       Fish's  prompt is also defined in a function, called fish_prompt. It is
       run when	the prompt is about to be displayed and	its output  forms  the
       prompt:

	  function fish_prompt
	      #	A simple prompt. Displays the current directory
	      #	(which fish stores in the $PWD variable)
	      #	and then a user	symbol - a 'ao'	for a normal user and a	'#' for	root.
	      set -l user_char 'ao'
	      if fish_is_root_user
		  set user_char	'#'
	      end

	      echo (set_color yellow)$PWD (set_color purple)$user_char
	  end

       To  edit	 a  function, you can use funced, and to save a	function func-
       save. This will store it	in a function file  that  fish	will  autoload
       when needed.

       The  functions  builtin	can  show a function's current definition (and
       type will also do if given a function).

       For more	information on functions, see the documentation	for the	 func-
       tion builtin.

   Defining aliases
       One  of the most	common uses for	functions is to	slightly alter the be-
       havior of an already existing command. For example, one might  want  to
       redefine	 the  ls  command to display colors. The switch	for turning on
       colors on GNU systems is	--color=auto. An alias,	or wrapper, around  ls
       might look like this:

	  function ls
	      command ls --color=auto $argv
	  end

       There are a few important things	that need to be	noted about aliases:

       o Always	 take care to add the $argv variable to	the list of parameters
	 to the	wrapped	command. This makes sure that if  the  user  specifies
	 any  additional parameters to the function, they are passed on	to the
	 underlying command.

       o If the	alias has the same name	as the aliased command,	 you  need  to
	 prefix	 the  call  to	the program with command to tell fish that the
	 function should not call itself, but rather a command with  the  same
	 name.	If  you	 forget	to do so, the function would call itself until
	 the end of time. Usually fish is smart	enough to figure this out  and
	 will refrain from doing so (which is hopefully	in your	interest).

       o Autoloading  isn't  applicable	 to aliases. Since, by definition, the
	 function is created at	the time the alias command  is	executed.  You
	 cannot	autoload aliases.

       To  easily  create  a function of this form, you	can use	the alias com-
       mand. Unlike other shells, this just makes functions - fish has no sep-
       arate  concept of an "alias", we	just use the word for a	function wrap-
       per like	this.

       For an alternative, try abbreviations. These are	 words	that  are  ex-
       panded  while  you  type,  instead of being actual functions inside the
       shell.

   Autoloading functions
       Functions can be	defined	on the commandline or in a configuration file,
       but they	can also be automatically loaded. This has some	advantages:

       o An autoloaded function	becomes	available automatically	to all running
	 shells.

       o If the	function definition is changed,	all running shells will	 auto-
	 matically reload the altered version, after a while.

       o Startup time and memory usage is improved, etc.

       When fish needs to load a function, it searches through any directories
       in the list variable $fish_function_path	for a file with	 a  name  con-
       sisting of the name of the function plus	the suffix .fish and loads the
       first it	finds.

       For example if you try to execute something called banana, fish will go
       through	all  directories  in  $fish_function_path  looking  for	a file
       called banana.fish and load the first one it finds.

       By default $fish_function_path contains the following:

       o A directory for users to keep their own  functions,  usually  ~/.con-
	 fig/fish/functions  (controlled  by  the  XDG_CONFIG_HOME environment
	 variable).

       o A directory for functions  for	 all  users  on	 the  system,  usually
	 /etc/fish/functions (really $__fish_sysconfdir/functions).

       o Directories  for other	software to put	their own functions. These are
	 in the	directories in the XDG_DATA_DIRS environment  variable,	 in  a
	 subdirectory  called  fish/vendor_functions.d.	The default is usually
	 /usr/share/fish/vendor_functions.d   and   /usr/local/share/fish/ven-
	 dor_functions.d.

       o The	functions    shipped   with   fish,   usually	installed   in
	 /usr/share/fish/functions (really $__fish_data_dir/functions).

       If  you	are  unsure,  your  functions  probably	 belong	  in   ~/.con-
       fig/fish/functions.

       As  we've  explained,  autoload files are loaded	by name, so, while you
       can put multiple	functions into one file, the file will only be	loaded
       automatically once you try to execute the one that shares the name.

       Autoloading  also won't work for	event handlers,	since fish cannot know
       that a function is supposed to be executed when an event	occurs when it
       hasn't yet loaded the function. See the event handlers section for more
       information.

       If a file of the	right name doesn't define the function,	fish will  not
       read  other  autoload  files, instead it	will go	on to try builtins and
       finally commands. This allows  masking  a  function  defined  later  in
       $fish_function_path,  e.g. if your administrator	has put	something into
       /etc/fish/functions that	you want to skip.

       If you are developing another program and want to  install  fish	 func-
       tions for it, install them to the "vendor" functions directory. As this
       path varies from	system to system, you can use pkgconfig	to discover it
       with  the  output  of pkg-config	--variable functionsdir	fish. Your in-
       stallation system should	support	a custom path to override the  pkgcon-
       fig path, as other distributors may need	to alter it easily.

   Comments
       Anything	 after	a # until the end of the line is a comment. That means
       it's purely for the reader's benefit, fish ignores it.

       This is useful to explain what and why you are doing something:

	  function ls
	      #	The function is	called ls,
	      #	so we have to explicitly call `command ls` to avoid calling ourselves.
	      command ls --color=auto $argv
	  end

       There are no multiline comments.	If you want to	make  a	 comment  span
       multiple	lines, simply start each line with a #.

       Comments	can also appear	after a	line like so:

	  set -gx EDITOR emacs # I don't like vim.

   Conditions
       Fish has	some builtins that let you execute commands only if a specific
       criterion is met: if, switch, and and or, and also the  familiar	 &&/||
       syntax.

       The  switch  command  is	used to	execute	one of possibly	many blocks of
       commands	depending on the value of a string. See	the documentation  for
       switch for more information.

       The  other conditionals use the exit status of a	command	to decide if a
       command or a block of commands should be	executed.

       Unlike programming languages you	might know, if doesn't take  a	condi-
       tion,  it  takes	 a command. If that command returned a successful exit
       status (that's 0), the if branch	is taken, otherwise the	else branch.

       Some examples:

	  # Just see if	the file contains the string "fish" anywhere.
	  # This executes the `grep` command, which searches for a string,
	  # and	if it finds it returns a status	of 0.
	  # The	`-q` switch stops it from printing any matches.
	  if grep -q fish myanimals
	      echo "You	have fish!"
	  else
	      echo "You	don't have fish!"
	  end

	  # $XDG_CONFIG_HOME is	a standard place to store configuration.
	  # If it's not	set applications should	use ~/.config.
	  set -q XDG_CONFIG_HOME; and set -l configdir $XDG_CONFIG_HOME
	  or set -l configdir ~/.config

       For more, see the documentation for the builtins	 or  the  Conditionals
       section of the tutorial.

   Loops and blocks
       Like  most  programming	language, fish also has	the familiar while and
       for loops.

       while works like	a repeated if:

	  while	true
	      echo Still running
	      sleep 1
	  end

       will print "Still running" once a second. You can abort it with ctrl-c.

       for loops work like in  other  shells,  which  is  more	like  python's
       for-loops than e.g. C's:

	  for file in *
	      echo file: $file
	  end

       will print each file in the current directory. The part after the in is
       just a list of arguments, so you	can use	any expansions there:

	  set moreanimals bird fox
	  for animal in	{cat,}fish dog $moreanimals
	     echo I like the $animal
	  end

       If you need a list of numbers, you can use the seq  command  to	create
       one:

	  for i	in (seq	1 5)
	      echo $i
	  end

       break  is available to break out	of a loop, and continue	to jump	to the
       next iteration.

       Input and output	redirections (including	pipes) can also	be applied  to
       loops:

	  while	read -l	line
	      echo line: $line
	  end <	file

       In addition there's a begin block that just groups commands together so
       you can redirect	to a block or use a new	 variable  scope  without  any
       repetition:

	  begin
	     set -l foo	bar # this variable will only be available in this block!
	  end

   Parameter expansion
       When  fish  is  given  a	 commandline, it expands the parameters	before
       sending them to the command. There are multiple different kinds of  ex-
       pansions:

       o Wildcards, to create filenames	from patterns

       o Variable expansion, to	use the	value of a variable

       o Command substitution, to use the output of another command

       o Brace	expansion,  to	write  lists with common pre- or suffixes in a
	 shorter way

       o Tilde expansion, to turn the ~	at the beginning  of  paths  into  the
	 path to the home directory

       Parameter expansion is limited to 524288	items. There is	a limit	to how
       many arguments the operating system allows for any command, and	524288
       is far above it.	This is	a measure to stop the shell from hanging doing
       useless computation.

   Wildcards ("Globbing")
       When a parameter	includes an unquoted * star (or	 "asterisk")  or  a  ?
       question	mark, fish uses	it as a	wildcard to match files.

       o *  matches  any number	of characters (including zero) in a file name,
	 not including /.

       o ** matches any	number of characters (including	zero),	and  also  de-
	 scends	 into  subdirectories. If ** is	a segment by itself, that seg-
	 ment may match	zero times, for	compatibility with other shells.

       o ? can match any single	character except /. This is deprecated and can
	 be  disabled  via the qmark-noglob feature flag, so ? will just be an
	 ordinary character.

       Other shells, such as zsh, have a much richer glob syntax,  like	 **(.)
       to  only	match regular files. Fish does not. Instead of reinventing the
       wheel, use programs like	find to	look for files.	For example:

	  function ff --description 'Like ** but only returns plain files.'
	      #	This also ignores .git directories.
	      find . \(	-name .git -type d -prune \) -o	-type f	| \
		  sed -n -e '/^\.\/\.git$/n' -e	's/^\.\///p'
	  end

       You would then use it in	place of ** like this, my_prog (ff),  to  pass
       only regular files in or	below $PWD to my_prog. [3]

       Wildcard	 matches  are  sorted case insensitively. When sorting matches
       containing numbers, they	are naturally sorted, so that the strings  '1'
       '5' and '12' would be sorted like 1, 5, 12.

       Hidden files (where the name begins with	a dot) are not considered when
       wildcarding unless the wildcard string has a dot	in that	place.

       Examples:

       o a* matches any	files beginning	with an	'a' in the current directory.

       o ??? matches any file in the current directory whose name  is  exactly
	 three characters long.

       o ** matches any	files and directories in the current directory and all
	 of its	subdirectories.

       o ~/.* matches all hidden files (also known as "dotfiles") and directo-
	 ries in your home directory.

       For  most commands, if any wildcard fails to expand, the	command	is not
       executed, $status is set	to nonzero, and	a warning is printed. This be-
       havior is like what bash	does with shopt	-s failglob. There are exactly
       4 exceptions, namely set, overriding variables in overrides, count  and
       for.  Their globs will instead expand to	zero arguments (so the command
       won't see them at all), like with shopt -s nullglob in bash.

       Examples:

	  # List the .foo files, or warns if there aren't any.
	  ls *.foo

	  # List the .foo files, if any.
	  set foos *.foo
	  if count $foos >/dev/null
	      ls $foos
	  end

       [3]  Technically, unix allows filenames with newlines, and this	splits
	    the	find output on newlines. If you	want to	avoid that, use	find's
	    -print0 option and string split0.

   Variable expansion
       One of the most important expansions in fish is	the  "variable	expan-
       sion".  This  is	the replacing of a dollar sign ($) followed by a vari-
       able name with the _value_ of that variable. For	more  on  shell	 vari-
       ables, read the Shell variables section.

       In the simplest case, this is just something like:

	  echo $HOME

       which  will  replace $HOME with the home	directory of the current user,
       and pass	it to echo, which will then print it.

       Some variables like $HOME are already set because fish sets them	by de-
       fault  or  because  fish's  parent  process passed them to fish when it
       started it. You can define your own variables by	setting	them with set:

	  set my_directory /home/cooluser/mystuff
	  ls $my_directory
	  # shows the contents of /home/cooluser/mystuff

       For more	on how setting variables works,	see Shell  variables  and  the
       following sections.

       Sometimes a variable has	no value because it is undefined or empty, and
       it expands to nothing:

	  echo $nonexistentvariable
	  # Prints no output.

       To separate a variable name from	 text  you  can	 encase	 the  variable
       within double-quotes or braces:

	  set WORD cat
	  echo The plural of $WORD is "$WORD"s
	  # Prints "The	plural of cat is cats" because $WORD is	set to "cat".
	  echo The plural of $WORD is {$WORD}s
	  # ditto

       Without the quotes or braces, fish will try to expand a variable	called
       $WORDs, which may not exist.

       The latter syntax {$WORD} is a special case of brace expansion.

       If $WORD	here is	undefined or an	empty list, the	"s"  is	 not  printed.
       However,	 it  is	 printed  if $WORD is the empty	string (like after set
       WORD "").

       Unlike all the other expansions,	variable  expansion  also  happens  in
       double  quoted  strings.	Inside double quotes ("these"),	variables will
       always expand to	exactly	one argument. If they are empty	or  undefined,
       it  will	 result	 in an empty string. If	they have one element, they'll
       expand to that element. If they have more than that, the	elements  will
       be joined with spaces, unless the variable is a path variable - in that
       case it will use	a colon	(:) instead [4].

       Outside of double quotes, variables will	expand to as many arguments as
       they  have elements. That means an empty	list will expand to nothing, a
       variable	with one element will expand to	that element, and  a  variable
       with  multiple  elements	 will  expand  to each of those	elements sepa-
       rately.

       If a variable expands to	nothing, it will cancel	out any	other  strings
       attached	to it. See the cartesian product section for more information.

       The  $  symbol  can also	be used	multiple times,	as a kind of "derefer-
       ence" operator (the * in	C or C++), like	in the following code:

	  set foo a b c
	  set a	10; set	b 20; set c 30
	  for i	in (seq	(count $$foo))
	      echo $$foo[$i]
	  end

	  # Output is:
	  # 10
	  # 20
	  # 30

       $$foo[$i] is "the value of the variable named by	$foo[$i].

       When using this feature together	with list brackets, the	brackets  will
       be  used	 from  the  inside out.	$$foo[5] will use the fifth element of
       $foo as a variable name,	instead	of giving the fifth element of all the
       variables   $foo	  refers  to.  That  would  instead  be	 expressed  as
       $$foo[1][5] (take the first element of $foo, use	it as a	variable name,
       then give the fifth element of that).

       [4]  Unlike  bash  or  zsh, which will join with	the first character of
	    $IFS (which	usually	is space).

   Command substitution
       The output of a command (or an entire pipeline) can be used as the  ar-
       guments to another command.

       When  you  write	 a command in parenthesis like outercommand (innercom-
       mand), the innercommand will be executed	 first.	 Its  output  will  be
       taken and each line given as a separate argument	to outercommand, which
       will then be executed. [5]

       If the output is	piped to string	split or string	 split0	 as  the  last
       step, those splits are used as they appear instead of splitting lines.

       The  exit  status  of the last run command substitution is available in
       the status variable if the substitution happens in the context of a set
       command (so if set -l (something) checks	if something returned true).

       Only  part of the output	can be used, see index range expansion for de-
       tails.

       Fish has	a default limit	of 100 MiB on the data it will read in a  com-
       mand  sustitution. If that limit	is reached the command (all of it, not
       just the	command	substitution - the outer command won't be executed  at
       all)  fails and $status is set to 122. This is so command substitutions
       can't cause the system to go out	of memory, because typically your  op-
       erating	system has a much lower	limit, so reading more than that would
       be  useless  and	 harmful.  This	 limit	can  be	 adjusted   with   the
       fish_read_limit	variable (0 meaning no limit). This limit also affects
       the read	command.

       Examples:

	  # Outputs 'image.png'.
	  echo (basename image.jpg .jpg).png

	  # Convert all	JPEG files in the current directory to the
	  # PNG	format using the 'convert' program.
	  for i	in *.jpg; convert $i (basename $i .jpg).png; end

	  # Set	the ``data`` variable to the contents of 'data.txt'
	  # without splitting it into a	list.
	  begin; set -l	IFS; set data (cat data.txt); end

	  # Set	``$data`` to the contents of data, splitting on	NUL-bytes.
	  set data (cat	data | string split0)

       Sometimes you want to pass the output of	a command to  another  command
       that  only  accepts  files. If it's just	one file, you can usually just
       pass it via a pipe, like:

	  grep fish myanimallist1 | wc -l

       but if you need multiple	or the command doesn't read from standard  in-
       put,  "process substitution" is useful. Other shells [6]	allow this via
       foo <(bar) <(baz), and fish uses	the psub command:

	  # Compare just the lines containing "fish" in	two files:
	  diff -u (grep	fish myanimallist1 | psub) (grep fish myanimallist2 | psub)

       This creates a temporary	file, stores the output	of the command in that
       file and	prints the filename, so	it is given to the outer command.

       [5]  Setting  $IFS to empty will	disable	line splitting.	This is	depre-
	    cated, use string split instead.

       [6]  Bash and Zsh at least, though it is	a POSIX	extension

   Brace expansion
       Curly braces can	be used	to write comma-separated lists.	They  will  be
       expanded	with each element becoming a new parameter, with the surround-
       ing string attached. This is useful to save on typing, and to  separate
       a variable name from surrounding	text.

       Examples:

	  > echo input.{c,h,txt}
	  input.c input.h input.txt

	  # Move all files with	the suffix '.c'	or '.h'	to the subdirectory src.
	  > mv *.{c,h} src/

	  # Make a copy	of `file` at `file.bak`.
	  > cp file{,.bak}

	  > set	-l dogs	hot cool cute "good "
	  > echo {$dogs}dog
	  hotdog cooldog cutedog good dog

       If there	is no "," or variable expansion	between	the curly braces, they
       will not	be expanded:

	  # This {} isn't special
	  > echo foo-{}
	  foo-{}
	  # This passes	"HEAD@{2}" to git
	  > git	reset --hard HEAD@{2}
	  > echo {{a,b}}
	  {a} {b} # because the	inner brace pair is expanded, but the outer isn't.

       If after	expansion there	is nothing between the	braces,	 the  argument
       will be removed (see the	cartesian product section):

	  > echo foo-{$undefinedvar}
	  # Output is an empty line, just like a bare `echo`.

       If there	is nothing between a brace and a comma or two commas, it's in-
       terpreted as an empty element:

	  > echo {,,/usr}/bin
	  /bin /bin /usr/bin

       To use a	"," as an element, quote or escape it.

   Combining lists (Cartesian Product)
       When lists are expanded with other parts	attached,  they	 are  expanded
       with these parts	still attached.	Even if	two lists are attached to each
       other, they are expanded	in all combinations. This is  referred	to  as
       the  cartesian  product (like in	mathematics), and works	basically like
       brace expansion.

       Examples:

	  # Brace expansion is the most	familiar:
	  # All	elements in the	brace combine with the parts outside of	the braces
	  >_ echo {good,bad}" apples"
	  good apples bad apples

	  # The	same thing happens with	variable expansion.
	  >_ set -l a x	y z
	  >_ set -l b 1	2 3

	  # $a is {x,y,z}, $b is {1,2,3},
	  # so this is `echo {x,y,z}{1,2,3}`
	  >_ echo $a$b
	  x1 y1	z1 x2 y2 z2 x3 y3 z3

	  # Same thing if something is between the lists
	  >_ echo $a"-"$b
	  x-1 y-1 z-1 x-2 y-2 z-2 x-3 y-3 z-3

	  # Or a brace expansion and a variable
	  >_ echo {x,y,z}$b
	  x1 y1	z1 x2 y2 z2 x3 y3 z3

	  # A combined brace-variable expansion
	  >_ echo {$b}word
	  1word	2word 3word

	  # Special case: If $c	has no elements, this expands to nothing
	  >_ echo {$c}word
	  # Output is an empty line

       Sometimes this may be unwanted, especially that	tokens	can  disappear
       after  expansion.  In  those cases, you should double-quote variables -
       echo "$c"word.

       This also happens after command substitution. To	 avoid	tokens	disap-
       pearing	there,	make  the  inner command return	a trailing newline, or
       store the output	in a variable and double-quote it.

       E.g.

	  >_ set b 1 2 3
	  >_ echo (echo	x)$b
	  x1 x2	x3
	  >_ echo (printf '%s' '')banana
	  # the	printf prints nothing, so this is nothing times	"banana",
	  # which is nothing.
	  >_ echo (printf '%s\n' '')banana
	  # the	printf prints a	newline,
	  # so the command substitution	expands	to an empty string,
	  # so this is `''banana`
	  banana

       This can	be quite useful. For example, if you want to  go  through  all
       the files in all	the directories	in $PATH, use:

	  for file in $PATH/*

       Because	$PATH  is a list, this expands to all the files	in all the di-
       rectories in it.	And if there are no directories	in  $PATH,  the	 right
       answer here is to expand	to no files.

   Index range expansion
       Sometimes  it's necessary to access only	some of	the elements of	a list
       (all fish variables are lists), or some of the lines a command  substi-
       tution  outputs.	 Both are possible in fish by writing a	set of indices
       in brackets, like:

	  # Make $var a	list of	four elements
	  set var one two three	four
	  # Print the second:
	  echo $var[2]
	  # prints "two"
	  # or print the first three:
	  echo $var[1..3]
	  # prints "one	two three"

       In index	brackets, fish understands ranges written like a..b  ('a'  and
       'b' being indices). They	are expanded into a sequence of	indices	from a
       to b (so	a a+1 a+2 ... b), going	up if b	is larger and going down if  a
       is  larger. Negative indices can	also be	used - they are	taken from the
       end of the list,	so -1 is the last element, and -2 the one  before  it.
       If an index doesn't exist the range is clamped to the next possible in-
       dex.

       If a list has 5 elements	the indices go from 1 to  5,  so  a  range  of
       2..16 will only go from element 2 to element 5.

       If  the end is negative the range always	goes up, so 2..-2 will go from
       element 2 to 4, and 2..-16 won't	go anywhere because there is no	way to
       go  from	 the second element to one that	doesn't	exist, while going up.
       If the start is negative	the range always goes down, so -2..1  will  go
       from  element  4	to 1, and -16..2 won't go anywhere because there is no
       way to go from an element that doesn't exist  to	 the  second  element,
       while going down.

       A  missing  starting index in a range defaults to 1. This is allowed if
       the range is the	first index expression of the sequence.	 Similarly,  a
       missing	ending	index,	defaulting to -1 is allowed for	the last index
       range in	the sequence.

       Multiple	ranges are also	possible, separated with a space.

       Some examples:

	  echo (seq 10)[1 2 3]
	  # Prints: 1 2	3

	  # Limit the command substitution output
	  echo (seq 10)[2..5]
	  # Uses elements from 2 to 5
	  # Output is: 2 3 4 5

	  echo (seq 10)[7..]
	  # Prints: 7 8	9 10

	  # Use	overlapping ranges:
	  echo (seq 10)[2..5 1..3]
	  # Takes elements from	2 to 5 and then	elements from 1	to 3
	  # Output is: 2 3 4 5 1 2 3

	  # Reverse output
	  echo (seq 10)[-1..1]
	  # Uses elements from the last	output line to
	  # the	first one in reverse direction
	  # Output is: 10 9 8 7	6 5 4 3	2 1

	  # The	command	substitution has only one line,
	  # so these will result in empty output:
	  echo (echo one)[2..-1]
	  echo (echo one)[-3..1]

       The same	works when setting or expanding	variables:

	  # Reverse path variable
	  set PATH $PATH[-1..1]
	  # or
	  set PATH[-1..1] $PATH

	  # Use	only n last items of the PATH
	  set n	-3
	  echo $PATH[$n..-1]

       Variables can be	used as	indices	for expansion of variables, like so:

	  set index 2
	  set letters a	b c d
	  echo $letters[$index]	# returns 'b'

       However using variables as indices for  command	substitution  is  cur-
       rently not supported, so:

	  echo (seq 5)[$index] # This won't work

	  set sequence (seq 5) # It needs to be	written	on two lines like this.
	  echo $sequence[$index] # returns '2'

       When  using  indirect  variable expansion with multiple $ ($$name), you
       have to give all	indices	up to the variable you want to slice:

	  > set	-l list	1 2 3 4	5
	  > set	-l name	list
	  > echo $$name[1]
	  1 2 3	4 5
	  > echo $$name[1..-1][1..3] # or $$name[1][1..3], since $name only has	one element.
	  1 2 3

   Home	directory expansion
       The ~ (tilde) character at the beginning	of a parameter,	followed by  a
       username,  is expanded into the home directory of the specified user. A
       lone ~, or a ~ followed by a slash, is expanded into the	home directory
       of the process owner:

	  ls ~/Music # lists my	music directory

	  echo ~root # prints root's home directory, probably "/root"

   Combining different expansions
       All  of the above expansions can	be combined. If	several	expansions re-
       sult in more than one parameter,	all possible combinations are created.

       When combining multiple parameter expansions, expansions	are  performed
       in the following	order:

       o Command substitutions

       o Variable expansions

       o Bracket expansion

       o Wildcard expansion

       Expansions  are performed from right to left, nested bracket expansions
       are performed from the inside and out.

       Example:

       If the current directory	contains the files 'foo' and 'bar',  the  com-
       mand echo a(ls){1,2,3} will output abar1	abar2 abar3 afoo1 afoo2	afoo3.

   Shell variables
       Variables  are  a way to	save data and pass it around. They can be used
       just by the shell, or they can be "exported", so	that  a	 copy  of  the
       variable	 is available to any external command the shell	starts.	An ex-
       ported variable is referred to as an "environment variable".

       To set a	variable value,	use the	set command. A variable	name  can  not
       be  empty and can contain only letters, digits, and underscores.	It may
       begin and end with any of those characters.

       Example:

       To set the variable smurf_color to the value blue, use the command  set
       smurf_color blue.

       After  a	 variable has been set,	you can	use the	value of a variable in
       the shell through variable expansion.

       Example:

	  set smurf_color blue
	  echo Smurfs are usually $smurf_color
	  set pants_color red
	  echo Papa smurf, who is $smurf_color,	wears $pants_color pants

       So you set a variable with set, and use it with a $ and the name.

   Variable scope
       There are three kinds of	variables in fish: universal, global and local
       variables.

       o Universal  variables  are  shared between all fish sessions a user is
	 running on one	computer.

       o Global	variables are specific to the current fish session,  and  will
	 never be erased unless	explicitly requested by	using set -e.

       o Local variables are specific to the current fish session, and associ-
	 ated with a specific block of commands, and automatically erased when
	 a  specific  block goes out of	scope. A block of commands is a	series
	 of commands that begins with one of the commands  for,	 while	,  if,
	 function, begin or switch, and	ends with the command end.

       Variables  can  be explicitly set to be universal with the -U or	--uni-
       versal switch, global with the -g or --global switch, or	local with the
       -l  or  --local	switch.	 The scoping rules when	creating or updating a
       variable	are:

       o When a	scope is explicitly given, it will be used. If a  variable  of
	 the  same name	exists in a different scope, that variable will	not be
	 changed.

       o When no scope is given, but a variable	of that	name exists, the vari-
	 able  of  the	smallest scope will be modified. The scope will	not be
	 changed.

       o As a special case, when no scope is given and no  variable  has  been
	 defined  the  variable	will belong to the scope of the	currently exe-
	 cuting	function. This is different from the --local flag, which would
	 make the variable local to the	current	block.

       There  can  be many variables with the same name, but different scopes.
       When you	use a variable,	the smallest scoped variable of	that name will
       be  used.  If  a	 local variable	exists,	it will	be used	instead	of the
       global or universal variable of the same	name.

       Example:

       There are a few possible	uses for different scopes.

       Typically inside	funcions you should use	local scope:

	  function something
	      set -l file /path/to/my/file
	      if not test -e "$file"
		  set file /path/to/my/otherfile
	      end
	  end

       If you want to set something in config.fish,  or	 set  something	 in  a
       function	 and  have  it	available  for the rest	of the session,	global
       scope is	a good choice:

	  # Don't shorten the working directory	in the prompt
	  set -g fish_prompt_pwd_dir_length 0

	  # Set	my preferred cursor style:
	  function setcursors
	     set -g fish_cursor_default	block
	     set -g fish_cursor_insert line
	     set -g fish_cursor_visual underscore
	  end

	  # Set	my language
	  set -gx LANG de_DE.UTF-8

       If you want to set some personal	customization, universal variables are
       nice:

	  # Typically you'd run	this interactively, fish takes care of keeping it.
	  set -U fish_color_autosuggestion 555

       Here is an example of local vs function-scoped variables:

	  begin
	      #	This is	a nice local scope where all variables will die
	      set -l pirate 'There be treasure in them thar hills'
	      set captain Space, the final frontier
	  end

	  echo $pirate
	  # This will not output anything, since the pirate was	local
	  echo $captain
	  # This will output the good Captain's	speech since $captain had function-scope.

   Overriding variables	for a single command
       If  you	want  to override a variable for a single command, you can use
       "var=val" statements before the command:

	  # Call git status on another directory
	  # (can also be done via `git -C somerepo status`)
	  GIT_DIR=somerepo git status

       Unlike other shells, fish will first set	the variable and then  perform
       other expansions	on the line, so:

	  set foo banana
	  foo=gagaga echo $foo # prints	gagaga,	while in other shells it might print "banana"

       Multiple	elements can be	given in a brace expansion:

	  # Call bash with a reasonable	default	path.
	  PATH={/usr,}/{s,}bin bash

       Or with a glob:

	  # Run	vlc on all mp3 files in	the current directory
	  # If no file exists it will still be run with	no arguments
	  mp3s=*.mp3 vlc $mp3s

       Unlike other shells, this does not inhibit any lookup (aliases or simi-
       lar). Calling a command after setting a variable	override  will	result
       in the exact same command being run.

       This syntax is supported	since fish 3.1.

   More	on universal variables
       Universal  variables  are  variables  that  are	shared between all the
       user's fish sessions on the computer. Fish stores many of its  configu-
       ration  options	as  universal  variables.  This	means that in order to
       change fish settings, all you have to do	is change the  variable	 value
       once,  and  it will be automatically updated for	all sessions, and pre-
       served across computer reboots and login/logout.

       To see universal	variables in action, start two fish sessions  side  by
       side, and issue the following command in	one of them set	fish_color_cwd
       blue. Since fish_color_cwd is a universal variable, the	color  of  the
       current	working	 directory listing in the prompt will instantly	change
       to blue on both terminals.

       Universal variables are stored in the file .config/fish/fish_variables.
       Do  not edit this file directly,	as your	edits may be overwritten. Edit
       the variables through fish scripts or by	using fish  interactively  in-
       stead.

       Do  not	append	to  universal  variables in config.fish, because these
       variables will then get longer with each	new shell  instance.  Instead,
       simply set them once at the command line.

   Variable scope for functions
       When calling a function,	all current local variables temporarily	disap-
       pear. This shadowing of the local scope is needed  since	 the  variable
       namespace  would	 become	cluttered, making it very easy to accidentally
       overwrite variables from	another	function.

       For example:

	  function shiver
	      set phrase 'Shiver me timbers'
	  end

	  function avast
	      set --local phrase 'Avast, mateys'
	      #	Calling	the shiver function here can not
	      #	change any variables in	the local scope
	      shiver
	      echo $phrase
	  end
	  avast

	  # Outputs "Avast, mateys"

   Exporting variables
       Variables in fish can be	"exported", so they will be inherited  by  any
       commands	 started  by  fish. In particular, this	is necessary for vari-
       ables used to configure external	commands like $LESS  or	 $GOPATH,  but
       also  for  variables that contain general system	settings like $PATH or
       $LANGUAGE. If an	external command needs to know a variable, it needs to
       be exported.

       This  also applies to fish - when it starts up, it receives environment
       variables from its parent (usually the terminal). These	typically  in-
       clude system configuration like $PATH and locale	variables.

       Variables  can be explicitly set	to be exported with the	-x or --export
       switch, or not exported with the	-u or --unexport switch.  The  export-
       ing  rules  when	 setting a variable are	identical to the scoping rules
       for variables:

       o If a variable is explicitly set to either  be	exported  or  not  ex-
	 ported, that setting will be honored.

       o If  a	variable is not	explicitly set to be exported or not exported,
	 but has been previously defined, the previous exporting rule for  the
	 variable is kept.

       o Otherwise, by default,	the variable will not be exported.

       o If  a	variable  has local scope and is exported, any function	called
	 receives a copy of it,	so any changes it makes	to the variable	disap-
	 pear once the function	returns.

       o Global	 variables  are	 accessible  to	functions whether they are ex-
	 ported	or not.

       As a naming convention, exported	variables are in uppercase  and	 unex-
       ported variables	are in lowercase.

       For example:

	  set -gx ANDROID_HOME ~/.android # /opt/android-sdk
	  set -gx CDPATH . ~ (test -e ~/Videos;	and echo ~/Videos)
	  set -gx EDITOR emacs -nw
	  set -gx GOPATH ~/dev/go
	  set -gx GTK2_RC_FILES	"$XDG_CONFIG_HOME/gtk-2.0/gtkrc"
	  set -gx LESSHISTFILE "-"

       Note:  Exporting	 is not	a scope, but an	additional state. It typically
       makes sense to make exported variables global as	 well,	but  local-ex-
       ported variables	can be useful if you need something more specific than
       Overrides. They are copied to functions so  the	function  can't	 alter
       them outside, and still available to commands.

   Lists
       Fish  can  store	a list (or an "array" if you wish) of multiple strings
       inside of a variable:

	  > set	mylist first second third
	  > printf '%s\n' $mylist # prints each	element	on its own line
	  first
	  second
	  third

       To access one element of	a list,	use the	index of the element inside of
       square brackets,	like this:

	  echo $PATH[3]

       List indices start at 1 in fish,	not 0 like in other languages. This is
       because it requires less	subtracting of 1 and many  common  Unix	 tools
       like  seq work better with it (seq 5 prints 1 to	5, not 0 to 5).	An in-
       valid index is silently ignored resulting in  no	 value	(not  even  an
       empty string, just no argument at all).

       If  you	don't  use  any	brackets, all the elements of the list will be
       passed to the command as	separate items.	This  means  you  can  iterate
       over a list with	for:

	  for i	in $PATH
	      echo $i is in the	path
	  end

       This  goes  over	 every directory in $PATH separately and prints	a line
       saying it is in the path.

       To create a variable smurf, containing the items	blue and small,	simply
       write:

	  set smurf blue small

       It is also possible to set or erase individual elements of a list:

	  # Set	smurf to be a list with	the elements 'blue' and	'small'
	  set smurf blue small

	  # Change the second element of smurf to 'evil'
	  set smurf[2] evil

	  # Erase the first element
	  set -e smurf[1]

	  # Output 'evil'
	  echo $smurf

       If  you	specify	a negative index when expanding	or assigning to	a list
       variable, the index will	be taken from the end of the list.  For	 exam-
       ple, the	index -1 is the	last element of	the list:

	  > set	fruit apple orange banana
	  > echo $fruit[-1]
	  banana

	  > echo $fruit[-2..-1]
	  orange
	  banana

	  > echo $fruit[-1..1] # reverses the list
	  banana
	  orange
	  apple

       As  you	see, you can use a range of indices, see index range expansion
       for details.

       All lists are one-dimensional and can't contain other  lists,  although
       it  is possible to fake nested lists using dereferencing	- see variable
       expansion.

       When a list is exported as an environment variable, it is either	 space
       or colon	delimited, depending on	whether	it is a	path variable:

	  > set	-x smurf blue small
	  > set	-x smurf_PATH forest mushroom
	  > env	| grep smurf
	  smurf=blue small
	  smurf_PATH=forest:mushroom

       Fish  automatically  creates lists from all environment variables whose
       name ends in PATH (like $PATH, $CDPATH or $MANPATH), by splitting  them
       on colons. Other	variables are not automatically	split.

       Lists can be inspected with the count or	the contains commands:

	  count	$smurf
	  # 2

	  contains blue	$smurf
	  # key	found, exits with status 0

	  > contains -i	blue $smurf
	  1

       A  nice	thing about lists is that they are passed to commands one ele-
       ment as one argument, so	once you've set	your list, you can  just  pass
       it:

	  set -l grep_args -r "my string"
	  grep $grep_args . # will run the same	as `grep -r "my	string"` .

       Unlike  other shells, fish does not do "word splitting" - elements in a
       list stay as they are, even if they contain spaces or tabs.

   Argument Handling
       An important list is $argv, which contains the arguments	to a  function
       or script. For example:

	  function myfunction
	      echo $argv[1]
	      echo $argv[3]
	  end

       This function takes whatever arguments it gets and prints the first and
       third:

	  > myfunction first second third
	  first
	  third

	  > myfunction apple cucumber banana
	  apple
	  banana

       Commandline tools often get various options and	flags  and  positional
       arguments, and $argv would contain all of these.

       A  more	robust approach	to argument handling is	argparse, which	checks
       the defined options and puts them into various variables, leaving  only
       the positional arguments	in $argv. Here's a simple example:

	  function mybetterfunction
	      argparse h/help s/second -- $argv
	      or return	# exit if argparse failed because it found an option it	didn't recognize - it will print an error

	      #	If -h or --help	is given, we print a little help text and return
	      if set -q	_flag_help
		  echo "mybetterfunction [-h|--help] [-s|--second] [ARGUMENTS...]"
		  return 0
	      end

	      #	If -s or --second is given, we print the second	argument,
	      #	not the	first and third.
	      if set -q	_flag_second
		  echo $argv[2]
	      else
		  echo $argv[1]
		  echo $argv[3]
	      end
	  end

       The options will	be removed from	$argv, so $argv[2] is the second posi-
       tional argument now:

	  > mybetterfunction first -s second third
	  second

   PATH	variables
       Path variables are a special kind of variable used to support colon-de-
       limited	path  lists  including PATH, CDPATH, MANPATH, PYTHONPATH, etc.
       All variables that end in "PATH"	 (case-sensitive)  become  PATH	 vari-
       ables.

       PATH  variables	act as normal lists, except they are implicitly	joined
       and split on colons.

	  set MYPATH 1 2 3
	  echo "$MYPATH"
	  # 1:2:3
	  set MYPATH "$MYPATH:4:5"
	  echo $MYPATH
	  # 1 2	3 4 5
	  echo "$MYPATH"
	  # 1:2:3:4:5

       Variables can be	marked or unmarked as PATH variables  via  the	--path
       and --unpath options to set.

   Special variables
       You  can	 change	the settings of	fish by	changing the values of certain
       variables.

       o PATH, a list of directories in	which to search	for commands

       o CDPATH, a list	of directories in which	the cd builtin looks for a new
	 directory.

       o The locale variables LANG, LC_ALL, LC_COLLATE,	LC_CTYPE, LC_MESSAGES,
	 LC_MONETARY, LC_NUMERIC and LC_TIME set the language option  for  the
	 shell	and subprograms. See the section Locale	variables for more in-
	 formation.

       o A number of  variable	starting  with	the  prefixes  fish_color  and
	 fish_pager_color.  See	Variables for changing highlighting colors for
	 more information.

       o fish_ambiguous_width controls the computed width  of  ambiguous-width
	 characters.  This  should  be set to 1	if your	terminal renders these
	 characters as single-width (typical), or 2 if double-width.

       o fish_emoji_width controls whether fish	 assumes  emoji	 render	 as  2
	 cells	or  1  cell  wide. This	is necessary because the correct value
	 changed from 1	to 2 in	Unicode	9,  and	 some  terminals  may  not  be
	 aware.	 Set  this if you see graphical	glitching related to emoji (or
	 other "special" characters). It should	usually	be auto-detected.

       o FISH_DEBUG and	FISH_DEBUG_OUTPUT control what debug output fish  gen-
	 erates	 and  where  it	 puts  it,  analogous to the --debug and --de-
	 bug-output options. These  have  to  be  set  on  startup,  via  e.g.
	 FISH_DEBUG='reader*' FISH_DEBUG_OUTPUT=/tmp/fishlog fish.

       o fish_escape_delay_ms  sets  how long fish waits for another key after
	 seeing	an escape, to distinguish pressing the	escape	key  from  the
	 start	of  an escape sequence.	The default is 30ms. Increasing	it in-
	 creases the latency but allows	pressing escape	 instead  of  alt  for
	 alt+character	bindings. For more information,	see the	chapter	in the
	 bind documentation.

       o fish_greeting,	the greeting  message  printed	on  startup.  This  is
	 printed  by  a	 function  of the same name that can be	overridden for
	 more complicated changes (see funced

       o fish_handle_reflow, determines	whether	fish should try	to repaint the
	 commandline  when the terminal	resizes. In terminals that reflow text
	 this should be	disabled. Set it to 1 to enable, anything else to dis-
	 able.

       o fish_history,	the  current  history session name. If set, all	subse-
	 quent commands	within an interactive fish session will	be logged to a
	 separate  file	identified by the value	of the variable. If unset, the
	 default session name "fish" is	used. If set to	an empty string,  his-
	 tory is not saved to disk (but	is still available within the interac-
	 tive session).

       o fish_key_bindings, the	name of	the function that sets up the keyboard
	 shortcuts for the command-line	editor.

       o fish_trace,  if  set and not empty, will cause	fish to	print commands
	 before	they execute, similar to set -x	in bash. The trace is  printed
	 to the	path given by the --debug-output option	to fish	(stderr	by de-
	 fault).

       o fish_user_paths, a list of directories	that are  prepended  to	 PATH.
	 This can be a universal variable.

       o umask,	 the  current  file creation mask. The preferred way to	change
	 the umask variable is through the umask function. An attempt  to  set
	 umask to an invalid value will	always fail.

       o BROWSER,  your	 preferred  web	browser. If this variable is set, fish
	 will use the specified	browser	instead	of the system default  browser
	 to display the	fish documentation.

       Fish also provides additional information through the values of certain
       environment variables. Most of these variables are read-only and	 their
       value can't be changed with set.

       o _,  the  name of the currently	running	command	(though	this is	depre-
	 cated,	and the	use of status current-command is preferred).

       o argv, a list of arguments to the shell	or function. argv is only  de-
	 fined when inside a function call, or if fish was invoked with	a list
	 of arguments, like fish myscript.fish foo bar.	This variable  can  be
	 changed.

       o CMD_DURATION, the runtime of the last command in milliseconds.

       o COLUMNS  and  LINES,  the  current size of the	terminal in height and
	 width.	These values are only used by fish  if	the  operating	system
	 does  not report the size of the terminal. Both variables must	be set
	 in that case otherwise	a default of 80x24 will	be used. They are  up-
	 dated when the	window size changes.

       o fish_kill_signal, the signal that terminated the last foreground job,
	 or 0 if the job exited	normally.

       o fish_pid, the process ID (PID)	of the shell.

       o history, a list containing the	last commands that were	entered.

       o HOME, the user's home directory. This variable	can be changed.

       o hostname, the machine's hostname.

       o IFS, the internal field separator that	is  used  for  word  splitting
	 with  the  read  builtin.  Setting this to the	empty string will also
	 disable line splitting	in command substitution. This variable can  be
	 changed.

       o last_pid, the process ID (PID)	of the last background process.

       o PWD, the current working directory.

       o pipestatus, a list of exit statuses of	all processes that made	up the
	 last executed pipe. See exit status.

       o SHLVL,	the level of nesting of	shells.	Fish increments	this in	inter-
	 active	shells,	otherwise it simply passes it along.

       o status,  the  exit  status of the last	foreground job to exit.	If the
	 job was terminated through a signal, the exit status will be 128 plus
	 the signal number.

       o status_generation,  the  "generation"	count of $status. This will be
	 incremented only when the previous command produced an	explicit  sta-
	 tus. (For example, background jobs will not increment this).

       o USER, the current username. This variable can be changed.

       o version, the version of the currently running fish (also available as
	 FISH_VERSION for backward compatibility).

       o fish_killring,	list of	entries	in fish	kill ring.

       As a convention,	an uppercase name is usually used for  exported	 vari-
       ables,  while lowercase variables are not exported. (CMD_DURATION is an
       exception for historical	reasons). This rule is not enforced  by	 fish,
       but it is good coding practice to use casing to distinguish between ex-
       ported and unexported variables.

       Fish also uses some variables internally, their name  usually  starting
       with  __fish.  These  are internal and should not typically be modified
       directly.

   The status variable
       Whenever	a process exits, an exit status	is  returned  to  the  program
       that  started  it  (usually  the	shell).	This exit status is an integer
       number, which tells the calling application how the  execution  of  the
       command went. In	general, a zero	exit status means that the command ex-
       ecuted without problem, but a non-zero exit status means	there was some
       form of problem.

       Fish stores the exit status of the last process in the last job to exit
       in the status variable.

       If fish encounters a problem while  executing  a	 command,  the	status
       variable	may also be set	to a specific value:

       o 0  is generally the exit status of commands if	they successfully per-
	 formed	the requested operation.

       o 1 is generally	the exit status	of commands if they failed to  perform
	 the requested operation.

       o 121  is  generally  the exit status of	commands if they were supplied
	 with invalid arguments.

       o 123 means that	the command was	not executed because the command  name
	 contained invalid characters.

       o 124 means that	the command was	not executed because none of the wild-
	 cards in the command produced any matches.

       o 125 means that	while an executable with the specified	name  was  lo-
	 cated,	the operating system could not actually	execute	the command.

       o 126  means  that while	a file with the	specified name was located, it
	 was not executable.

       o 127 means that	no function, builtin or	command	with  the  given  name
	 could be located.

       If  a  process exits through a signal, the exit status will be 128 plus
       the number of the signal.

       The status can be negated with  not  (or	 !),  which  is	 useful	 in  a
       condition. This turns a status of 0 into	1 and any non-zero status into
       0.

       There is	also $pipestatus, which	is a list of all status	values of pro-
       cesses  in  a  pipe. One	difference is that not applies to $status, but
       not $pipestatus,	because	it loses information.

       For example:

	  not cat file | grep -q fish
	  echo status is: $status pipestatus is	$pipestatus

       Here $status reflects the status	of grep, which returns 0 if  it	 found
       something,  negated with	not (so	1 if it	found something, 0 otherwise).
       $pipestatus reflects the	status of cat (which returns non-zero for  ex-
       ample when it couldn't find the file) and grep, without the negation.

       So  if  both  cat and grep succeeded, $status would be 1	because	of the
       not, and	$pipestatus would be 0 and 0.

   Locale variables
       The "locale" of a program is its	set of language	and regional settings.
       In  UNIX, there are a few separate variables to control separate	things
       - LC_CTYPE defines the text encoding while  LC_TIME  defines  the  time
       format.

       The  locale  variables are: LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MES-
       SAGES,  LC_MONETARY, LC_NUMERIC and LC_TIME. These  variables  work  as
       follows:	 LC_ALL	 forces	all the	aspects	of the locale to the specified
       value. If LC_ALL	is set,	all other locale  variables  will  be  ignored
       (this  is  typically not	recommended!). The other LC_ variables set the
       specified aspect	of the locale information. LANG	is a  fallback	value,
       it will be used if none of the LC_ variables are	specified.

       The  most  common  way  to set the locale to use	a command like set -gx
       LANG en_GB.utf8,	which sets the current locale to be the	 English  lan-
       guage,  as  used	 in Great Britain, using the UTF-8 character set. That
       way any program that requires one setting differently can easily	 over-
       ride  just  that	 and  doesn't  have to resort to LC_ALL. For a list of
       available locales on your system, try locale -a.

       Because it needs	to handle output that might include multibyte  charac-
       ters (like e.g. emojis),	fish will try to set its own internal LC_CTYPE
       to one that is UTF8-capable even	if given an effective LC_CTYPE of  "C"
       (the  default). This prevents issues with e.g. filenames	given in auto-
       suggestions even	if the user started fish with LC_ALL=C.	To  turn  this
       handling	off, set fish_allow_singlebyte_locale to "1".

   Builtin commands
       Fish includes a number of commands in the shell directly. We call these
       "builtins". These include:

       o Builtins that manipulate the shell state - cd changes directory,  set
	 sets variables

       o Builtins  for dealing with data, like string for strings and math for
	 numbers, count	for counting lines or arguments

       o status	for asking about the shell's status

       o printf	and echo for creating output

       o test for checking conditions

       o argparse for parsing function arguments

       o source	to read	a script in the	current	shell (so changes to variables
	 stay) and eval	to execute a string as script

       o random	to get random numbers or pick a	random element from a list

       For a list of all builtins, use builtin -n.

       For  a  list of all builtins, functions and commands shipped with fish,
       see the list of commands. The documentation is also available by	 using
       the --help switch.

   Shell variable and function names
       The  names  given  to variables and functions (so called	"identifiers")
       have to follow certain rules:

       o A variable name cannot	be empty. It can contain only letters, digits,
	 and underscores. It may begin and end with any	of those characters.

       o A function name cannot	be empty. It may not begin with	a hyphen ("-")
	 and may not contain a slash ("/"). All	other characters, including  a
	 space,	are valid.

       o A  bind  mode	name  (e.g., bind -m abc ...) must be a	valid variable
	 name.

       Other things have other restrictions. For instance what is allowed  for
       file  names  depends  on	your system, but at the	very least they	cannot
       contain a "/" (because that is the path separator) or  NULL  byte  (be-
       cause that is how UNIX ends strings).

   Future feature flags
       Feature	flags  are  how	 fish stages changes that might	break scripts.
       Breaking	changes	are introduced as opt-in, in a few releases  they  be-
       come opt-out, and eventually the	old behavior is	removed.

       You can see the current list of features	via status features:

	  > status features
	  stderr-nocaret  on	 3.0	  ^ no longer redirects	stderr
	  qmark-noglob	  off	 3.0	  ? no longer globs
	  regex-easyesc	  off	 3.1	  string replace -r needs fewer	\\'s

       There are two breaking changes in fish 3.0: caret ^ no longer redirects
       stderr, and question mark ? is no longer	a glob.

       There is	one breaking change in fish 3.1: string	replace	-r does	a  su-
       perfluous  round	 of  escaping  for  the	replacement, so	escaping back-
       slashes would look like string replace -ra '([ab])' '\\\\\\\$1' a. This
       flag removes that if turned on, so '\\\\$1' is enough.

       These  changes are off by default. They can be enabled on a per session
       basis:

	  > fish --features qmark-noglob,stderr-nocaret

       or opted	into globally for a user:

	  > set	-U fish_features stderr-nocaret	qmark-noglob

       Features	will only be set on startup, so	this variable will  only  take
       effect if it is universal or exported.

       You  can	 also  use  the	 version  as  a	group, so 3.0 is equivalent to
       "stderr-nocaret"	and "qmark-noglob".

       Prefixing a feature with	no- turns it off instead.

   Event handlers
       When defining a new function in fish, it	is possible to make it into an
       event  handler,	i.e.  a	function that is automatically run when	a spe-
       cific event takes place.	Events that can	trigger	 a  handler  currently
       are:

       o When a	signal is delivered

       o When a	job exits

       o When the value	of a variable is updated

       o When the prompt is about to be	shown

       Example:

       To specify a signal handler for the WINCH signal, write:

	  function my_signal_handler --on-signal WINCH
	      echo Got WINCH signal!
	  end

       Please  note  that event	handlers only become active when a function is
       loaded, which means you need to otherwise source	or execute a  function
       instead	of relying on autoloading. One approach	is to put it into your
       configuration file.

       For more	information on how to define new event handlers, see the docu-
       mentation for the function command.

   Debugging fish scripts
       Fish includes a built in	debugging facility. The	debugger allows	you to
       stop execution of a script at an	arbitrary point. When this happens you
       are  presented  with an interactive prompt. At this prompt you can exe-
       cute any	fish command (there are	no debug commands as such). For	 exam-
       ple,  you  can  check or	change the value of any	variables using	printf
       and set.	As another example, you	can run	 status	 print-stack-trace  to
       see  how	this breakpoint	was reached. To	resume normal execution	of the
       script, simply type exit	or Control+D.

       To start	a debug	session	simply run the builtin command	breakpoint  at
       the point in a function or script where you wish	to gain	control. Also,
       the default action of the TRAP signal is	to call	 this  builtin.	 So  a
       running	script	can be debugged	by sending it the TRAP signal with the
       kill command. Once in the debugger, it is easy  to  insert  new	break-
       points  by  using the funced function to	edit the definition of a func-
       tion.

   Commands
       fish ships with the following commands:

   _ - call fish's translations
   Synopsis
	  _ STRING...

   Description
       _ translates its	arguments into the current language, if	possible.

       It is equivalent	to gettext fish	STRING,	meaning	it can only be used to
       look up fish's own translations.

       It  requires  fish to be	built with gettext support. If that support is
       disabled, or there is no	translation it will simply echo	 the  argument
       back.

       The language depends on the current locale, set with $LANG and $LC_MES-
       SAGES.

   Options
       _ has no	options.

   Examples
	  > _ File
	  Datei

   abbr	- manage fish abbreviations
   Synopsis
	  abbr --add [SCOPE] WORD EXPANSION
	  abbr --erase WORD...
	  abbr --rename	[SCOPE]	OLD_WORD NEW_WORD
	  abbr --show
	  abbr --list
	  abbr --query WORD...

   Description
       abbr manages abbreviations - user-defined words that are	replaced  with
       longer phrases after they are entered.

       For example, a frequently-run command like git checkout can be abbrevi-
       ated to gco. After entering gco and pressing Space or Enter,  the  full
       text git	checkout will appear in	the command line.

   Options
       The following options are available:

       o -a  WORD  EXPANSION  or --add WORD EXPANSION Adds a new abbreviation,
	 causing WORD to be expanded to	EXPANSION.

       o -r OLD_WORD NEW_WORD or --rename OLD_WORD NEW_WORD Renames an	abbre-
	 viation, from OLD_WORD	to NEW_WORD.

       o -s  or	 --show	Show all abbreviations in a manner suitable for	export
	 and import.

       o -l or --list Lists all	abbreviated words.

       o -e WORD or --erase WORD... Erase the given abbreviations.

       o -q or --query Return 0	(true) if one of the WORDs is an abbreviation.

       In addition, when adding	or renaming abbreviations:

       o -g or --global	to use a global	variable.

       o -U or --universal to use a universal variable (default).

       See the "Internals" section for more on them.

   Examples
	  abbr -a -g gco git checkout

       Add a new abbreviation where gco	will be	 replaced  with	 git  checkout
       global  to  the	current	shell. This abbreviation will not be automati-
       cally visible to	other shells unless the	same command is	run  in	 those
       shells (such as when executing the commands in config.fish).

	  abbr -a -U l less

       Add  a new abbreviation where l will be replaced	with less universal so
       all shells. Note	that you omit the -U since it is the default.

	  abbr -r gco gch

       Renames an existing abbreviation	from gco to gch.

	  abbr -e gco

       Erase the gco abbreviation.

	  ssh another_host abbr	-s | source

       Import the abbreviations	defined	on another_host	over SSH.

   Internals
       Each abbreviation is stored in its own global  or  universal  variable.
       The  name consists of the prefix	_fish_abbr_ followed by	the WORD after
       being transformed by string escape style=var. The WORD cannot contain a
       space but all other characters are legal.

       Defining	an abbreviation	with global scope is slightly faster than uni-
       versal scope (which is the default). But	in general you'll only want to
       use  the	 global	 scope when defining abbreviations in a	startup	script
       like ~/.config/fish/config.fish like this:

	  if status --is-interactive
	      abbr --add --global first	'echo my first abbreviation'
	      abbr --add --global second 'echo my second abbreviation'
	      abbr --add --global gco git checkout
	      #	etcetera
	  end

       You can create abbreviations interactively and they will	be visible  to
       other  fish sessions if you use the -U or --universal flag or don't ex-
       plicitly	specify	the scope and the abbreviation isn't  already  defined
       with  global  scope.  If	 you want it to	be visible only	to the current
       shell use the -g	or --global flag.

   alias - create a function
   Synopsis
	  alias
	  alias	[OPTIONS] NAME DEFINITION
	  alias	[OPTIONS] NAME=DEFINITION

   Description
       alias is	a simple wrapper for the function  builtin,  which  creates  a
       function	 wrapping  a  command.	It  has	 similar syntax	to POSIX shell
       alias. For other	uses, it is recommended	to define a function.

       fish marks functions that have been created by alias by	including  the
       command	used  to create	them in	the function description. You can list
       alias-created functions by running alias	without	arguments.  They  must
       be erased using functions -e.

       o NAME is the name of the alias

       o DEFINITION is the actual command to execute. The string $argv will be
	 appended.

       You cannot create an alias to a function	with the same name. Note  that
       spaces need to be escaped in the	call to	alias just like	at the command
       line, even inside quoted	parts.

       The following options are available:

       o -h or --help displays help about using	this command.

       o -s or --save Automatically save the function  created	by  the	 alias
	 into your fish	configuration directory	using funcsave.

   Example
       The following code will create rmi, which runs rm with additional argu-
       ments on	every invocation.

	  alias	rmi="rm	-i"

	  # This is equivalent to entering the following function:
	  function rmi --wraps rm --description	'alias rmi=rm -i'
	      rm -i $argv
	  end

	  # This needs to have the spaces escaped or "Chrome.app..."
	  # will be seen as an argument	to "/Applications/Google":
	  alias	chrome='/Applications/Google\ Chrome.app/Contents/MacOS/Google\	Chrome banana'

   See more
       1. The function builtin this builds on.

       2. Functions.

       3. Function wrappers.

   and - conditionally execute a command
   Synopsis
	  COMMAND1; and	COMMAND2

   Description
       and is used to execute a	command	if the previous	command	was successful
       (returned a status of 0).

       and  statements	may be used as part of the condition in	an while or if
       block.

       and does	not change the current exit status itself, but the command  it
       runs  most  likely will.	The exit status	of the last foreground command
       to exit can always be accessed using the	$status	variable.

   Example
       The following code runs the make	command	to build  a  program.  If  the
       build  succeeds,	make's exit status is 0, and the program is installed.
       If either step fails, the exit status is	1,  and	 make  clean  is  run,
       which removes the files created by the build process.

	  make;	and make install; or make clean

   See Also
       o or command

   argparse - parse options passed to a	fish script or function
   Synopsis
	  argparse [OPTIONS] OPTION_SPEC... -- [ARG...]

   Description
       This command makes it easy for fish scripts and functions to handle ar-
       guments like how	fish builtin commands handle their arguments. You pass
       arguments that define the known options,	followed by a literal --, then
       the arguments to	be parsed (which might also  include  a	 literal  --).
       argparse	 then sets variables to	indicate the passed options with their
       values, and sets	$argv (and always $argv) to the	 remaining  arguments.
       More on this in the usage section below.

       Each  option  specification (OPTION_SPEC) is written in the domain spe-
       cific language described	below. All OPTION_SPECs	must appear after  any
       argparse	flags and before the --	that separates them from the arguments
       to be parsed.

       Each option that	is seen	in the ARG list	will result in variables named
       _flag_X,	 where	X  is the short	flag letter and	the long flag name (if
       they are	defined). For example a	--help option could cause argparse  to
       define one variable called _flag_h and another called _flag_help.

       The  variables will be set with local scope (i.e., as if	the script had
       done set	-l _flag_X). If	the flag is a boolean (that  is,  it  just  is
       passed  or  not,	 it doesn't have a value) the values are the short and
       long flags seen.	If the option is not a boolean the values will be zero
       or  more	values corresponding to	the values collected when the ARG list
       is processed. If	the flag was not seen the flag variable	 will  not  be
       set.

   Options
       The  following  argparse	options	are available. They must appear	before
       all OPTION_SPECs:

       o -n or --name is the command name for use in error  messages.  By  de-
	 fault the current function name will be used, or argparse if run out-
	 side of a function.

       o -x or --exclusive should be followed by a  comma  separated  list  of
	 short	or  long options that are mutually exclusive. You can use this
	 more than once	to define multiple sets	of mutually exclusive options.

       o -N or --min-args is followed by an integer that defines  the  minimum
	 number	of acceptable non-option arguments. The	default	is zero.

       o -X  or	 --max-args is followed	by an integer that defines the maximum
	 number	of acceptable non-option arguments. The	default	is infinity.

       o -i or --ignore-unknown	ignores	 unknown  options,  keeping  them  and
	 their arguments in $argv instead.

       o -s  or	--stop-nonopt causes scanning the arguments to stop as soon as
	 the first non-option argument is seen.	Among other  things,  this  is
	 useful	to implement subcommands that have their own options.

       o -h or --help displays help about using	this command.

   Usage
       To use this command, pass the option specifications (OPTION_SPEC), then
       a mandatory --, and then	the arguments you want to have parsed.

       A simple	example:

	  argparse --name=my_function 'h/help' 'n/name=' -- $argv
	  or return

       If $argv	is empty then there is nothing to parse	and  argparse  returns
       zero  to	indicate success. If $argv is not empty	then it	is checked for
       flags -h, --help, -n and	--name.	If they	are  found  they  are  removed
       from  the  arguments and	local variables	called _flag_OPTION are	set so
       the script can determine	which options were seen. If $argv doesn't have
       any errors, like	a missing mandatory value for an option, then argparse
       exits with a status of zero. Otherwise it writes	appropriate error mes-
       sages to	stderr and exits with a	status of one.

       The  or	return means that the function returns argparse's status if it
       failed, so if it	goes on	argparse succeeded.

       The -- argument is required. You	do not have to include	any  arguments
       after  the -- but you must include the --. For example, this is accept-
       able:

	  set -l argv
	  argparse 'h/help' 'n/name' --	$argv

       But this	is not:

	  set -l argv
	  argparse 'h/help' 'n/name' $argv

       The first -- seen is what allows	the argparse command to	reliably sepa-
       rate  the  option  specifications  and options to argparse itself (like
       --ignore-unknown) from the command arguments, so	it is required.

   Option Specifications
       Each option specification consists of:

       o An optional alphanumeric short	flag letter, followed by a  /  if  the
	 short flag can	be used	by someone invoking your command or, for back-
	 wards compatibility, a	- if it	should not be exposed as a valid short
	 flag (in which	case it	will also not be exposed as a flag variable).

       o An  optional  long flag name. If not present then only	the short flag
	 letter	can be used, and if that is not	present	either it's an error.

       o Nothing if the	flag is	a boolean that takes no	argument or is an  in-
	 teger flag, or

       o =  if	it  requires a value and only the last instance	of the flag is
	 saved,	or

       o =? it takes an	optional value and only	the last instance of the  flag
	 is saved, or

       o =+ if it requires a value and each instance of	the flag is saved.

       o Optionally  a	! followed by fish script to validate the value. Typi-
	 cally this will be a function to run. If the exit status is zero  the
	 value	for  the  flag is valid. If non-zero the value is invalid. Any
	 error messages	should be written to stdout (not stderr). See the sec-
	 tion on Flag Value Validation for more	information.

       See  the	fish_opt command for a friendlier but more verbose way to cre-
       ate option specifications.

       If a flag is not	seen when parsing the arguments	then the corresponding
       _flag_X var(s) will not be set.

   Integer flag
       Sometimes  commands  take numbers directly as options, like foo -55. To
       allow this one option spec can have the # modifier so that any  integer
       will  be	 understood as this flag, and the last number will be given as
       its value (as if	= was used).

       The # must follow the short flag	letter (if any), and  other  modifiers
       like = are not allowed, except for - (for backwards compatibility):

	  m#maximum

       This  does  not	read  numbers given as +NNN, only those	that look like
       flags - -NNN.

   Note: Optional arguments
       An option defined with =? can take optional arguments.  Optional	 argu-
       ments have to be	directly attached to the option	they belong to.

       That  means the argument	will only be used for the option if you	use it
       like:

	  cmd --flag=value
	  # or
	  cmd  -fvalue

       but not if used like:

	  cmd --flag value
	  # "value" here will be used as a positional argument
	  # and	"--flag" won't have an argument.

       If this weren't the case, using an option without an optional  argument
       would be	difficult if you also wanted to	use positional arguments.

       For example:

	  grep --color auto
	  # Here "auto"	will be	used as	the search string,
	  # "color" will not have an argument and will fall back to the	default,
	  # which also *happens	to be* auto.
	  grep --color always
	  # Here grep will still only use color	"auto"matically
	  # and	search for the string "always".

       This  isn't  specific  to  argparse  but	 common	 to  all  things using
       getopt(3) (if they have optional	arguments at all). That	 grep  example
       is how GNU grep actually	behaves.

   Flag	Value Validation
       Sometimes  you need to validate the option values. For example, that it
       is a valid integer within a specific range, or an ip address, or	 some-
       thing entirely different. You can always	do this	after argparse returns
       but you can also	request	that argparse perform the validation  by  exe-
       cuting  arbitrary  fish	script.	 To do so simply append	an ! (exclama-
       tion-mark) then the fish	script to be run. When that code  is  executed
       three vars will be defined:

       o _argparse_cmd	will  be set to	the value of the value of the argparse
	 --name	value.

       o _flag_name will be set	to the short or	 long  flag  that  being  pro-
	 cessed.

       o _flag_value  will  be set to the value	associated with	the flag being
	 processed.

       These variables are passed to the function as local exported variables.

       The script should write any error messages to stdout,  not  stderr.  It
       should  return  a status	of zero	if the flag value is valid otherwise a
       non-zero	status to indicate it is invalid.

       Fish ships with a _validate_int function	that accepts a --min and --max
       flag. Let's say your command accepts a -m or --max flag and the minimum
       allowable value is zero and the maximum is 5. You would define the  op-
       tion  like  this:  m/max=!_validate_int --min 0 --max 5.	The default if
       you just	call _validate_int without those flags is to simply check that
       the value is a valid integer with no limits on the min or max value al-
       lowed.

   Example OPTION_SPECs
       Some OPTION_SPEC	examples:

       o h/help	means that both	-h and --help are valid. The flag is a boolean
	 and  can  be used more	than once. If either flag is used then _flag_h
	 and _flag_help	will be	set to the count of how	many times either flag
	 was seen.

       o help  means  that only	--help is valid. The flag is a boolean and can
	 be used more than once. If it is used then _flag_help will be set  to
	 the count of how many times the long flag was seen. Also h-help (with
	 an arbitrary short letter) for	backwards compatibility.

       o longonly= is a	flag --longonly	that requires an option, there	is  no
	 short flag or even short flag variable.

       o n/name=  means	that both -n and --name	are valid. It requires a value
	 and can be used at most once. If the flag is seen  then  _flag_n  and
	 _flag_name  will  be  set  with the single mandatory value associated
	 with the flag.

       o n/name=? means	that both -n and --name	are valid. It accepts  an  op-
	 tional	 value	and can	be used	at most	once. If the flag is seen then
	 _flag_n and _flag_name	will be	set with the value associated with the
	 flag if one was provided else it will be set with no values.

       o name=+	 means	that only --name is valid. It requires a value and can
	 be used more than once. If the	flag is	seen then _flag_name  will  be
	 set with the values associated	with each occurrence.

       o x  means that only -x is valid. It is a boolean that can be used more
	 than once. If it is seen then _flag_x will be set to the count	of how
	 many times the	flag was seen.

       o x=,  x=?,  and	x=+ are	similar	to the n/name examples above but there
	 is no long flag alternative to	the short flag -x.

       o #max (or #-max) means that flags matching the	regex  "^--?\d+$"  are
	 valid.	 When  seen  they are assigned to the variable _flag_max. This
	 allows	any valid positive or negative integer to be specified by pre-
	 fixing	 it  with  a single "-". Many commands support this idiom. For
	 example head -3 /a/file  to  emit  only  the  first  three  lines  of
	 /a/file.

       o n#max	means that flags matching the regex "^--?\d+$" are valid. When
	 seen they are assigned	to the variables _flag_n and  _flag_max.  This
	 allows	any valid positive or negative integer to be specified by pre-
	 fixing	it with	a single "-". Many commands support  this  idiom.  For
	 example  head	-3  /a/file  to	 emit  only  the  first	three lines of
	 /a/file. You can also specify the value using either flag: -n NNN  or
	 --max NNN in this example.

       o #longonly  causes  the	last integer option to be stored in _flag_lon-
	 gonly.

       After parsing the arguments the argv variable is	set with  local	 scope
       to any values not already consumed during flag processing. If there are
       no unbound values the variable is set but count $argv will be zero.

       If an error occurs during argparse  processing  it  will	 exit  with  a
       non-zero	status and print error messages	to stderr.

   begin - start a new block of	code
   Synopsis
	  begin; [COMMANDS...;]	end

   Description
       begin is	used to	create a new block of code.

       A block allows the introduction of a new	variable scope,	redirection of
       the input or output of a	set of commands	as  a  group,  or  to  specify
       precedence when using the conditional commands like and.

       The block is unconditionally executed. begin; ...; end is equivalent to
       if true;	...; end.

       begin does not change the current exit status itself. After  the	 block
       has  completed,	$status	will be	set to the status returned by the most
       recent command.

   Example
       The following code sets a number	of variables inside of a block	scope.
       Since the variables are set inside the block and	have local scope, they
       will be automatically deleted when the block ends.

	  begin
	      set -l PIRATE Yarrr

	      ...
	  end

	  echo $PIRATE
	  # This will not output anything, since the PIRATE variable
	  # went out of	scope at the end of the	block

       In the following	code, all output is redirected to the file out.html.

	  begin
	      echo $xml_header
	      echo $html_header
	      if test -e $file
		  ...
	      end
	      ...
	  end >	out.html

   bg -	send jobs to background
   Synopsis
	  bg [PID...]

   Description
       bg sends	jobs to	the background,	resuming them if they are stopped.

       A background job	is executed simultaneously with	 fish,	and  does  not
       have access to the keyboard. If no job is specified, the	last job to be
       used is put in the background. If PID is	specified, the jobs containing
       the specified process IDs are put in the	background.

       For  compatibility with other shells, job expansion syntax is supported
       for bg. A PID of	the format %1 will be interpreted as the PID of	job 1.
       Job numbers can be seen in the output of	jobs.

       When at least one of the	arguments isn't	a valid	job specifier, bg will
       print an	error without backgrounding anything.

       When all	arguments are valid job	specifiers,  bg	 will  background  all
       matching	jobs that exist.

   Example
       bg 123 456 789 will background the jobs that contain processes 123, 456
       and 789.

       If only 123 and 789 exist, it will still	background them	and  print  an
       error about 456.

       bg  123	banana	or  bg banana 123 will complain	that "banana" is not a
       valid job specifier.

       bg %1 will background job 1.

   bind	- handle fish key bindings
   Synopsis
	  bind [(-M | --mode) MODE] [(-m | --sets-mode)	NEW_MODE] [--preset | --user] [(-s | --silent)]	[(-k | --key)] SEQUENCE	COMMAND	[COMMAND...]
	  bind [(-M | --mode) MODE] [(-k | --key)] [--preset] [--user] SEQUENCE
	  bind (-K | --key-names) [(-a | --all)] [--preset] [--user]
	  bind (-f | --function-names)
	  bind (-L | --list-modes)
	  bind (-e | --erase) [(-M | --mode) MODE] [--preset] [--user] (-a | --all | [(-k | --key)] SEQUENCE [SEQUENCE...])

   Description
       bind manages bindings.

       It can add bindings if given a SEQUENCE of characters to	bind to. These
       should be written as fish escape	sequences. The most important of these
       are \c for the control key, and \e for escape, and because of  histori-
       cal reasons also	the Alt	key (sometimes also called "Meta").

       For  example,  Alt+W  can  be written as	\ew, and Control+X (^X)	can be
       written as \cx. Note that Alt-based key bindings	are case sensitive and
       Control-based  key bindings are not. This is a constraint of text-based
       terminals, not fish.

       The generic key binding that matches if no other	binding	 does  can  be
       set  by	specifying  a SEQUENCE of the empty string (that is, ''	). For
       most key	bindings, it makes sense to bind this to the self-insert func-
       tion  (i.e.  bind  '' self-insert). This	will insert any	keystrokes not
       specifically bound to into the editor. Non-printable characters are ig-
       nored by	the editor, so this will not result in control sequences being
       inserted.

       If the -k switch	is used, the name of a key (such as  'down',  'up'  or
       'backspace') is used instead of a sequence. The names used are the same
       as the corresponding curses variables, but without the  'key_'  prefix.
       (See  terminfo(5)  for  more information, or use	bind --key-names for a
       list of all available named keys). Normally this	will print an error if
       the  current $TERM entry	doesn't	have a given key, unless the -s	switch
       is given.

       To find out  what  sequence  a  key  combination	 sends,	 you  can  use
       fish_key_reader.

       COMMAND	can  be	 any  fish command, but	it can also be one of a	set of
       special input functions.	These include functions	for moving the cursor,
       operating  on  the  kill-ring, performing tab completion, etc. Use bind
       --function-names	for a complete list of these input functions.

       When COMMAND is a shellscript command, it is a good practice to put the
       actual  code into a function and	simply bind to the function name. This
       way it becomes significantly easier to test the function	while editing,
       and the result is usually more readable as well.

       If a script produces output, it should finish by	calling	commandline -f
       repaint to tell fish that a repaint is in order.

       Note that special input functions  cannot  be  combined	with  ordinary
       shell script commands. The commands must	be entirely a sequence of spe-
       cial input functions (from bind -f) or all shell	script commands	(i.e.,
       valid fish script).

       If  no  SEQUENCE	is provided, all bindings (or just the bindings	in the
       given MODE) are printed.	If SEQUENCE is provided	but no	COMMAND,  just
       the binding matching that sequence is printed.

       To  save	 custom	keybindings, put the bind statements into config.fish.
       Alternatively, fish  also  automatically	 executes  a  function	called
       fish_user_key_bindings if it exists.

       Key  bindings  may use "modes", which mimics Vi's modal input behavior.
       The default mode	is "default", and every	bind applies to	a single mode.
       The mode	can be viewed/changed with the $fish_bind_mode variable.

   Options
       The following options are available:

       o -k or --key Specify a key name, such as 'left'	or 'backspace' instead
	 of a character	sequence

       o -K or --key-names Display a list of available key  names.  Specifying
	 -a or --all includes keys that	don't have a known mapping

       o -f or --function-names	Display	a list of available input functions

       o -L or --list-modes Display a list of defined bind modes

       o -M  MODE or --mode MODE Specify a bind	mode that the bind is used in.
	 Defaults to "default"

       o -m NEW_MODE or	 --sets-mode  NEW_MODE	Change	the  current  mode  to
	 NEW_MODE after	this binding is	executed

       o -e  or	--erase	Erase the binding with the given sequence and mode in-
	 stead of defining a new one. Multiple sequences can be	specified with
	 this  flag. Specifying	-a or --all with -M or --mode erases all binds
	 in the	given mode regardless of  sequence.  Specifying	 -a  or	 --all
	 without  -M or	--mode erases all binds	in all modes regardless	of se-
	 quence.

       o -a or --all See --erase and --key-names

       o --preset and --user specify if	bind should operate on user or	preset
	 bindings.  User  bindings  take  precedence over preset bindings when
	 fish looks up mappings. By default, all bind invocations work on  the
	 "user"	level except for listing, which	will show both levels. All in-
	 vocations except for inserting	new bindings can operate on both  lev-
	 els  at the same time (if both	--preset and --user are	given).	--pre-
	 set should only be used in full binding sets (like  when  working  on
	 fish_vi_key_bindings).

   Special input functions
       The following special input functions are available:

       o and,  only execute the	next function if the previous succeeded	(note:
	 only some functions report success)

       o accept-autosuggestion,	accept the current autosuggestion completely

       o backward-char,	moves one character to the left

       o backward-bigword, move	one whitespace-delimited word to the left

       o backward-delete-char, deletes one character of	input to the  left  of
	 the cursor

       o backward-kill-bigword,	move the whitespace-delimited word to the left
	 of the	cursor to the killring

       o backward-kill-line, move everything from the beginning	of the line to
	 the cursor to the killring

       o backward-kill-path-component,	move one path component	to the left of
	 the cursor to the killring. A path component is everything likely  to
	 belong	 to a path component, i.e. not any of the following: /={,}'":@
	 |;___,	plus newlines and tabs.

       o backward-kill-word, move the word to the left of the  cursor  to  the
	 killring.  The	 "word"	here is	everything up to punctuation or	white-
	 space.

       o backward-word,	move one word to the left

       o beginning-of-buffer, moves to the beginning of	the buffer,  i.e.  the
	 start of the first line

       o beginning-of-history, move to the beginning of	the history

       o beginning-of-line, move to the	beginning of the line

       o begin-selection, start	selecting text

       o cancel,  cancel  the  current	commandline  and replace it with a new
	 empty one

       o cancel-commandline, cancel the	current	 commandline  and  replace  it
	 with  a  new empty one, leaving the old one in	place with a marker to
	 show that it was cancelled

       o capitalize-word, make the current word	begin with a capital letter

       o complete, guess the remainder of the current token

       o complete-and-search, invoke the searchable pager  on  completion  op-
	 tions	(for  convenience, this	also moves backwards in	the completion
	 pager)

       o delete-char, delete one character to the right	of the cursor

       o delete-or-exit, deletes one character to the right of the  cursor  or
	 exits the shell if the	commandline is empty.

       o down-line, move down one line

       o downcase-word,	make the current word lowercase

       o end-of-buffer,	 moves	to  the	end of the buffer, i.e.	the end	of the
	 first line

       o end-of-history, move to the end of the	history

       o end-of-line, move to the end of the line

       o end-selection,	end selecting text

       o expand-abbr, expands any abbreviation currently under the cursor

       o execute, run the current commandline

       o exit, exit the	shell

       o forward-bigword, move one whitespace-delimited	word to	the right

       o forward-char, move one	character to the right

       o forward-single-char, move one character to the	right; if an  autosug-
	 gestion is available, only take a single char from it

       o forward-word, move one	word to	the right

       o history-search-backward, search the history for the previous match

       o history-search-forward, search	the history for	the next match

       o history-prefix-search-backward,  search  the history for the previous
	 prefix	match

       o history-prefix-search-forward,	search the history for the next	prefix
	 match

       o history-token-search-backward,	 search	 the  history for the previous
	 matching argument

       o history-token-search-forward, search the history for the next	match-
	 ing argument

       o forward-jump  and  backward-jump,  read another character and jump to
	 its next occurence after/before the cursor

       o forward-jump-till and backward-jump-till, jump	to  right  before  the
	 next occurence

       o repeat-jump  and  repeat-jump-reverse,	 redo  the  last  jump	in the
	 same/opposite direction

       o kill-bigword, move the	next whitespace-delimited word to the killring

       o kill-line, move everything from the cursor to the end of the line  to
	 the killring

       o kill-selection, move the selected text	to the killring

       o kill-whole-line, move the line	to the killring

       o kill-word, move the next word to the killring

       o or,  only  execute the	next function if the previous succeeded	(note:
	 only some functions report success)

       o pager-toggle-search, toggles the  search  field  if  the  completions
	 pager is visible.

       o repaint, reexecutes the prompt	functions and redraws the prompt (also
	 force-repaint for backwards-compatibility)

       o repaint-mode, reexecutes the fish_mode_prompt and redraws the prompt.
	 This  is  useful  for	vi-mode.  If  no fish_mode_prompt exists or it
	 prints	nothing, it acts like a	normal repaint.

       o self-insert, inserts the matching sequence into the command line

       o self-insert-notfirst, inserts the matching sequence into the  command
	 line, unless the cursor is at the beginning

       o suppress-autosuggestion,  remove  the current autosuggestion. Returns
	 true if there was a suggestion	to remove.

       o swap-selection-start-stop, go to the other  end  of  the  highlighted
	 text without changing the selection

       o transpose-chars, transpose two	characters to the left of the cursor

       o transpose-words, transpose two	words to the left of the cursor

       o togglecase-char,  toggle  the	capitalisation (case) of the character
	 under the cursor

       o togglecase-selection, toggle the capitalisation (case)	of the	selec-
	 tion

       o insert-line-under, add	a new line under the current line

       o insert-line-over, add a new line over the current line

       o up-line, move up one line

       o undo  and  redo,  revert or redo the most recent edits	on the command
	 line

       o upcase-word, make the current word uppercase

       o yank, insert the latest entry of the killring into the	buffer

       o yank-pop, rotate to the previous entry	of the killring

   Additional functions
       The following functions are included as normal functions, but are  par-
       ticularly useful	for input editing:

       o up-or-search and down-or-search,  which move the cursor or search the
	 history depending on the cursor position and current mode

       o edit_command_buffer, open the visual editor (controlled by the	VISUAL
	 or  EDITOR  environment variables) with the current command-line con-
	 tents

       o delete-or-exit, quit the shell	if the current command-line is	empty,
	 or delete the character under the cursor if not

       o fish_clipboard_copy,  copy  the current selection to the system clip-
	 board

       o fish_clipboard_paste, paste the current  selection  from  the	system
	 clipboard before the cursor

       o fish_commandline_append,  append the argument to the command-line. If
	 the command-line already ends with the	 argument,  this  removes  the
	 suffix	instead. Starts	with the last command from history if the com-
	 mand-line is empty.

       o fish_commandline_prepend, prepend the argument	to  the	 command-line.
	 If  the  command-line	already	starts with the	argument, this removes
	 the prefix instead. Starts with the last command from history if  the
	 command-line is empty.

   Examples
       Exit the	shell when Control+D is	pressed:

	  bind \cd 'exit'

       Perform a history search	when Page Up is	pressed:

	  bind -k ppage	history-search-backward

       Turn on Vi key bindings and rebind Control+C to clear the input line:

	  set -g fish_key_bindings fish_vi_key_bindings
	  bind -M insert \cc kill-whole-line repaint

       Launch  git  diff and repaint the commandline afterwards	when Control+G
       is pressed:

	  bind \cg 'git	diff; commandline -f repaint'

   Terminal Limitations
       Unix terminals, like the	ones fish operates in, are at heart 70s	 tech-
       nology.	They  have  some  limitations that applications	running	inside
       them can't workaround.

       For instance, the control key modifies a	character by setting  the  top
       three bits to 0.	This means:

       o Many characters + control are indistinguishable from other keys. Con-
	 trol+I	is tab,	Control+J is newline (n).

       o Control and shift don't work simultaneously

       Other keys don't	have a direct encoding,	and are	 sent  as  escape  se-
       quences.	For example ^a (Right) often sends \e\[C. These can differ from
       terminal	to terminal, and the mapping is	typically  available  in  ter-
       minfo(5).   Sometimes   however	 a   terminal	identifies   as	  e.g.
       xterm-256color for compatibility, but then implements xterm's sequences
       incorrectly.

   Special Case: The Escape Character
       The  escape key can be used standalone, for example, to switch from in-
       sertion mode to normal mode when	using Vi keybindings. Escape can  also
       be  used	 as a "meta" key, to indicate the start	of an escape sequence,
       like for	function or arrow keys.	Custom bindings	can  also  be  defined
       that begin with an escape character.

       Holding alt and something else also typically sends escape, for example
       holding alt+a will send an escape character and then an "a".

       fish waits for a	period after receiving the escape character, to	deter-
       mine  whether  it  is  standalone  or part of an	escape sequence. While
       waiting,	additional key presses make the	escape key behave  as  a  meta
       key. If no other	key presses come in, it	is handled as a	standalone es-
       cape. The waiting period	is set to 30 milliseconds (0.03	 seconds).  It
       can  be	configured  by	setting	the fish_escape_delay_ms variable to a
       value between 10	and 5000 ms. This can be a universal variable that you
       set once	from an	interactive session.

   block - temporarily block delivery of events
   Synopsis
	  block	[OPTIONS...]

   Description
       block  prevents events triggered	by fish	or the emit command from being
       delivered and acted upon	while the block	is in place.

       In functions, block can be useful while performing work that should not
       be interrupted by the shell.

       The  block  can	be removed. Any	events which triggered while the block
       was in place will then be delivered.

       Event blocks should not be confused with	code blocks, which are created
       with begin, if, while or	for

       The following parameters	are available:

       o -l  or	--local	Release	the block automatically	at the end of the cur-
	 rent innermost	code block scope

       o -g or --global	Never automatically release the	lock

       o -e or --erase Release global block

   Example
	  # Create a function that listens for events
	  function --on-event foo foo; echo 'foo fired'; end

	  # Block the delivery of events
	  block	-g

	  emit foo
	  # No output will be produced

	  block	-e
	  # 'foo fired'	will now be printed

   Notes
       Note that events	are only received from the  current  fish  process  as
       there is	no way to send events from one fish process to another.

   break - stop	the current inner loop
   Synopsis
	  LOOP_CONSTRUCT; [COMMANDS...]	break; [COMMANDS...] end

   Description
       break  halts  a	currently running loop,	such as	a switch, for or while
       loop. It	is usually added inside	of a conditional block such as	an  if
       block.

       There are no parameters for break.

   Example
       The  following code searches all	.c files for "smurf", and halts	at the
       first occurrence.

	  for i	in *.c
	      if grep smurf $i
		  echo Smurfs are present in $i
		  break
	      end
	  end

   See Also
       o the continue command, to skip the remainder of	the current  iteration
	 of the	current	inner loop

   breakpoint -	launch debug mode
   Synopsis
	  breakpoint

   Description
       breakpoint  is  used to halt a running script and launch	an interactive
       debugging prompt.

       For more	details, see Debugging fish scripts in the fish	manual.

       There are no parameters for breakpoint.

   builtin - run a builtin command
   Synopsis
	  builtin [OPTIONS...] BUILTINNAME
	  builtin --query BUILTINNAMES...

   Description
       builtin forces the shell	to use a builtin command, rather than a	 func-
       tion or program.

       The following parameters	are available:

       o -n or --names List the	names of all defined builtins

       o -q or --query tests if	any of the specified builtins exists

   Example
	  builtin jobs
	  # executes the jobs builtin, even if a function named	jobs exists

   case	- conditionally	execute	a block	of commands
   Synopsis
	  switch VALUE;	[case [WILDCARD...]; [COMMANDS...]; ...] end

   Description
       switch executes one of several blocks of	commands, depending on whether
       a specified value matches one of	several	values.	case is	used  together
       with  the  switch statement in order to determine which block should be
       executed.

       Each case command is given one or more parameters. The first case  com-
       mand  with  a parameter that matches the	string specified in the	switch
       command will be evaluated. case parameters may contain wildcards. These
       need  to	be escaped or quoted in	order to avoid regular wildcard	expan-
       sion using filenames.

       Note that fish does not fall through on case statements.	Only the first
       matching	case is	executed.

       Note  that  command substitutions in a case statement will be evaluated
       even if its body	is not taken.  All  substitutions,  including  command
       substitutions,  must  be	 performed  before  the	 value can be compared
       against the parameter.

   Example
       Say $animal contains the	name of	an animal. Then	this code would	 clas-
       sify it:

	  switch $animal
	      case cat
		  echo evil
	      case wolf	dog human moose	dolphin	whale
		  echo mammal
	      case duck	goose albatross
		  echo bird
	      case shark trout stingray
		  echo fish
	      #	Note that the next case	has a wildcard which is	quoted
	      case '*'
		  echo I have no idea what a $animal is
	  end

       If  the	above code was run with	$animal	set to whale, the output would
       be mammal.

       If $animal was set to "banana", it would	print "I have no idea  what  a
       banana is".

   cd -	change directory
   Synopsis
	  cd [DIRECTORY]

   Description
       cd changes the current working directory.

       If  DIRECTORY  is supplied, it will become the new directory. If	no pa-
       rameter is given, the contents of the HOME environment variable will be
       used.

       If  DIRECTORY  is  a  relative path, the	paths found in the CDPATH list
       will be tried as	prefixes for the specified path, in addition to	$PWD.

       Note that the shell will	attempt	to change directory without  requiring
       cd  if the name of a directory is provided (starting with ., / or ~, or
       ending with /).

       Fish also ships a wrapper function around the builtin  cd  that	under-
       stands cd - as changing to the previous directory. See also prevd. This
       wrapper function	maintains a history of the 25  most  recently  visited
       directories  in the $dirprev and	$dirnext global	variables. If you make
       those universal variables your cd history is shared among all fish  in-
       stances.

       As  a  special  case, cd	. is equivalent	to cd $PWD, which is useful in
       cases where a mountpoint	has been recycled or a directory has been  re-
       moved and recreated.

   Examples
	  cd
	  # changes the	working	directory to your home directory.

	  cd /usr/src/fish-shell
	  # changes the	working	directory to /usr/src/fish-shell

   See Also
       Navigate	directories using the directory	history	or the directory stack

   cdh - change	to a recently visited directory
   Synopsis
	  cdh [	directory ]

   Description
       cdh  with no arguments presents a list of recently visited directories.
       You can then select one of the entries by letter	 or  number.  You  can
       also  press  Tab	to use the completion pager to select an item from the
       list. If	you give it a single argument it is equivalent	to  cd	direc-
       tory.

       Note  that  the	cd command limits directory history to the 25 most re-
       cently visited directories. The history is stored in the	 $dirprev  and
       $dirnext	 variables  which  this	command	manipulates. If	you make those
       universal variables your	cd history is shared among all fish instances.

   See Also
       o the dirh command to print the directory history

       o the prevd command to move backward

       o the nextd command to move forward

   command - run a program
   Synopsis
	  command [OPTIONS] COMMANDNAME	[ARGS...]

   Description
       command forces the shell	to execute the program COMMANDNAME and	ignore
       any functions or	builtins with the same name.

       The following options are available:

       o -a  or	 --all returns all the external	COMMANDNAMEs that are found in
	 $PATH in the order they are found.

       o -q or --query,	silences the output and	prints nothing,	 setting  only
	 the  exit  status.  Implies --search. For compatibility with old fish
	 versions this is also --quiet (but this is deprecated).

       o -s or --search	returns	the name of the	external command that would be
	 executed,  or	nothing	 if  no	 file with the specified name could be
	 found in the $PATH.

       With the	-s option, command treats every	argument as a separate command
       to  look	 up and	sets the exit status to	0 if any of the	specified com-
       mands were found, or 1 if no  commands  could  be  found.  Additionally
       passing	a  -q or --quiet option	prevents any paths from	being printed,
       like type -q, for testing only the exit status.

       For basic compatibility with POSIX command, the -v flag	is  recognized
       as an alias for -s.

   Examples
       command	ls  causes fish	to execute the ls program, even	if an ls func-
       tion exists.

       command -s ls returns the path to the ls	program.

       command -q git; and command git log runs	git log	only if	git exists.

   commandline - set or	get the	current	command	line buffer
   Synopsis
	  commandline [OPTIONS]	[CMD]

   Description
       commandline can be used to set or get the current contents of the  com-
       mand line buffer.

       With  no	 parameters, commandline returns the current value of the com-
       mand line.

       With CMD	specified, the command line buffer is erased and replaced with
       the contents of CMD.

       The following options are available:

       o -C  or	 --cursor set or get the current cursor	position, not the con-
	 tents of the buffer. If no argument is	given, the current cursor  po-
	 sition	 is  printed, otherwise	the argument is	interpreted as the new
	 cursor	position. If one of the	options	-j, -p or -t is	given, the po-
	 sition	 is relative to	the respective substring instead of the	entire
	 command line buffer.

       o -f or --function causes any additional	arguments to be	interpreted as
	 input	functions,  and	puts them into the queue, so that they will be
	 read before any additional actual key presses are. This option	cannot
	 be combined with any other option. See	bind for a list	of input func-
	 tions.

       The following options change the	way commandline	 updates  the  command
       line buffer:

       o -a  or	 --append  do  not  remove the current commandline, append the
	 specified string at the end of	it

       o -i or --insert	do not remove  the  current  commandline,  insert  the
	 specified string at the current cursor	position

       o -r  or	 --replace  remove the current commandline and replace it with
	 the specified string (default)

       The following options change what part of the commandline is printed or
       updated:

       o -b  or	 --current-buffer select the entire commandline, not including
	 any displayed autosuggestion (default)

       o -j or --current-job select the	current	job - a	job here is one	 pipe-
	 line.	It  stops  at  logical	operators or terminators (;, & or new-
	 lines).

       o -p or --current-process select	the current process - a	 process  here
	 is  one simple	command. It stops at logical operators,	terminators or
	 pipes.

       o -s or --current-selection selects the current selection

       o -t or --current-token select the current token

       The following options change the	way  commandline  prints  the  current
       commandline buffer:

       o -c  or	--cut-at-cursor	only print selection up	until the current cur-
	 sor position

       o -o or --tokenize tokenize the selection and print one string-type to-
	 ken per line

       If commandline is called	during a call to complete a given string using
       complete	-C STRING, commandline will consider the specified  string  to
       be the current contents of the command line.

       The following options output metadata about the commandline state:

       o -L  or	 --line	print the line that the	cursor is on, with the topmost
	 line starting at 1

       o -S or --search-mode evaluates to true if the commandline is  perform-
	 ing a history search

       o -P  or	 --paging-mode evaluates to true if the	commandline is showing
	 pager contents, such as tab completions

   Example
       commandline -j $history[3] replaces the job under the cursor  with  the
       third item from the command line	history.

       If the commandline contains

	  >_ echo $flounder >&2	| less;	and echo $catfish

       (with the cursor	on the "o" of "flounder")

       The  echo  $flounder  >&	 is the	first process, less the	second and and
       echo $catfish the third.

       echo $flounder >&2 | less is the	first job, and echo $catfish the  sec-
       ond.

       $flounder is the	current	token.

       More examples:

	  >_ commandline -t
	  $flounder
	  >_ commandline -ct
	  $fl
	  >_ commandline -b # or just commandline
	  echo $flounder >&2 | less; and echo $catfish
	  >_ commandline -p
	  echo $flounder >&2
	  >_ commandline -j
	  echo $flounder >&2 | less

   complete - edit command specific tab-completions
   Synopsis
	  complete [( -c | --command | -p | --path )] COMMAND
		  [( -c	| --command | -p | --path ) COMMAND]...
		  [( -e	| --erase )]
		  [( -s	| --short-option ) SHORT_OPTION]...
		  [( -l	| --long-option	| -o | --old-option ) LONG_OPTION]...
		  [( -a	| --arguments )	ARGUMENTS]
		  [( -k	| --keep-order )]
		  [( -f	| --no-files )]
		  [( -F	| --force-files	)]
		  [( -r	| --require-parameter )]
		  [( -x	| --exclusive )]
		  [( -w	| --wraps ) WRAPPED_COMMAND]...
		  [( -n	| --condition )	CONDITION]
		  [( -d	| --description	) DESCRIPTION]
	  complete ( -C	[STRING] | --do-complete[=STRING] )

   Description
       complete	defines, removes or lists completions for a command.

       For  an	introduction to	writing	your own completions, see Writing your
       own completions in the fish manual.

       o -c COMMAND 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.

       o -p COMMAND or --path COMMAND specifies	that COMMAND is	 the  absolute
	 path of the command (optionally containing wildcards).

       o -e or --erase deletes the specified completion.

       o -s SHORT_OPTION or --short-option=SHORT_OPTION	adds a short option to
	 the completions list.

       o -l LONG_OPTION	or --long-option=LONG_OPTION adds a GNU	style long op-
	 tion to the completions list.

       o -o LONG_OPTION	or --old-option=LONG_OPTION adds an old	style long op-
	 tion to the completions list (See below for details).

       o -a ARGUMENTS or --arguments=ARGUMENTS adds the	specified option argu-
	 ments to the completions list.

       o -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.

       o -f  or	 --no-files says that this completion may not be followed by a
	 filename.

       o -F or --force-files says that this completion may be  followed	 by  a
	 filename, even	if another applicable complete specified --no-files.

       o -r  or	--require-parameter says that this completion must have	an op-
	 tion argument,	i.e. may not be	followed by another option.

       o -x or --exclusive is short for	-r and -f.

       o -w WRAPPED_COMMAND or --wraps=WRAPPED_COMMAND	causes	the  specified
	 command  to  inherit  completions from	the wrapped command (See below
	 for details).

       o -n CONDITION or --condition CONDITION specifies that 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.

       o -C STRING or --do-complete=STRING makes complete try to find all pos-
	 sible completions for the specified string. If	there  is  no  STRING,
	 the current commandline is used instead.

       Command specific	tab-completions	in fish	are based on the notion	of op-
       tions and arguments. An option is a parameter which begins with	a  hy-
       phen, 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:

       o 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
	 in the	following parameter (-w	32) or by appending  the  option  with
	 the value (-w32).

       o Old  style  long options, like	-Wall or -name.	Old style long options
	 can be	more than one character	long, are preceded by a	single	hyphen
	 and  may  not	be grouped together. Option arguments are specified in
	 the following parameter (-ao null).

       o 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	in the follow-
	 ing   parameter   (--quoting-style  shell)  or	 after	a  =  (--quot-
	 ing-style=shell).

       Multiple	commands and paths can be given	in one call to define the same
       completions for multiple	commands.

       Multiple	command	switches and wrapped commands can also be given	to de-
       fine multiple completions in one	call.

       Invoking	complete multiple times	for the	same command adds the new def-
       initions	on top of any existing completions defined for the command.

       When -a or --arguments is specified in conjunction with long, short, or
       old style options, the specified	arguments are only completed as	 argu-
       ments  for any of the specified options.	If -a or --arguments is	speci-
       fied without any	long, short, or	old style options, the specified argu-
       ments are used when completing non-option arguments to the command (ex-
       cept when completing an option argument that was	specified with	-r  or
       --require-parameter).

       Command	substitutions found in ARGUMENTS should	return a newline-sepa-
       rated 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.

       The -w or --wraps options causes	the specified command to inherit  com-
       pletions	 from another command, "wrapping" the other command. The wrap-
       ping 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	speci-
       fying completions with -p or --path.

       When  erasing  completions,  it is possible to either erase all comple-
       tions for a specific command by specifying complete -c COMMAND  -e,  or
       by specifying a specific	completion option to delete.

       When  complete  is  called  without anything that would define or erase
       completions (options, arguments,	wrapping, ...),	it shows matching com-
       pletions	 instead.  So  complete	without	any arguments shows all	loaded
       completions, complete -c	foo shows  all	loaded	completions  for  foo.
       Since completions are autoloaded, you will have to trigger them first.

   Examples
       The short style option -o for the gcc command needs a file argument:

	  complete -c gcc -s o -r

       The  short  style  option -d for	the grep command requires one of read,
       skip or recurse:

	  complete -c grep -s d	-x -a "read skip recurse"

       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:

	  complete -x -c su -d "Username" -a "(cat /etc/passwd | cut -d	: -f 1)"

       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.

       This can	be written as:

	  complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps	-d "Don't check	dependencies"

       where  __fish_contains_opt  is  a function that checks the command line
       buffer for the presence of a specified set of options.

       To implement an alias, use the -w or --wraps option:

	  complete -c hub -w git

       Now hub inherits	all of the completions from git. Note this can also be
       specified in a function declaration (function thing -w otherthing).

	  complete -c git

       Show all	completions for	git.

   contains - test if a	word is	present	in a list
   Synopsis
	  contains [OPTIONS] KEY [VALUES...]

   Description
       contains	 tests	whether	the set	VALUES contains	the string KEY.	If so,
       contains	exits with status 0; if	not, it	exits with status 1.

       The following options are available:

       o -i or --index print the word index

       Note that, like GNU tools and most of fish's builtins, contains	inter-
       prets  all arguments starting with a - as options to contains, until it
       reaches an argument that	is -- (two dashes). See	the examples below.

   Example
       If $animals is a	list of	animals, the following will test  if  it  con-
       tains a cat:

	  if contains cat $animals
	     echo Your animal list is evil!
	  end

       This  code  will	 add  some directories to $PATH	if they	aren't yet in-
       cluded:

	  for i	in ~/bin /usr/local/bin
	      if not contains $i $PATH
		  set PATH $PATH $i
	      end
	  end

       While this will check if	hasargs	was run	with the -q option:

	  function hasargs
	      if contains -- -q	$argv
		  echo '$argv contains a -q option'
	      end
	  end

       The -- here stops contains from treating	-q to an option	to itself. In-
       stead it	treats it as a normal string to	check.

   continue - skip the remainder of the	current	iteration of the current inner
       loop
   Synopsis
	  LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end

   Description
       continue	skips the remainder of the current iteration  of  the  current
       inner loop, such	as a for loop or a while loop. It is usually added in-
       side of a conditional block such	as an if statement or a	switch	state-
       ment.

   Example
       The  following  code removes all	tmp files that do not contain the word
       smurf.

	  for i	in *.tmp
	      if grep smurf $i
		  continue
	      end
	      #	This "rm" is skipped over if "continue"	is executed.
	      rm $i
	      #	As is this "echo"
	      echo $i
	  end

   See Also
       o the break command, to stop the	current	inner loop

   count - count the number of elements	of a list
   Synopsis
	  count	$VARIABLE
	  COMMAND | count
	  count	< FILE

   Description
       count prints the	number of arguments that were passed to	it,  plus  the
       number of newlines passed to it via stdin. This is usually used to find
       out how many elements an	environment variable  list  contains,  or  how
       many lines there	are in a text file.

       count does not accept any options, not even -h or --help.

       count  exits with a non-zero exit status	if no arguments	were passed to
       it, and with zero if at least one argument was passed.

       Note that, like wc -l, reading from stdin counts	newlines, so  echo  -n
       foo | count will	print 0.

   Example
	  count	$PATH
	  # Returns the	number of directories in the users PATH	variable.

	  count	*.txt
	  # Returns the	number of files	in the current working directory
	  # ending with	the suffix '.txt'.

	  git ls-files --others	--exclude-standard | count
	  # Returns the	number of untracked files in a git repository

	  printf '%s\n'	foo bar	| count	baz
	  # Returns 3 (2 lines from stdin plus 1 argument)

	  count	< /etc/hosts
	  # Counts the number of entries in the	hosts file

   dirh	- print	directory history
   Synopsis
	  dirh

   Description
       dirh  prints the	current	directory history. The current position	in the
       history is highlighted using the	color defined in  the  fish_color_his-
       tory_current environment	variable.

       dirh does not accept any	parameters.

       Note  that  the	cd command limits directory history to the 25 most re-
       cently visited directories. The history is stored in the	 $dirprev  and
       $dirnext	variables.

   See Also
       o the cdh command to display a prompt to	quickly	navigate the history

       o the prevd command to move backward

       o the nextd command to move forward

   dirs	- print	directory stack
   Synopsis
	  dirs
	  dirs -c

   Description
       dirs  prints the	current	directory stack, as created by pushd and modi-
       fied by popd.

       With "-c", it clears the	directory stack	instead.

       dirs does not accept any	parameters.

   See Also
       o the cdh command which provides	a more intuitive way  to  navigate  to
	 recently visited directories.

   disown - remove a process from the list of jobs
   Synopsis
	  disown [ PID ... ]

   Description
       disown  removes the specified job from the list of jobs.	The job	itself
       continues to exist, but fish does not keep track	of it any longer.

       Jobs in the list	of jobs	are sent a hang-up  signal  when  fish	termi-
       nates,  which  usually causes the job to	terminate; disown allows these
       processes to continue regardless.

       If no process is	specified, the most recently-used job is removed (like
       bg and fg).  If one or more PIDs	are specified, jobs with the specified
       process IDs are removed from the	job list. Invalid jobs are ignored and
       a warning is printed.

       If  a  job  is  stopped,	it is sent a signal to continue	running, and a
       warning is printed. It is not possible to use the bg  builtin  to  con-
       tinue a job once	it has been disowned.

       disown  returns 0 if all	specified jobs were disowned successfully, and
       1 if any	problems were encountered.

   Example
       firefox &; disown will start the	Firefox	web browser in the  background
       and remove it from the job list,	meaning	it will	not be closed when the
       fish process is closed.

       disown (jobs -p)	removes	all jobs from the job list without terminating
       them.

   echo	- display a line of text
   Synopsis
	  echo [OPTIONS] [STRING]

   Description
       echo displays a string of text.

       The following options are available:

       o -n, Do	not output a newline

       o -s, Do	not separate arguments with spaces

       o -E, Disable interpretation of backslash escapes (default)

       o -e, Enable interpretation of backslash	escapes

       Unlike  other shells, this echo accepts -- to signal the	end of the op-
       tions.

   Escape Sequences
       If -e is	used, the following sequences are recognized:

       o \ backslash

       o \a alert (BEL)

       o \b backspace

       o \c produce no further output

       o \e escape

       o \f form feed

       o \n new	line

       o \r carriage return

       o \t horizontal tab

       o \v vertical tab

       o \0NNN byte with octal value NNN (1 to 3 digits)

       o \xHH byte with	hexadecimal value HH (1	to 2 digits)

   Example
	  > echo 'Hello	World'
	  Hello	World

	  > echo -e 'Top\nBottom'
	  Top
	  Bottom

	  > echo -- -n
	  -n

   See Also
       o the printf command, for more control over output formatting

   else	- execute command if a condition is not	met
   Synopsis
	  if CONDITION;	COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end

   Description
       if will execute the command CONDITION. If the condition's  exit	status
       is  0, the commands COMMANDS_TRUE will execute. If it is	not 0 and else
       is given, COMMANDS_FALSE	will be	executed.

   Example
       The following code tests	whether	a file foo.txt	exists	as  a  regular
       file.

	  if test -f foo.txt
	      echo foo.txt exists
	  else
	      echo foo.txt does	not exist
	  end

   emit	- emit a generic event
   Synopsis
	  emit EVENT_NAME [ARGUMENTS...]

   Description
       emit  emits, or fires, an event.	Events are delivered to, or caught by,
       special functions called	event handlers.	The arguments  are  passed  to
       the event handlers as function arguments.

   Example
       The following code first	defines	an event handler for the generic event
       named 'test_event', and then emits an event of that type.

	  function event_test --on-event test_event
	      echo event test: $argv
	  end

	  emit test_event something

   Notes
       Note that events	are only sent to the current fish process as there  is
       no way to send events from one fish process to another.

   end - end a block of	commands
   Synopsis
	  begin; [COMMANDS...] end
	  function NAME	[OPTIONS]; COMMANDS...;	end
	  if CONDITION;	COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
	  switch VALUE;	[case [WILDCARD...]; [COMMANDS...]; ...] end
	  while	CONDITION; COMMANDS...;	end
	  for VARNAME in [VALUES...]; COMMANDS...; end

   Description
       end ends	a block	of commands started by one of the following commands:

       o begin to start	a block	of commands

       o function to define a function

       o if, switch to conditionally execute commands

       o while,	for to perform commands	multiple times

       The  end	 command does not change the current exit status. Instead, the
       status after it will be the status returned by the most recent command.

   eval	- evaluate the specified commands
   Synopsis
	  eval [COMMANDS...]

   Description
       eval evaluates the specified parameters as a command. If	more than  one
       parameter  is  specified,  all  parameters will be joined using a space
       character as a separator.

       If your command does not	need access to stdin,  consider	 using	source
       instead.

       If  no  piping  or  other compound shell	constructs are required, vari-
       able-expansion-as-command, as in	 set cmd ls -la; $cmd, is also an  op-
       tion.

   Example
       The  following code will	call the ls command and	truncate each filename
       to the first 12 characters.

	  set cmd ls \|	cut -c 1-12
	  eval $cmd

   exec	- execute command in current process
   Synopsis
	  exec COMMAND [OPTIONS...]

   Description
       exec replaces the currently running shell with a	new command.  On  suc-
       cessful	completion,  exec  never returns. exec cannot be used inside a
       pipeline.

   Example
       exec emacs starts up the	emacs text editor, and exits fish. When	 emacs
       exits, the session will terminate.

   exit	- exit the shell
   Synopsis
	  exit [STATUS]

   Description
       exit  causes  fish to exit. If STATUS is	supplied, it will be converted
       to an integer and used as the exit status. Otherwise, the  exit	status
       will be that of the last	command	executed.

       If  exit	is called while	sourcing a file	(using the source builtin) the
       rest of the file	will be	skipped, but the shell itself will not exit.

   false - return an unsuccessful result
   Synopsis
	  false

   Description
       false sets the exit status to 1.

   See Also
       o true command

       o $status variable

   fg -	bring job to foreground
   Synopsis
	  fg [PID]

   Description
       fg brings the specified job to the foreground, resuming	it  if	it  is
       stopped.	 While	a foreground job is executed, fish is suspended. If no
       job is specified, the last job to be used is put	in the foreground.  If
       PID  is	specified,  the	 job  containing  a process with the specified
       process ID is put in the	foreground.

       For compatibility with other shells, job	expansion syntax is  supported
       for  fg.	 A PID of the format %1	will foreground	job 1. Job numbers can
       be seen in the output of	jobs.

   Example
       fg will put the last job	in the foreground.

       fg %3 will put job 3 into the foreground.

   fish	- the friendly interactive shell
   Synopsis
	  fish [OPTIONS] [-c command] [FILE] [ARGUMENTS...]

   Description
       fish is a command-line shell written mainly  with  interactive  use  in
       mind.  This  page  briefly describes the	options	for invoking fish. The
       full manual is available	in HTML	by using the help command from	inside
       fish,  and  in  the  fish-doc(1)	man page. The tutorial is available as
       HTML via	help tutorial or in fish-tutorial(1).

       The following options are available:

       o -c or --command=COMMANDS evaluate the specified commands  instead  of
	 reading from the commandline, passing any additional positional argu-
	 ments via $argv. Note that, unlike other shells, the  first  argument
	 is  not the name of the program ($0), but simply the first normal ar-
	 gument.

       o -C or --init-command=COMMANDS evaluate	the specified  commands	 after
	 reading the configuration, before running the command specified by -c
	 or reading interactive	input

       o -d or --debug=DEBUG_CATEGORIES	enable debug output and	specify	a pat-
	 tern for matching debug categories. See Debugging below for details.

       o -o  or	 --debug-output=DEBUG_FILE  specify a file path	to receive the
	 debug output, including categories and	 fish_trace.  The  default  is
	 stderr.

       o -i or --interactive specify that fish is to run in interactive	mode

       o -l or --login specify that fish is to run as a	login shell

       o -n  or	 --no-execute do not execute any commands, only	perform	syntax
	 checking

       o -p or --profile=PROFILE_FILE when fish	exits, output timing  informa-
	 tion  on  all	executed commands to the specified file. This excludes
	 time spent starting up	and reading the	configuration.

       o --profile-startup=PROFILE_FILE	 will  write  timing  information  for
	 fish's	 startup to the	specified file.	This is	useful to profile your
	 configuration.

       o -P or --private enables private mode, so fish will not	access old  or
	 store new history.

       o --print-rusage-self when fish exits, output stats from	getrusage

       o --print-debug-categories  outputs  the	 list of debug categories, and
	 then exits.

       o -v or --version display version and exit

       o -f or --features=FEATURES enables one or more	feature	 flags	(sepa-
	 rated by a comma). These are how fish stages changes that might break
	 scripts.

       The fish	exit status is generally the exit status  of  the  last	 fore-
       ground command.

   Debugging
       While fish provides extensive support for debugging fish	scripts, it is
       also possible to	debug and instrument its internals. Debugging  can  be
       enabled	by passing the --debug option. For example, the	following com-
       mand turns on debugging for background IO thread	events,	in addition to
       the default categories, i.e. debug, error, warning, and warning-path:

	  > fish --debug=iothread

       Available  categories  are listed by fish --print-debug-categories. The
       --debug option accepts a	comma-separated	list of	categories,  and  sup-
       ports  glob  syntax.  The following command turns on debugging for com-
       plete, history, history-file, and profile-history, as well as  the  de-
       fault categories:

	  > fish --debug='complete,*history*'

       Debug  messages output to stderr	by default. Note that if fish_trace is
       set, execution tracing also outputs to stderr by	default. You can  out-
       put to a	file using the --debug-output option:

	  > fish --debug='complete,*history*' --debug-output=/tmp/fish.log --init-command='set fish_trace on'

       These  options  can  also  be changed via the $FISH_DEBUG and $FISH_DE-
       BUG_OUTPUT variables. The categories enabled via	--debug	are  added  to
       the  ones  enabled by $FISH_DEBUG, so they can be disabled by prefixing
       them with - (reader-*,-ast* enables reader debugging and	 disables  ast
       debugging).

       The  file  given	 in  --debug-output  takes precedence over the file in
       $FISH_DEBUG_OUTPUT.

   fish_add_path - add to the path
   Synopsis
	  fish_add_path	[paths...]
	  fish_add_path	(-h | --help)
	  fish_add_path	[(-g | --global) | (-U | --universal) |	(-P | --path)] [(-m | --move)] [(-a | --append)	| (-p |	--prepend)] [(-v | --verbose) |	(-n | --dry-run)] [paths...]

   Description
       fish_add_path is	a simple way to	add more components to	fish's	$PATH.
       It does this by adding the components either to $fish_user_paths	or di-
       rectly to $PATH (if the --path switch is	given).

       It is (by default) safe to use fish_add_path in config.fish, or it  can
       be  used	once, interactively, and the paths will	stay in	future because
       of universal variables. This is a "do what I mean"  style  command,  if
       you need	more control, consider modifying the variable yourself.

       Components are normalized by realpath. This means that trailing slashes
       are ignored and relative	paths are made absolute	(but symlinks are  not
       resolved).  If  a  component  already exists, it	is not added again and
       stays in	the same place unless the --move switch	is given.

       Components are added  in	 the  order  they  are	given,	and  they  are
       prepended  to the path unless --append is given (if $fish_user_paths is
       used, that means	they are last in  $fish_user_paths,  which  is	itself
       prepended to $PATH, so they still stay ahead of the system paths).

       If no component is new, the variable ($fish_user_paths or $PATH)	is not
       set again or otherwise modified,	so variable  handlers  are  not	 trig-
       gered.

       If a component is not an	existing directory, fish_add_path ignores it.

   Options
       o -a  or	 --append  causes the components to be added to	the end	of the
	 variable

       o -p or --prepend causes	the components to be added to the front	of the
	 variable (this	is the default)

       o -g or --global	means to use a global $fish_user_paths

       o -U or --universal means to use	a universal $fish_user_paths - this is
	 the default if	it doesn't already exist

       o -P or --path means to use $PATH directly

       o -m or --move means to move already existing components	to  the	 place
	 they  would be	added -	by default they	would be left in place and not
	 added again

       o -v or --verbose means to print	the set	command	used

       o -n or --dry-run means to print	the set	command	 that  would  be  used
	 without executing it

       If --move is used, it may of course lead	to the path swapping order, so
       you should be careful doing that	in config.fish.

   Example
	  # I just installed mycoolthing and need to add it to the path	to use it.
	  > fish_add_path /opt/mycoolthing/bin

	  # I want my ~/.local/bin to be checked first.
	  > fish_add_path -m ~/.local/bin

	  # I prefer using a global fish_user_paths
	  > fish_add_path -g ~/.local/bin ~/.otherbin /usr/local/sbin

	  # I want to append to	the entire $PATH because this directory	contains fallbacks
	  > fish_add_path -aP /opt/fallback/bin

	  # I want to add the bin/ directory of	my current $PWD	(say /home/nemo/)
	  > fish_add_path -v bin/
	  set fish_user_paths /home/nemo/bin /usr/bin /home/nemo/.local/bin

	  # I have installed ruby via homebrew
	  > fish_add_path /usr/local/opt/ruby/bin

   fish_breakpoint_prompt - define the prompt when stopped at a	breakpoint
   Synopsis
	  function fish_breakpoint_prompt
	      ...
	  end

   Description
       fish_breakpoint_prompt is the prompt function when asking for input  in
       response	to a breakpoint	command.

       The exit	status of commands within fish_breakpoint_prompt will not mod-
       ify the value of	$status	outside	of  the	 fish_breakpoint_prompt	 func-
       tion.

       fish  ships  with  a default version of this function that displays the
       function	name and line number of	the current execution context.

   Example
       A simple	prompt that is a simplified version of the  default  debugging
       prompt:

	  function fish_breakpoint_prompt -d "Write out	the debug prompt"
	      set -l function (status current-function)
	      set -l line (status current-line-number)
	      set -l prompt "$function:$line >"
	      echo -ns (set_color $fish_color_status) "BP $prompt" (set_color normal) '	'
	  end

   fish_command_not_found - what to do when a command wasn't found
   Synopsis
	  function fish_command_not_found
	      ...
	  end

   Description
       When fish tries to execute a command and	can't find it, it invokes this
       function.

       It can print a message to tell you about	it, and	it often  also	checks
       for a missing package that would	include	the command.

       Fish  ships multiple handlers for various operating systems and chooses
       from them when this function is loaded, or you can define your own.

       It receives the full commandline	as one argument	per token, so $argv[1]
       contains	the missing command.

       When  you  leave	 fish_command_not_found	 undefined  (e.g. by adding an
       empty   function	  file)	  or   explicitly   call   __fish_default_com-
       mand_not_found_handler, fish will just print a simple error.

   Example
       A simple	handler:

	  function fish_command_not_found
	      echo Did not find	command	$argv[1]
	  end

	  > flounder
	  Did not find command flounder

       Or the handler for OpenSUSE's command-not-found:

	  function fish_command_not_found
	      /usr/bin/command-not-found $argv[1]
	  end

       Or the simple default handler:

	  function fish_command_not_found
	      __fish_default_command_not_found_handler $argv
	  end

   Backwards compatibility
       This  command  was  introduced in fish 3.2.0. Previous versions of fish
       used the	"fish_command_not_found" event instead.

       To define a handler that	works in older versions	of fish	as  well,  de-
       fine it the old way:

	  function __fish_command_not_found_handler --on-event fish_command_not_found
	       echo COMMAND WAS	NOT FOUND MY FRIEND $argv[1]
	  end

       in  which case fish will	define a fish_command_not_found	that calls it,
       or define a wrapper:

	  function fish_command_not_found
	       echo "G'day mate, could not find	your command: $argv"
	  end

	  function __fish_command_not_found_handler --on-event fish_command_not_found
	       fish_command_not_found $argv
	  end

   fish_config - start the web-based configuration interface
   Synopsis
	  fish_config
	  fish_config browse
	  fish_config prompt (choose | list | save | show)

   Description
       fish_config is used to configure	fish.

       Without arguments or with the browse command it	starts	the  web-based
       configuration  interface.  The  web  interface  allows you to view your
       functions, variables and	history, and to	make changes  to  your	prompt
       and  color  configuration.  It  starts  a  local	web server and opens a
       browser window. When you	are finished, close  the  browser  window  and
       press the Enter key to terminate	the configuration session.

       If the BROWSER environment variable is set, it will be used as the name
       of the web browser to open instead of the system	default.

       With the	prompt command fish_config can be used to view	and  choose  a
       prompt from fish's sample prompts inside	the terminal directly.

       Available subcommands for the prompt command:

       o choose	loads a	sample prompt in the current session.

       o list lists the	names of the available sample prompts.

       o save saves the	current	prompt to a file (via funcsave).

       o show shows what the given sample prompts (or all) would look like.

   Example
       fish_config  or	fish_config  browse opens a new	web browser window and
       allows you to configure certain fish settings.

       fish_config prompt show demos the available sample prompts.

       fish_config prompt choose disco makes the disco prompt the  prompt  for
       the  current  session.  This can	also be	used in	config.fish to set the
       prompt.

       fish_config prompt save saves the current prompt	to an autoloaded file.

       fish_config prompt save default chooses the default  prompt  and	 saves
       it.

   fish_git_prompt - output git	information for	use in a prompt
   Synopsis
	  function fish_prompt
	       printf '%s' $PWD	(fish_git_prompt) ' $ '
	  end

   Description
       The fish_git_prompt function displays information about the current git
       repository, if any.

       Git must	be installed.

       There are numerous customization	options, which can be controlled  with
       git  options  or	 fish  variables.  git	options, where available, take
       precedence over the fish	variable with the same function.  git  options
       can  be set on a	per-repository or global basis.	git options can	be set
       with the	git config command, while fish variables can be	set  as	 usual
       with the	set command.

       o $__fish_git_prompt_show_informative_status    or   the	  git	option
	 bash.showInformativeStatus can	be set	to  enable  the	 "informative"
	 display,  which  will show a large amount of information - the	number
	 of untracked files, dirty files, unpushed/unpulled commits, and more.
	 In  large  repositories,  this	 can take a lot	of time, so it you may
	 wish to disable it in these repositories  with	  git  config  --local
	 bash.showInformativeStatus  false. It also changes the	characters the
	 prompt	uses to	less plain ones	(^a instead of *	for  the  dirty	 state
	 for  example)	,  and	if  you	 are  only  interested	in  that,  set
	 $__fish_git_prompt_use_informative_chars instead.

       o $__fish_git_prompt_showdirtystate or the git option  bash.showDirtyS-
	 tate can be set to show if the	repository is "dirty", i.e. has	uncom-
	 mitted	changes.

       o $__fish_git_prompt_showuntrackedfiles or the git option  bash.showUn-
	 trackedFiles can be set to show if the	repository has untracked files
	 (that aren't ignored).

       o $__fish_git_prompt_showupstream can be	set to a list of values	to de-
	 termine how changes between HEAD and upstream are shown:

	    auto   summarize the difference between HEAD and its upstream

	    verbose
		   show	number of commits ahead/behind (+/-) upstream

	    name   if verbose, then also show the upstream abbrev name

	    informative
		   similar  to verbose,	but shows nothing when equal - this is
		   the default if informative status is	enabled.

	    git	   always compare HEAD to @{upstream}

	    svn	   always compare HEAD to your SVN upstream

	    none   disables (useful with informative status)

       o $__fish_git_prompt_showstashstate can be set to display the state  of
	 the stash.

       o $__fish_git_prompt_shorten_branch_len	can  be	 set  to the number of
	 characters that the branch name will be shortened to.

       o $__fish_git_prompt_describe_style can be set to one of	the  following
	 styles	to describe the	current	HEAD:

	    contains
		   relative to newer annotated tag, such as (v1.6.3.2~35)

	    branch relative to newer tag or branch, such as (master~4)

	    describe
		   relative	to    older    annotated    tag,    such    as
		   (v1.6.3.1-13-gdd42c2f)

	    default
		   an exactly matching tag ((develop))

	    If none of these apply, the	commit SHA shortened to	 8  characters
	    is used.

       o $__fish_git_prompt_showcolorhints  can	 be set	to enable coloring for
	 the branch name and status symbols.

       A number	of variables set characters and	color used as indicators. Many
       of  these  have a different default if used with	informative status en-
       abled, or $__fish_git_prompt_use_informative_chars set. The  usual  de-
       fault  is  given	 first,	then the informative default (if it is differ-
       ent).  If  no  default  for  the	 colors	 is  given,  they  default  to
       $__fish_git_prompt_color.

       o $__fish_git_prompt_char_stateseparator	(' ', |) - the character to be
	 used between the state	characters

       o $__fish_git_prompt_color (no default)

       o $__fish_git_prompt_color_prefix - the color of	the ( prefix

       o $__fish_git_prompt_color_suffix - the color of	the ) suffix

       o $__fish_git_prompt_color_bare - the color to use for a	 bare  reposi-
	 tory -	one without a working tree

       o $__fish_git_prompt_color_merging  - the color when a merge/rebase/re-
	 vert/bisect or	cherry-pick is in progress

       Some variables are only used in some modes, like	when informative  sta-
       tus is enabled:

       o $__fish_git_prompt_char_cleanstate  (a)  -  the  character to be used
	 when nothing else applies

       o $__fish_git_prompt_color_cleanstate

       Variables used with showdirtystate:

       o $__fish_git_prompt_char_dirtystate (*,	a) -  the  number  of  "dirty"
	 changes, i.e. unstaged	files with changes

       o $__fish_git_prompt_char_invalidstate  (#,  a)	-  the	number of "un-
	 merged" changes, e.g. additional changes to already added files

       o $__fish_git_prompt_char_stagedstate (+, a) -  the  number  of	staged
	 files without additional changes

       o $__fish_git_prompt_color_dirtystate (red with showcolorhints, same as
	 color_flags otherwise)

       o $__fish_git_prompt_color_invalidstate

       o $__fish_git_prompt_color_stagedstate  (green	with   showcolorhints,
	 color_flags otherwise)

       Variables used with showstashstate:

       o $__fish_git_prompt_char_stashstate ($,	a)

       o $__fish_git_prompt_color_stashstate (same as color_flags)

       Variables used with showuntrackedfiles:

       o $__fish_git_prompt_char_untrackedfiles	 (%,  a|) - the	symbol for un-
	 tracked files

       o $__fish_git_prompt_color_untrackedfiles (same as color_flags)

       Variables used with showupstream	(also implied by informative status):

       o $__fish_git_prompt_char_upstream_ahead	(>, a) - the character for the
	 commits this repository is ahead of upstream

       o $__fish_git_prompt_char_upstream_behind  (<,  a)  - the character for
	 the commits this repository is	behind upstream

       o $__fish_git_prompt_char_upstream_diverged (<>)	- the symbol  if  this
	 repository is both ahead and behind upstream

       o $__fish_git_prompt_char_upstream_equal	 (=) - the symbol if this repo
	 is equal to upstream

       o $__fish_git_prompt_char_upstream_prefix ('')

       o $__fish_git_prompt_color_upstream

       Colors used with	showcolorhints:

       o $__fish_git_prompt_color_branch (green) - the color of	the branch

       o $__fish_git_prompt_color_branch_detached  (red)  the  color  of   the
	 branch	if it's	detached (e.g. a commit	is checked out)

       o $__fish_git_prompt_color_flags	 (--bold blue) - the default color for
	 dirty/staged/stashed/untracked	state

       Note that all colors can	also have a corresponding _done	color. For ex-
       ample,	the   contents	of  $__fish_git_prompt_color_upstream_done  is
       printed right _after_ the upstream.

       See also	fish_vcs_prompt, which will call all supported version control
       prompt functions, including git,	Mercurial and Subversion.

   Example
       A simple	prompt that displays git info:

	  function fish_prompt
	      #	...
	      set -g __fish_git_prompt_showupstream auto
	      printf '%s %s$' $PWD (fish_git_prompt)
	  end

   fish_greeting - display a welcome message in	interactive shells
   Synopsis
	  function fish_greeting
	      ...
	  end

   Description
       When an interactive fish	starts,	it executes fish_greeting and displays
       its output.

       The default fish_greeting is a function that prints a variable  of  the
       same  name  ($fish_greeting),  so  you can also just change that	if you
       just want to change the text.

       While you could also just put echo calls	into config.fish,  fish_greet-
       ing takes care of only being used in interactive	shells,	so it won't be
       used e.g. with scp (which executes a shell), which  prevents  some  er-
       rors.

   Example
       A simple	greeting:

	  function fish_greeting
	      echo Hello friend!
	      echo The time is (set_color yellow; date +%T; set_color normal) and this machine is called $hostname
	  end

   fish_hg_prompt - output Mercurial information for use in a prompt
   Synopsis
	  function fish_prompt
	       printf '%s' $PWD	(fish_hg_prompt) ' $ '
	  end

   Description
       The fish_hg_prompt function displays information	about the current Mer-
       curial repository, if any.

       Mercurial (hg) must be installed.

       By default, only	the current branch is shown because hg status  can  be
       slow on a large repository. You can enable a more informative prompt by
       setting the variable $fish_prompt_hg_show_informative_status, for exam-
       ple:

	  set --universal fish_prompt_hg_show_informative_status

       If you enabled the informative status, there are	numerous customization
       options,	which can be controlled	with fish variables.

       o $fish_color_hg_clean,		 $fish_color_hg_modified	   and
	 $fish_color_hg_dirty  are colors used when the	repository has the re-
	 spective status.

       Some colors for status symbols:

       o $fish_color_hg_added

       o $fish_color_hg_renamed

       o $fish_color_hg_copied

       o $fish_color_hg_deleted

       o $fish_color_hg_untracked

       o $fish_color_hg_unmerged

       The status symbols themselves:

       o $fish_prompt_hg_status_added, default 'a'

       o $fish_prompt_hg_status_modified, default '*'

       o $fish_prompt_hg_status_copied,	default	'a'

       o $fish_prompt_hg_status_deleted, default 'a'

       o $fish_prompt_hg_status_untracked, default '?'

       o $fish_prompt_hg_status_unmerged, default '!'

       Finally,	$fish_prompt_hg_status_order, which can	be used	to change  the
       order  the  status  symbols  appear  in.	 It defaults to	added modified
       copied deleted untracked	unmerged.

       See also	fish_vcs_prompt, which will call all supported version control
       prompt functions, including git,	Mercurial and Subversion.

   Example
       A simple	prompt that displays hg	info:

	  function fish_prompt
	      ...
	      set -g fish_prompt_hg_show_informative_status
	      printf '%s %s$' $PWD (fish_hg_prompt)
	  end

   fish_indent - indenter and prettifier
   Synopsis
	  fish_indent [OPTIONS]	[FILE...]

   Description
       fish_indent  is	used to	indent a piece of fish code. fish_indent reads
       commands	from standard input or the given filenames and outputs them to
       standard	output or a specified file (if -w is given).

       The following options are available:

       o -w or --write indents a specified file	and immediately	writes to that
	 file.

       o -i or --no-indent do not indent commands; only	reformat  to  one  job
	 per line.

       o -c or --check do not indent, only return 0 if the code	is already in-
	 dented	as fish_indent would, the number of  failed  files  otherwise.
	 Also print the	failed filenames if not	reading	from stdin.

       o -v or --version displays the current fish version and then exits.

       o --ansi	 colorizes the output using ANSI escape	sequences, appropriate
	 for the current $TERM,	using the colors defined  in  the  environment
	 (such as $fish_color_command).

       o --html	outputs	HTML, which supports syntax highlighting if the	appro-
	 priate	CSS is defined.	The CSS	class names are	the same as the	 vari-
	 able names, such as fish_color_command.

       o -d or --debug=DEBUG_CATEGORIES	enable debug output and	specify	a pat-
	 tern for matching debug categories. See Debugging in fish(1) for  de-
	 tails.

       o -o  or	 --debug-output=DEBUG_FILE  specify a file path	to receive the
	 debug output, including categories and	 fish_trace.  The  default  is
	 stderr.

       o --dump-parse-tree  dumps  information	about the parsed statements to
	 stderr. This is likely	to be of interest only to  people  working  on
	 the fish source code.

   fish_is_root_user - check if	the current user is root
   Synopsis
	  fish_is_root_user

   Description
       fish_is_root_user  will	check  if  the current user is root. It	can be
       useful for the prompt to	display	something different  if	 the  user  is
       root, for example.

   Example
       A simple	example:

	  function example --description 'Just an example'
	      if fish_is_root_user
		  do_something_different
	      end
	  end

   fish_key_reader - explore what characters keyboard keys send
   Synopsis
	  fish_key_reader [OPTIONS]

   Description
       fish_key_reader	is  used to study input	received from the terminal and
       can help	with key binds.	The program is interactive and works on	 stan-
       dard input. Individual characters themselves and	their hexadecimal val-
       ues are displayed.

       The tool	will write an example bind command matching the	character  se-
       quence  captured	to stdout. If the character sequence matches a special
       key name	(see bind --key-names),	 both bind CHARS ... and bind -k  KEY-
       NAME  ...  usage	will be	shown. Additional details about	the characters
       received, such as the delay between chars, are written to stderr.

       The following options are available:

       o -c or --continuous begins a session where multiple key	sequences  can
	 be  inspected.	 By default the	program	exits after capturing a	single
	 key sequence.

       o -h or --help prints usage information.

       o -v or --version prints	fish_key_reader's version and exits.

   Usage Notes
       The delay in milliseconds since the previous character was received  is
       included	in the diagnostic information written to stderr. This informa-
       tion may	be useful to determine the optimal  fish_escape_delay_ms  set-
       ting  or	 learn the amount of lag introduced by tools like ssh, mosh or
       tmux.

       fish_key_reader intentionally disables handling	of  many  signals.  To
       terminate fish_key_reader in --continuous mode do:

       o press Control+C twice,	or

       o press Control+D twice,	or

       o type exit, or

       o type quit

   fish_mode_prompt - define the appearance of the mode	indicator
   Synopsis
	  function fish_mode_prompt
	       echo -n "$fish_bind_mode	"
	  end

   Description
       The  fish_mode_prompt  function	outputs	 the mode indicator for	use in
       vi-mode.

       The default fish_mode_prompt function will output indicators about  the
       current Vi editor mode displayed	to the left of the regular prompt. De-
       fine your own function to customize the appearance of the mode  indica-
       tor.  The $fish_bind_mode variable can be used to determine the current
       mode. It	will be	one of default,	insert,	replace_one, or	visual.

       You can also define an empty fish_mode_prompt function to remove	the Vi
       mode indicators:

	  function fish_mode_prompt; end
	  funcsave fish_mode_prompt

       fish_mode_prompt	 will be executed when the vi mode changes. If it pro-
       duces any output, it is displayed and used. If it does not,  the	 other
       prompt  functions  (fish_prompt and fish_right_prompt) will be executed
       as well in case they contain a mode display.

   Example
	  function fish_mode_prompt
	    switch $fish_bind_mode
	      case default
		set_color --bold red
		echo 'N'
	      case insert
		set_color --bold green
		echo 'I'
	      case replace_one
		set_color --bold green
		echo 'R'
	      case visual
		set_color --bold brmagenta
		echo 'V'
	      case '*'
		set_color --bold red
		echo '?'
	    end
	    set_color normal
	  end

       Outputting multiple lines is not	supported in fish_mode_prompt.

   fish_opt - create an	option spec for	the argparse command
   Synopsis
	  fish_opt [ -h	| --help ]
	  fish_opt ( -s	X | --short=X )	[ -l LONG | --long=LONG	] [ --long-only	] [ -o | --optional-val	] [ -r | --required-val	] [ --multiple-vals ]

   Description
       This command provides a way to produce option  specifications  suitable
       for use with the	argparse command. You can, of course, write the	option
       specs by	hand without using this	command. But you might prefer  to  use
       this for	the clarity it provides.

       The following argparse options are available:

       o -s or --short takes a single letter that is used as the short flag in
	 the option being defined. This	option is mandatory.

       o -l or --long takes a string that is used as the long flag in the  op-
	 tion being defined. This option is optional and has no	default. If no
	 long flag is defined then only	the short flag will  be	 allowed  when
	 parsing arguments using the option spec.

       o --long-only  means  the option	spec being defined will	only allow the
	 long flag name	to be used. The	short flag name	must still be  defined
	 (i.e.,	 --short must be specified) but	it cannot be used when parsing
	 args using this option	spec.

       o -o or --optional-val means the	option being defined can take a	 value
	 but  it  is optional rather than required. If the option is seen more
	 than once when	parsing	arguments only the last	value seen  is	saved.
	 This  means the resulting flag	variable created by argparse will zero
	 elements if no	value was given	with the option	else it	will have  ex-
	 actly one element.

       o -r or --required-val means the	option being defined requires a	value.
	 If the	option is seen more than once when parsing arguments only  the
	 last value seen is saved. This	means the resulting flag variable cre-
	 ated by argparse will have exactly one	element.

       o --multiple-vals means the option being	defined	requires a value  each
	 time  it  is  seen. Each instance is stored. This means the resulting
	 flag variable created by argparse will	have one element for each  in-
	 stance	of this	option in the args.

       o -h or --help displays help about using	this command.

   Examples
       Define a	single option spec for the boolean help	flag:

	  set -l options (fish_opt -s h	-l help)
	  argparse $options -- $argv

       Same as above but with a	second flag that requires a value:

	  set -l options (fish_opt -s h	-l help)
	  set options $options (fish_opt -s m -l max --required-val)
	  argparse $options -- $argv

       Same  as	 above	but with a third flag that can be given	multiple times
       saving the value	of each	instance seen and  only	 the  long  flag  name
       (--token) can be	used:

	  set -l options (fish_opt --short=h --long=help)
	  set options $options (fish_opt --short=m --long=max --required-val)
	  set options $options (fish_opt --short=t --long=token	--multiple-vals	--long-only)
	  argparse $options -- $argv

   fish_prompt - define	the appearance of the command line prompt
   Synopsis
	  function fish_prompt
	      ...
	  end

   Description
       The  fish_prompt	 function  is executed when the	prompt is to be	shown,
       and the output is used as a prompt.

       The exit	status of commands within  fish_prompt	will  not  modify  the
       value of	$status	outside	of the fish_prompt function.

       fish ships with a number	of example prompts that	can be chosen with the
       fish_config command.

   Example
       A simple	prompt:

	  function fish_prompt -d "Write out the prompt"
	      #	This shows up as USER@HOST /home/user/ >, with the directory colored
	      #	$USER and $hostname are	set by fish, so	you can	just use them
	      #	instead	of using `whoami` and `hostname`
	      printf '%s@%s %s%s%s > ' $USER $hostname \
		  (set_color $fish_color_cwd) (prompt_pwd) (set_color normal)
	  end

   fish_right_prompt - define the appearance of	the  right-side	 command  line
       prompt
   Synopsis
	  function fish_right_prompt
	      ...
	  end

   Description
       fish_right_prompt  is similar to	fish_prompt, except that it appears on
       the right side of the terminal window.

       Multiple	lines are not supported	in fish_right_prompt.

   Example
       A simple	right prompt:

	  function fish_right_prompt -d	"Write out the right prompt"
	      date '+%m/%d/%y'
	  end

   fish_status_to_signal - Convert exit	codes to human-friendly	signals
   Synopsis
	  function fish_prompt
	      echo -n (fish_status_to_signal $pipestatus | string join '|') (prompt_pwd) '$ '
	  end

   Description
       fish_status_to_signal converts exit codes to  their  corresponding  hu-
       man-friendly  signals  if  one exists.  This is likely to be useful for
       prompts in conjunction with the $status and $pipestatus variables.

   Example
	  >_ sleep 5
	  ^Ca
	  >_ fish_status_to_signal $status
	  SIGINT

   fish_svn_prompt - output Subversion information for use in a	prompt
   Synopsis
	  function fish_prompt
	       printf '%s' $PWD	(fish_svn_prompt) ' $ '
	  end

   Description
       The fish_svn_prompt function displays  information  about  the  current
       Subversion repository, if any.

       Subversion (svn)	must be	installed.

       There  are numerous customization options, which	can be controlled with
       fish variables.

       o

	 $__fish_svn_prompt_color_revision
		the colour of the revision number to display in	the prompt

       o

	 $__fish_svn_prompt_char_separator
		the separator between status characters

       A  number  of  variables	 control  the  symbol  ("display")  and	 color
       ("color") for the different status indicators:

       o $__fish_svn_prompt_char_added_display

       o $__fish_svn_prompt_char_added_color

       o $__fish_svn_prompt_char_conflicted_display

       o $__fish_svn_prompt_char_conflicted_color

       o $__fish_svn_prompt_char_deleted_display

       o $__fish_svn_prompt_char_deleted_color

       o $__fish_svn_prompt_char_ignored_display

       o $__fish_svn_prompt_char_ignored_color

       o $__fish_svn_prompt_char_modified_display

       o $__fish_svn_prompt_char_modified_color

       o $__fish_svn_prompt_char_replaced_display

       o $__fish_svn_prompt_char_replaced_color

       o $__fish_svn_prompt_char_unversioned_external_display

       o $__fish_svn_prompt_char_unversioned_external_color

       o $__fish_svn_prompt_char_unversioned_display

       o $__fish_svn_prompt_char_unversioned_color

       o $__fish_svn_prompt_char_missing_display

       o $__fish_svn_prompt_char_missing_color

       o $__fish_svn_prompt_char_versioned_obstructed_display

       o $__fish_svn_prompt_char_versioned_obstructed_color

       o $__fish_svn_prompt_char_locked_display

       o $__fish_svn_prompt_char_locked_color

       o $__fish_svn_prompt_char_scheduled_display

       o $__fish_svn_prompt_char_scheduled_color

       o $__fish_svn_prompt_char_switched_display

       o $__fish_svn_prompt_char_switched_color

       o $__fish_svn_prompt_char_token_present_display

       o $__fish_svn_prompt_char_token_present_color

       o $__fish_svn_prompt_char_token_other_display

       o $__fish_svn_prompt_char_token_other_color

       o $__fish_svn_prompt_char_token_stolen_display

       o $__fish_svn_prompt_char_token_stolen_color

       o $__fish_svn_prompt_char_token_broken_display

       o $__fish_svn_prompt_char_token_broken_color

       See also	fish_vcs_prompt, which will call all supported version control
       prompt functions, including git,	Mercurial and Subversion.

   Example
       A simple	prompt that displays svn info:

	  function fish_prompt
	      ...
	      printf '%s %s$' $PWD (fish_svn_prompt)
	  end

   fish_title -	define the terminal's title
   Synopsis
	  function fish_title
	      ...
	  end

   Description
       The fish_title function is executed before and after a new  command  is
       executed	 or put	into the foreground and	the output is used as a	title-
       bar message.

       The first argument to fish_title	contains the  most  recently  executed
       foreground command as a string, if any.

       This  requires  that your terminal supports programmable	titles and the
       feature is turned on.

   Example
       A simple	title:

	  function fish_title
	      set -q argv[1]; or set argv fish
	      #	Looks like ~/d/fish: git log
	      #	or /e/apt: fish
	      echo (fish_prompt_pwd_dir_length=1 prompt_pwd): $argv;
	  end

   fish_update_completions - update completions	using manual pages
   Synopsis
	  fish_update_completions

   Description
       fish_update_completions parses manual pages installed  on  the  system,
       and  attempts  to create	completion files in the	fish configuration di-
       rectory.

       This does not overwrite custom completions.

       There are no parameters for fish_update_completions.

   fish_vcs_prompt - output version control system information for  use	 in  a
       prompt
   Synopsis
	  function fish_prompt
	       printf '%s' $PWD	(fish_vcs_prompt) ' $ '
	  end

   Description
       The  fish_vcs_prompt  function  displays	 information about the current
       version control system (VCS) repository,	if any.

       It calls	out to VCS-specific functions. The currently supported systems
       are:

       o fish_git_prompt

       o fish_hg_prompt

       o fish_svn_prompt

       If a VCS	isn't installed, the respective	function does nothing.

       The  svn	 prompt	 is disabled by	default	because	it's slow on large svn
       repositories. To	enable it, modify fish_vcs_prompt to uncomment it. See
       funced.

       For  more  information, see the documentation for each of the functions
       above.

   Example
       A simple	prompt that displays all known VCS info:

	  function fish_prompt
	      ...
	      set -g __fish_git_prompt_showupstream auto
	      printf '%s %s$' $PWD (fish_vcs_prompt)
	  end

   for - perform a set of commands multiple times
   Synopsis
	  for VARNAME in [VALUES...]; COMMANDS...; end

   Description
       for is a	loop construct.	It will	perform	the commands specified by COM-
       MANDS  multiple	times. On each iteration, the local variable specified
       by VARNAME is assigned a	new value from VALUES.	If  VALUES  is	empty,
       COMMANDS	 will  not be executed at all. The VARNAME is visible when the
       loop terminates and will	contain	the last value assigned	to it. If VAR-
       NAME  does not already exist it will be set in the local	scope. For our
       purposes	if the for block is inside a function there must  be  a	 local
       variable	 with  the  same name. If the for block	is not nested inside a
       function	then global and	universal variables of the same	name  will  be
       used if they exist.

   Example
	  for i	in foo bar baz;	echo $i; end

	  # would output:
	  foo
	  bar
	  baz

   Notes
       The VARNAME was local to	the for	block in releases prior	to 3.0.0. This
       means that if you did something like this:

	  for var in a b c
	      if break_from_loop
		  break
	      end
	  end
	  echo $var

       The last	value assigned to var when the loop terminated	would  not  be
       available outside the loop. What	echo $var would	write depended on what
       it was set to before the	loop was run. Likely nothing.

   funced - edit a function interactively
   Synopsis
	  funced [OPTIONS] NAME

   Description
       funced provides an interface to edit the	 definition  of	 the  function
       NAME.

       If the $VISUAL environment variable is set, it will be used as the pro-
       gram to edit the	function. If $VISUAL is	unset but $EDITOR is set, that
       will  be	 used. Otherwise, a built-in editor will be used. Note that to
       enter a literal newline using the  built-in  editor  you	 should	 press
       Alt+Enter.  Pressing  Enter signals that	you are	done editing the func-
       tion. This does not apply to an external	editor like emacs or vim.

       If there	is no function called NAME a new function will be created with
       the specified name

       o -e command or --editor	command	Open the function body inside the text
	 editor	given by the command (for example, -e vi). The special command
	 fish will use the built-in editor (same as specifying -i).

       o -i  or	 --interactive Force opening the function body in the built-in
	 editor	even if	$VISUAL	or $EDITOR is defined.

       o -s or --save Automatically save the function after successfully edit-
	 ing it.

   Example
       Say you want to modify your prompt.

       Run:

	  >_ funced fish_prompt

       This  will  open	 up  your editor, allowing you to modify the function.
       When you're done, save and quit.	Fish will reload the function, so  you
       should see the changes right away.

       When you're done, use:

	  >_ funcsave fish_prompt

       For more, see funcsave.

   funcsave  - save the	definition of a	function to the	user's autoload	direc-
       tory
   Synopsis
	  funcsave FUNCTION_NAME
	  funcsave [(-d	| --directory) where/to/save ] FUNCTION_NAME

   Description
       funcsave	saves a	function to a file in the  fish	 configuration	direc-
       tory.  This function will be automatically loaded by current and	future
       fish sessions. This can be useful if you	have interactively  created  a
       new function and	wish to	save it	for later use.

       Note  that because fish loads functions on-demand, saved	functions will
       not function as event handlers until they are run or sourced otherwise.
       To  activate  an	event handler for every	new shell, add the function to
       your configuration file instead of using	funcsave.

       This is typically used together with funced, which will open the	 func-
       tion in your editor and load it in the current seession afterwards.

   function - create a function
   Synopsis
	  function NAME	[OPTIONS]; BODY; end

   Description
       function	creates	a new function NAME with the body BODY.

       A function is a list of commands	that will be executed when the name of
       the function is given as	a command.

       The following options are available:

       o -a NAMES or --argument-names NAMES assigns the	 value	of  successive
	 command-line arguments	to the names given in NAMES.

       o -d  DESCRIPTION or --description=DESCRIPTION is a description of what
	 the function does, suitable as	a completion description.

       o -w WRAPPED_COMMAND or --wraps=WRAPPED_COMMAND causes the function  to
	 inherit  completions from the given wrapped command. See the documen-
	 tation	for complete for more information.

       o -e or --on-event EVENT_NAME tells fish	to run this function when  the
	 specified  named  event  is  emitted. Fish internally generates named
	 events	e.g. when showing the prompt.

       o -v or --on-variable VARIABLE_NAME tells fish  to  run	this  function
	 when  the  variable VARIABLE_NAME changes value. Note that fish makes
	 no guarantees on any particular timing	or even	that the function will
	 be  run for every single set. Rather it will be run when the variable
	 has been set at least once, possibly skipping some  values  or	 being
	 run when the variable has been	set to the same	value (except for uni-
	 versal	variables set in other shells -	only changes in	the value will
	 be picked up for those).

       o -j  PID or --on-job-exit PID tells fish to run	this function when the
	 job containing	a child	process	with the given PID exits.  Instead  of
	 PID, the string 'caller' can be specified. This is only legal when in
	 a command substitution, and will result in the	 handler  being	 trig-
	 gered by the exit of the job which created this command substitution.

       o -p  PID or --on-process-exit PID tells	fish to	run this function when
	 the fish child	process	with process ID	PID exits. Instead of  a  PID,
	 for  backward compatibility, "%self" can be specified as an alias for
	 $fish_pid, and	the function will be run when  the  current  fish  in-
	 stance	exits.

       o -s  or	 --on-signal  SIGSPEC tells fish to run	this function when the
	 signal	SIGSPEC	is delivered. SIGSPEC can be a signal number,  or  the
	 signal	name, such as SIGHUP (or just HUP).

       o -S  or	 --no-scope-shadowing  allows the function to access the vari-
	 ables of calling functions. Normally, any variables inside the	 func-
	 tion  that  have the same name	as variables from the calling function
	 are "shadowed", and their contents are	 independent  of  the  calling
	 function.   It's  important to	note that this does not	capture	refer-
	 enced variables or the	scope at the time of function declaration!  At
	 this  time,  fish does	not have any concept of	closures, and variable
	 lifetimes  are	  never	  extended.   In   other   words,   by	 using
	 --no-scope-shadowing the scope	of the function	each time it is	run is
	 shared	with the scope it was called from rather than the scope	it was
	 defined in.

       o -V  or	 --inherit-variable  NAME  snapshots the value of the variable
	 NAME and defines a local variable with	that same name and value  when
	 the  function	is defined. This is similar to a closure in other lan-
	 guages	like Python but	a bit different. Note the word	"snapshot"  in
	 the  first  sentence.	If  you	change the value of the	variable after
	 defining the function,	even if	you do so in the same scope (typically
	 another  function) the	new value will not be used by the function you
	 just created using this option. See the function notify example below
	 for how this might be used.

       If  the	user  enters any additional arguments after the	function, they
       are inserted into the environment variable list $argv. If  the  --argu-
       ment-names option is provided, the arguments are	also assigned to names
       specified in that option.

       By using	one of the event handler switches, a function can be  made  to
       run  automatically at specific events. The user may generate new	events
       using the emit builtin. Fish generates the following named events:

       o fish_prompt, which is emitted whenever	a new fish prompt is about  to
	 be displayed.

       o fish_preexec,	which is emitted right before executing	an interactive
	 command. The commandline is passed as the first parameter. Not	 emit-
	 ted if	command	is empty.

       o fish_posterror, which is emitted right	after executing	a command with
	 syntax	errors.	The commandline	is passed as the first parameter.

       o fish_postexec,	which is emitted right after executing an  interactive
	 command.  The commandline is passed as	the first parameter. Not emit-
	 ted if	command	is empty.

       o fish_exit is emitted right before fish	exits.

       o fish_cancel, which is emitted when a commandline is cleared (used for
	 terminal-shell	integration).

   Example
	  function ll
	      ls -l $argv
	  end

       will  run the ls	command, using the -l option, while passing on any ad-
       ditional	files and switches to ls.

	  function mkdir -d "Create a directory	and set	CWD"
	      command mkdir $argv
	      if test $status =	0
		  switch $argv[(count $argv)]
		      case '-*'

		      case '*'
			  cd $argv[(count $argv)]
			  return
		  end
	      end
	  end

       This will run the mkdir command,	and if it is  successful,  change  the
       current working directory to the	one just created.

	  function notify
	      set -l job (jobs -l -g)
	      or begin;	echo "There are	no jobs" >&2; return 1;	end

	      function _notify_job_$job	--on-job-exit $job --inherit-variable job
		  echo -n \a # beep
		  functions -e _notify_job_$job
	      end
	  end

       This will beep when the most recent job completes.

   Notes
       Events  are  only received from the current fish	process	as there is no
       way to send events from one fish	process	to another.

   See more
       For more	explanation of how functions fit into fish, see	Functions.

   functions - print or	erase functions
   Synopsis
	  functions [ -a | --all ] [ -n	| --names ]
	  functions [ -D | --details ] [ -v ] FUNCTION
	  functions -c OLDNAME NEWNAME
	  functions -d DESCRIPTION FUNCTION
	  functions [ -e | -q ]	FUNCTIONS...

   Description
       functions prints	or erases functions.

       The following options are available:

       o -a or --all lists all functions, even those whose name	starts with an
	 underscore.

       o -c  OLDNAME  NEWNAME or --copy	OLDNAME	NEWNAME	creates	a new function
	 named NEWNAME,	using the definition of	the OLDNAME function.

       o -d DESCRIPTION	or --description=DESCRIPTION changes  the  description
	 of this function.

       o -e  or	--erase	causes the specified functions to be erased. This also
	 means that it is prevented from autoloading.

       o -D or --details reports the path name where the specified function is
	 defined or could be autoloaded, stdin if the function was defined in-
	 teractively or	on the command line or by  reading  stdin,  -  if  the
	 function was created via source, and n/a if the function isn't	avail-
	 able. (Functions created via alias will return	-, because alias  uses
	 source	 internally.)  If  the --verbose option	is also	specified then
	 five lines are	written:

	    o the pathname as already described,

	    o autoloaded, not-autoloaded or n/a,

	    o the line number within the file or zero if not applicable,

	    o scope-shadowing if the function shadows the vars in the  calling
	      function	 (the	normal	 case	if   it	 wasn't	 defined  with
	      --no-scope-shadowing), else no-scope-shadowing, or  n/a  if  the
	      function isn't defined,

	    o the  function  description  minimally  escaped so	it is a	single
	      line or n/a if the function isn't	defined.

       You should not assume that only five lines will be written since	we may
       add additional information to the output	in the future.

       o --no-details  turns  off function path	reporting, so just the defini-
	 tion will be printed.

       o -n or --names lists the names of all defined functions.

       o -q or --query tests if	the specified functions	exist.

       o -v or --verbose will make some	output more verbose.

       o -H or --handlers will show all	event handlers.

       o -t or --handlers-type TYPE will show all event	handlers matching  the
	 given type

       The default behavior of functions, when called with no arguments, is to
       print the names of all defined  functions.  Unless  the	-a  option  is
       given,  no functions starting with underscores are included in the out-
       put.

       If any non-option parameters are	given, the definition of the specified
       functions are printed.

       Copying	a  function using -c copies only the body of the function, and
       does not	attach any event notifications from the	original function.

       Only one	function's description can be changed in a  single  invocation
       of functions -d.

       The  exit  status  of functions is the number of	functions specified in
       the argument list that do not exist, which can be used in concert  with
       the -q option.

   Examples
	  functions -n
	  # Displays a list of currently-defined functions

	  functions -c foo bar
	  # Copies the 'foo' function to a new function	called 'bar'

	  functions -e bar
	  # Erases the function	``bar``

   See more
       For more	explanation of how functions fit into fish, see	Functions.

   help	- display fish documentation
   Synopsis
	  help [SECTION]

   Description
       help displays the fish help documentation.

       If a SECTION is specified, the help for that command is shown.

       If  the BROWSER environment variable is set, it will be used to display
       the documentation. Otherwise, fish will search for a suitable browser.

       If you prefer to	use a  different  browser  (other  than	 as  described
       above)  for fish	help, you can set the fish_help_browser	variable. This
       variable	may be set as a	list, where the	first element is  the  browser
       command and the rest are	browser	options.

       Note that most builtin commands display their help in the terminal when
       given the --help	option.

   Example
       help fg shows the documentation for the fg builtin.

   history - show and manipulate command history
   Synopsis
	  history [ search ] [ --show-time ] [ --case-sensitive	] [ --exact | --prefix | --contains ] [	--max=n	] [ --null ] [ -R | --reverse ]	[ "search string"... ]
	  history delete [ --show-time ] [ --case-sensitive ] [	--exact	| --prefix | --contains	] "search string"...
	  history merge
	  history save
	  history clear
	  history ( -h | --help	)

   Description
       history is used to search, delete, and otherwise	manipulate the history
       of interactive commands.

       The following operations	(sub-commands) are available:

       o search	returns	history	items matching the search string. If no	search
	 string	is provided it returns all history items. This is the  default
	 operation  if	no  other operation is specified. You only have	to ex-
	 plicitly say history search if	you wish to search for one of the sub-
	 commands.  The	 --contains  search  option  will be used if you don't
	 specify a different search option. Entries are	ordered	newest to old-
	 est unless you	use the	--reverse flag.	If stdout is attached to a tty
	 the output will be piped through your pager by	the history  function.
	 The history builtin simply writes the results to stdout.

       o delete	 deletes  history  items. The --contains search	option will be
	 used if you don't specify a different search  option.	If  you	 don't
	 specify  --exact  a  prompt  will  be	displayed before any items are
	 deleted asking	you which entries are to be deleted. You can enter the
	 word  "all" to	delete all matching entries. You can enter a single ID
	 (the number in	square brackets) to delete just	that single entry. You
	 can  enter  more  than	one ID separated by a space to delete multiple
	 entries. Just press [enter] to	not delete anything. Note that the in-
	 teractive  delete  behavior is	a feature of the history function. The
	 history builtin only supports --exact --case-sensitive	deletion.

       o merge immediately incorporates	history	changes	from  other  sessions.
	 Ordinarily  fish  ignores history changes from	sessions started after
	 the current one. This command applies those changes immediately.

       o save immediately writes all changes to	the history  file.  The	 shell
	 automatically saves the history file; this option is provided for in-
	 ternal	use and	should not normally need to be used by the user.

       o clear clears the history file.	A prompt is displayed before the  his-
	 tory  is  erased  asking  you to confirm you really want to clear all
	 history unless	builtin	history	is used.

       The following options are available:

       These flags can appear before or	immediately after one of the  sub-com-
       mands listed above.

       o -C  or	 --case-sensitive does a case-sensitive	search.	The default is
	 case-insensitive. Note	that prior  to	fish  2.4.0  the  default  was
	 case-sensitive.

       o -c  or	 --contains searches or	deletes	items in the history that con-
	 tain the specified text string. This is the default for the  --search
	 flag. This is not currently supported by the delete subcommand.

       o -e  or	 --exact searches or deletes items in the history that exactly
	 match the specified text string. This is the default for  the	delete
	 subcommand.  Note  that  the match is case-insensitive	by default. If
	 you really want an exact match, including letter case,	you  must  use
	 the -C	or --case-sensitive flag.

       o -p  or	 --prefix  searches or deletes items in	the history that begin
	 with the specified text string. This is not  currently	 supported  by
	 the --delete flag.

       o -t  or	--show-time prepends each history entry	with the date and time
	 the entry was recorded. By default it	uses  the  strftime  format  #
	 %c%n.	You  can  specify  another format; e.g., --show-time="%Y-%m-%d
	 %H:%M:%S " or --show-time="%a%I%p". The short option, -t, doesn't ac-
	 cept  a  strftime format string; it only uses the default format. Any
	 strftime format is allowed, including %s to get the raw UNIX  seconds
	 since the epoch.

       o -z  or	--null causes history entries written by the search operations
	 to be terminated by a NUL character rather than a newline.  This  al-
	 lows the output to be processed by read -z to correctly handle	multi-
	 line history entries.

       o -<number> -n <number> or --max=<number> limits	 the  matched  history
	 items	to the first "n" matching entries. This	is only	valid for his-
	 tory search.

       o -R or --reverse causes	the history search results to be ordered  old-
	 est to	newest.	Which is the order used	by most	shells.	The default is
	 newest	to oldest.

       o -h or --help display help for this command.

   Example
	  history clear
	  # Deletes all	history	items

	  history search --contains "foo"
	  # Outputs a list of all previous commands containing the string "foo".

	  history delete --prefix "foo"
	  # Interactively deletes commands which start with "foo" from the history.
	  # You	can select more	than one entry by entering their IDs separated by a space.

   Customizing the name	of the history file
       By     default	  interactive	  commands     are	logged	    to
       $XDG_DATA_HOME/fish/fish_history		   (typically		~/.lo-
       cal/share/fish/fish_history).

       You can set the fish_history variable to	another	name for  the  current
       shell  session.	The default value (when	the variable is	unset) is fish
       which corresponds to $XDG_DATA_HOME/fish/fish_history. If you set it to
       e.g.  fun, the history would be written to $XDG_DATA_HOME/fish/fun_his-
       tory. An	empty string means history will	not be stored at all. This  is
       similar to the private session features in web browsers.

       You  can	 change	fish_history at	any time (by using set -x fish_history
       "session_name") and it will take	effect right away. If you  set	it  to
       "default", it will use the default session name (which is "fish").

       Other  shells  such as bash and zsh use a variable named	HISTFILE for a
       similar purpose.	Fish uses a different name to avoid conflicts and sig-
       nal  that  the  behavior	 is  different (session	name instead of	a file
       path). Also, if you set the var to anything other than fish or  default
       it  will	 inhibit  importing  the bash history. That's because the most
       common use case for this	feature	is to avoid leaking private or	sensi-
       tive history when giving	a presentation.

   Notes
       If you specify both --prefix and	--contains the last flag seen is used.

       Note that for backwards compatibility each subcommand can also be spec-
       ified as	a long option. For example, rather than	history	search you can
       type  history  --search.	 Those long options are	deprecated and will be
       removed in a future release.

   if -	conditionally execute a	command
   Synopsis
	  if CONDITION;	COMMANDS_TRUE...;
	  [else	if CONDITION2; COMMANDS_TRUE2...;]
	  [else; COMMANDS_FALSE...;]
	  end

   Description
       if will execute the command CONDITION. If the condition's  exit	status
       is  0,  the commands COMMANDS_TRUE will execute.	 If the	exit status is
       not 0 and else is given,	COMMANDS_FALSE will be executed.

       You can use and or or in	the condition. See the second example below.

       The exit	status of the last foreground command to exit  can  always  be
       accessed	using the $status variable.

   Example
       The following code will print foo.txt exists if the file	foo.txt	exists
       and is a	regular	file, otherwise	it will	print bar.txt  exists  if  the
       file  bar.txt  exists  and  is  a regular file, otherwise it will print
       foo.txt and bar.txt do not exist.

	  if test -f foo.txt
	      echo foo.txt exists
	  else if test -f bar.txt
	      echo bar.txt exists
	  else
	      echo foo.txt and bar.txt do not exist
	  end

       The following code will print  "foo.txt	exists	and  is	 readable"  if
       foo.txt is a regular file and readable

	  if test -f foo.txt
	     and test -r foo.txt
	     echo "foo.txt exists and is readable"
	  end

   isatty - test if a file descriptor is a terminal
   Synopsis
	  isatty [FILE DESCRIPTOR]

   Description
       isatty tests if a file descriptor is a terminal (as opposed to a	file).
       The name	is derived from	the system call	of the same  name,  which  for
       historical reasons refers to a teletypewriter (TTY).

       FILE  DESCRIPTOR	 may be	either the number of a file descriptor,	or one
       of the strings stdin, stdout, or	stderr.	If not specified, zero is  as-
       sumed.

       If  the specified file descriptor is a terminal device, the exit	status
       of the command is zero. Otherwise, the exit status is non-zero. No mes-
       sages are printed to standard error.

   Examples
       From  an	interactive shell, the commands	below exit with	a return value
       of zero:

	  isatty
	  isatty stdout
	  isatty 2
	  echo | isatty	1

       And these will exit non-zero:

	  echo | isatty
	  isatty 9
	  isatty stdout	> file
	  isatty 2 2> file

   jobs	- print	currently running jobs
   Synopsis
	  jobs [OPTIONS] [ PID | %JOBID	]

   Description
       jobs prints a list of the currently running jobs	and their status.

       jobs accepts the	following switches:

       o -c or --command prints	the command name for each process in jobs.

       o -g or --group only prints the group ID	of each	job.

       o -l or --last prints only the last job to be started.

       o -p or --pid prints the	process	ID for each process in all jobs.

       o -q or --query prints no output	for evaluation of jobs by exit	status
	 only.	For  compatibility with	old fish versions this is also --quiet
	 (but this is deprecated).

       On systems that supports	this feature, jobs will	print the CPU usage of
       each  job  since	 the  last  command was	executed. The CPU usage	is ex-
       pressed as a percentage of full CPU activity. Note that on multiproces-
       sor systems, the	total activity may be more than	100%.

       Arguments  of  the  form	PID or %JOBID restrict the output to jobs with
       the selected process identifiers	or job numbers respectively.

       If the output of	jobs is	redirected or if it is part of a command  sub-
       stitution, the column header that is usually printed is omitted,	making
       it easier to parse.

       The exit	status of jobs is 0 if there are running background jobs and 1
       otherwise.

   Example
       jobs  outputs  a	 summary of the	current	jobs, such as two long-running
       tasks in	this example:

	  Job Group   State   Command
	  2   26012   running nc -l 55232 < /dev/random	&
	  1   26011   running python tests/test_11.py &

   math	- perform mathematics calculations
   Synopsis
	  math [-sN | --scale=N] [-bBASE | --base=BASE]	[--] EXPRESSION

   Description
       math performs mathematical calculations.	It supports simple  operations
       such  as	 addition,  subtraction,  and so on, as	well as	functions like
       abs(), sqrt() and ln().

       By default, the output is a floating-point number with trailing	zeroes
       trimmed.	To get a fixed representation, the --scale option can be used,
       including --scale=0 for integer output.

       Keep in mind that parameter expansion happens  before  expressions  are
       evaluated. This can be very useful in order to perform calculations in-
       volving shell variables or the output of	command	substitutions, but  it
       also  means  that  parenthesis (()) and the asterisk (*)	glob character
       have to be escaped or quoted. x can also	be used	to denote  multiplica-
       tion,  but it needs to be followed by whitespace	to distinguish it from
       hexadecimal numbers.

       Parentheses for functions are optional -	math sin pi prints 0. However,
       a comma will bind to the	inner function,	so math	pow sin	3, 5 is	an er-
       ror because it tries to give sin	the arguments 3	and 5. When in	doubt,
       use parentheses.

       math ignores whitespace between arguments and takes its input as	multi-
       ple arguments (internally joined	with a space), so math 2 +2  and  math
       "2 +    2" work the same. math 2	2 is an	error.

       The following options are available:

       o -sN  or  --scale=N sets the scale of the result. N must be an integer
	 or the	word "max" for the maximum scale. A scale of zero  causes  re-
	 sults	to  be	rounded	 down to the nearest integer. So 3/2 returns 1
	 rather	than 2 which 1.5 would normally	round to. This is for compati-
	 bility	 with  bc  which  was the basis	for this command prior to fish
	 3.0.0.	Scale values greater than zero causes the result to be rounded
	 using the usual rules to the specified	number of decimal places.

       o -b  BASE  or  --base BASE sets	the numeric base used for output (math
	 always	understands hexadecimal	numbers	as input). It currently	under-
	 stands	"hex" or "16" for hexadecimal and "octal" or "8" for octal and
	 implies a scale of 0 (other scales cause an error), so	it will	 trun-
	 cate  the result down to an integer. This might change	in the future.
	 Hex numbers will be printed with a 0x prefix. Octal numbers will have
	 a prefix of 0 and aren't understood by	math as	input.

   Return Values
       If  the expression is successfully evaluated and	doesn't	over/underflow
       or return NaN the return	status is zero (success) else one.

   Syntax
       math knows some operators, constants,  functions	 and  can  (obviously)
       read numbers.

       For  numbers,  .	 is  always the	radix character	regardless of locale -
       2.5, not	2,5. Scientific	notation (10e5)	 and  hexadecimal  (0xFF)  are
       also available.

   Operators
       math knows the following	operators:

       o + for addition	and - for subtraction.

       o *  or	x for multiplication, /	for division. (Note that * is the glob
	 character and needs to	be quoted or escaped, x	needs to  be  followed
	 by whitespace or it looks like	0x hexadecimal notation.)

       o ^ for exponentiation.

       o % for modulo.

       o (  and	) for grouping.	(These need to be quoted or escaped because ()
	 denotes a command substitution.)

       They are	all used in an infix manner - 5	+ 2, not + 5 2.

   Constants
       math knows the following	constants:

       o e - Euler's number.

       o pi - I. You know this one. Half of Tau.

       o tau. Equivalent to 2I,	or the number of radians in a circle.

       Use them	without	a leading $ - pi - 3 should be about 0.

   Functions
       math supports the following functions:

       o abs - the absolute value, with	positive sign

       o acos -	arc cosine

       o asin -	arc sine

       o atan -	arc tangent

       o atan2 - arc tangent of	two variables

       o bitand, bitor and bitxor to perform bitwise  operations.  These  will
	 throw away any	non-integer parts and interpret	the rest as an int.

       o ceil -	round number up	to nearest integer

       o cos - the cosine

       o cosh -	hyperbolic cosine

       o exp - the base-e exponential function

       o fac - factorial - also	known as x! (x * (x - 1) * (x -	2) * ... * 1)

       o floor - round number down to nearest integer

       o ln - the base-e logarithm

       o log or	log10 -	the base-10 logarithm

       o log2 -	the base-2 logarithm

       o max - returns the larger of two numbers

       o min - returns the smaller of two numbers

       o ncr  -	 "from	n choose r" combination	function - how many subsets of
	 size r	can be taken from n (order doesn't matter)

       o npr - the number of subsets of	size r that can	be taken from a	set of
	 n elements (including different order)

       o pow(x,y) returns x to the y (and can be written as x ^	y)

       o round - rounds	to the nearest integer,	away from 0

       o sin - the sine	function

       o sinh -	the hyperbolic sine

       o sqrt -	the square root	- (can also be written as x ^ 0.5)

       o tan - the tangent

       o tanh -	the hyperbolic tangent

       All of the trigonometric	functions use radians (the pi-based scale, not
       360A<degree>).

   Examples
       math 1+1	outputs	2.

       math $status - 128 outputs the numerical	exit status of the  last  com-
       mand minus 128.

       math 10 / 6 outputs 1.666667.

       math -s0	10.0 / 6.0 outputs 1.

       math -s3	10 / 6 outputs 1.666.

       math "sin(pi)" outputs 0.

       math 5 \* 2 or math "5 *	2" or math 5 "*" 2 all output 10.

       math 0xFF outputs 255, math 0 x 3 outputs 0 (because it computes	0 mul-
       tiplied by 3).

       math bitand 0xFE, 0x2e outputs 46.

       math "bitor(9,2)" outputs 11.

       math --base=hex 192 prints 0xc0.

       math 'ncr(49,6)'	prints 13983816	- that's the number of possible	 picks
       in 6-from-49 lotto.

   Compatibility notes
       Fish  1.x  and  2.x releases relied on the bc command for handling math
       expressions. Starting with fish 3.0.0 fish uses	the  tinyexpr  library
       and  evaluates  the  expression without the involvement of any external
       commands.

       You don't need to use --	before the expression, even if it begins  with
       a minus sign which might	otherwise be interpreted as an invalid option.
       If you do insert	-- before the expression, it will cause	 option	 scan-
       ning  to	stop just like for every other command and it won't be part of
       the expression.

   nextd - move	forward	through	directory history
   Synopsis
	  nextd	[ -l | --list ]	[POS]

   Description
       nextd moves forwards POS	positions in the history of  visited  directo-
       ries; if	the end	of the history has been	hit, a warning is printed.

       If the -l or --list flag	is specified, the current directory history is
       also displayed.

       Note that the cd	command	limits directory history to the	 25  most  re-
       cently  visited	directories. The history is stored in the $dirprev and
       $dirnext	variables which	this command manipulates.

   Example
	  cd /usr/src
	  # Working directory is now /usr/src

	  cd /usr/src/fish-shell
	  # Working directory is now /usr/src/fish-shell

	  prevd
	  # Working directory is now /usr/src

	  nextd
	  # Working directory is now /usr/src/fish-shell

   See Also
       o the cdh command to display a prompt to	quickly	navigate the history

       o the dirh command to print the directory history

       o the prevd command to move backward

   not - negate	the exit status	of a job
   Synopsis
	  not COMMAND [OPTIONS...]

   Description
       not negates the exit status of another command. If the exit  status  is
       zero, not returns 1. Otherwise, not returns 0.

   Example
       The  following  code  reports an	error and exits	if no file named spoon
       can be found.

	  if not test -f spoon
	      echo There is no spoon
	      exit 1
	  end

   open	- open file in its default application
   Synopsis
	  open FILES...

   Description
       open opens a file in its	default	 application,  using  the  appropriate
       tool  for  the operating	system.	On GNU/Linux, this requires the	common
       but optional xdg-open utility, from the xdg-utils package.

       Note that this function will not	be used	if a command by	this name  ex-
       ists (which is the case on macOS	or Haiku).

   Example
       open *.txt opens	all the	text files in the current directory using your
       system's	default	text editor.

   or -	conditionally execute a	command
   Synopsis
	  COMMAND1; or COMMAND2

   Description
       or is used to execute a command if the previous command	was  not  suc-
       cessful (returned a status of something other than 0).

       or  statements  may be used as part of the condition in an and or while
       block.

       or does not change the current exit status itself, but the  command  it
       runs  most  likely will.	The exit status	of the last foreground command
       to exit can always be accessed using the	$status	variable.

   Example
       The following code runs the make	command	to build  a  program.  If  the
       build  succeeds,	 the  program is installed. If either step fails, make
       clean is	run, which removes the files created by	the build process.

	  make;	and make install; or make clean

   See Also
       o and command

   popd	- move through directory stack
   Synopsis
	  popd

   Description
       popd removes the	top directory from the directory stack and changes the
       working	directory  to the new top directory. Use pushd to add directo-
       ries to the stack.

   Example
	  pushd	/usr/src
	  # Working directory is now /usr/src
	  # Directory stack contains /usr/src

	  pushd	/usr/src/fish-shell
	  # Working directory is now /usr/src/fish-shell
	  # Directory stack contains /usr/src /usr/src/fish-shell

	  popd
	  # Working directory is now /usr/src
	  # Directory stack contains /usr/src

   See Also
       o the dirs command to print the directory stack

       o the cdh command which provides	a more intuitive way  to  navigate  to
	 recently visited directories.

   prevd - move	backward through directory history
   Synopsis
	  prevd	[ -l | --list ]	[POS]

   Description
       prevd  moves backwards POS positions in the history of visited directo-
       ries; if	the beginning of the  history  has  been  hit,	a  warning  is
       printed.

       If the -l or --list flag	is specified, the current history is also dis-
       played.

       Note that the cd	command	limits directory history to the	 25  most  re-
       cently  visited	directories. The history is stored in the $dirprev and
       $dirnext	variables which	this command manipulates.

   Example
	  cd /usr/src
	  # Working directory is now /usr/src

	  cd /usr/src/fish-shell
	  # Working directory is now /usr/src/fish-shell

	  prevd
	  # Working directory is now /usr/src

	  nextd
	  # Working directory is now /usr/src/fish-shell

   See Also
       o the cdh command to display a prompt to	quickly	navigate the history

       o the dirh command to print the directory history

       o the nextd command to move forward

   printf - display text according to a	format string
   Synopsis
	  printf FORMAT	[ARGUMENT ...]

   Description
       printf uses the format string FORMAT to print the  ARGUMENT  arguments.
       This means that it takes	format specifiers in the format	string and re-
       places each with	an argument.

       The format argument is re-used as many times as	necessary  to  convert
       all  of	the given arguments. So	printf %s\n flounder catfish clownfish
       shark will print	four lines.

       Unlike echo, printf does	not append a new line unless it	 is  specified
       as part of the string.

       It doesn't support any options, so there	is no need for a -- separator,
       which makes it easier to	use for	arbitrary input	than echo. [1]

   Format Specifiers
       Valid  format  specifiers  are  taken  from  the	 C  library   function
       printf(3):

       o %d  or	 %i:  Argument	will be	used as	decimal	integer	(signed	or un-
	 signed)

       o %o: An	octal unsigned integer

       o %u: An	unsigned decimal integer - this	means  negative	 numbers  will
	 wrap around

       o %x or %X: An unsigned hexadecimal integer

       o %f,  %g or %G:	A floating-point number. %f defaults to	6 places after
	 the decimal point (which is locale-dependent -	e.g. in	de_DE it  will
	 be a ,). %g and %G will trim trailing zeroes and switch to scientific
	 notation (like	%e) if the numbers get small or	large enough.

       o %e or %E: A floating-point number in scientific (XXXeYY) notation

       o %s: A string

       o %b: As	a string, interpreting backslash escapes,  except  that	 octal
	 escapes are of	the form 0 or 0ooo.

       %% signifies a literal "%".

       Conversion  can fail, e.g. "102.234" can't losslessly convert to	an in-
       teger, causing printf to	print an error.	If you are  okay  with	losing
       information, silence errors with	2>/dev/null.

       A  number  between the %	and the	format letter specifies	the width. The
       result will be left-padded with spaces.

   Backslash Escapes
       printf also knows a number of backslash escapes:

       o \" double quote

       o \\ backslash

       o \a alert (bell)

       o \b backspace

       o \c produce no further output

       o \e escape

       o \f form feed

       o \n new	line

       o \r carriage return

       o \t horizontal tab

       o \v vertical tab

       o \ooo octal number (ooo	is 1 to	3 digits)

       o \xhh hexadecimal number (hhh is 1 to 2	digits)

       o \uhhhh	16-bit Unicode character (hhhh is 4 digits)

       o \Uhhhhhhhh 32-bit Unicode character (hhhhhhhh is 8 digits)

   Errors and Return Status
       If the given argument doesn't work for the given	format (like when  you
       try  to convert a number	like 3.141592 to an integer), printf prints an
       error, to stderr. printf	will then also return non-zero,	but will still
       try to print as much as it can.

       It  will	also return non-zero if	no argument at all was given, in which
       case it will print nothing.

       This printf has been imported from the printf in	GNU Coreutils  version
       6.9.  If	 you  would like to use	a newer	version	of printf, for example
       the one shipped with your OS, try command printf.

   Example
	  printf '%s\t%s\n' flounder fish

       Will print "flounder    fish" (separated	with a	tab  character),  fol-
       lowed  by  a newline character. This is useful for writing completions,
       as fish expects completion scripts to output the	option followed	by the
       description, separated with a tab character.

	  printf '%s: %d' "Number of bananas in	my pocket" 42

       Will print "Number of bananas in	my pocket: 42",	without	a newline.

   See Also
       o the echo command, for simpler output

   Footnotes
       [1]  (in	fact while fish's echo supports	--, POSIX forbids it, so other
	    implementations can't be  used  if	the  input  contains  anything
	    starting with -)

   prompt_login	- describe the login suitable for prompt
   Synopsis
	  function fish_prompt
	      echo -n (prompt_login) (prompt_pwd) '$ '
	  end

   Description
       prompt_login  is	a function to describe the current login. It will show
       the user, the host and also whether the shell is	running	 in  a	chroot
       (currently debian's debian_chroot is supported).

   Examples
	  >_ prompt_login
	  root@bananablaster

   prompt_pwd -	print pwd suitable for prompt
   Synopsis
	  function fish_prompt
	      echo -n (prompt_pwd) '$ '
	  end

   Description
       prompt_pwd  is  a  function to print the	current	working	directory in a
       way suitable for	prompts. It will replace the home directory  with  "~"
       and shorten every path component	but the	last to	a default of one char-
       acter.

       To  change  the	number	of  characters	 per   path   component,   set
       $fish_prompt_pwd_dir_length  to the number of characters. Setting it to
       0 or an invalid value will disable shortening entirely.

   Examples
	  >_ cd	~/
	  >_ echo $PWD
	  /home/alfa

	  >_ prompt_pwd
	  ~

	  >_ cd	/tmp/banana/sausage/with/mustard
	  >_ prompt_pwd
	  /t/b/s/w/mustard

	  >_ set -g fish_prompt_pwd_dir_length 3
	  >_ prompt_pwd
	  /tmp/ban/sau/wit/mustard

   psub	- perform process substitution
   Synopsis
	  COMMAND1 ( COMMAND2 |	psub [-F | --fifo] [-f | --file] [-s SUFFIX])

   Description
       Some shells (e.g., ksh, bash) feature a syntax that is  a  mix  between
       command	substitution  and  piping,  called process substitution. It is
       used to send the	output of a command into  the  calling	command,  much
       like  command  substitution, but	with the difference that the output is
       not sent	through	commandline arguments but through a named  pipe,  with
       the  filename of	the named pipe sent as an argument to the calling pro-
       gram. psub combined with	a regular command  substitution	 provides  the
       same functionality.

       The following options are available:

       o -f or --file will cause psub to use a regular file instead of a named
	 pipe to communicate with the calling process. This will cause psub to
	 be  significantly slower when large amounts of	data are involved, but
	 has the advantage that	the reading process can	seek  in  the  stream.
	 This is the default.

       o -F  or	--fifo will cause psub to use a	named pipe rather than a file.
	 You should only use this if the command produces no more than	8  KiB
	 of  output.  The limit	on the amount of data a	FIFO can buffer	varies
	 with the OS but is typically 8	KiB, 16	KiB or 64 KiB. If you use this
	 option	and the	command	on the left of the psub	pipeline produces more
	 output	a deadlock is likely to	occur.

       o -s or --suffix	will append SUFFIX to the filename.

   Example
	  diff (sort a.txt | psub) (sort b.txt | psub)
	  # shows the difference between the sorted versions of	files ``a.txt``	and ``b.txt``.

	  source-highlight -f esc (cpp main.c |	psub -f	-s .c)
	  # highlights ``main.c`` after	preprocessing as a C source.

   pushd - push	directory to directory stack
   Synopsis
	  pushd	[DIRECTORY]

   Description
       The pushd function adds DIRECTORY to the	top of the directory stack and
       makes it	the current working directory. popd will pop it	off and	return
       to the original directory.

       Without arguments, it exchanges the top two directories in the stack.

       pushd +NUMBER rotates the stack counter-clockwise i.e. from  bottom  to
       top

       pushd -NUMBER rotates clockwise i.e. top	to bottom.

   Example
	  cd ~/dir1
	  pushd	~/dir2
	  pushd	~/dir3
	  # Working directory is now ~/dir3
	  # Directory stack contains ~/dir2 ~/dir1

	  pushd	/tmp
	  # Working directory is now /tmp
	  # Directory stack contains ~/dir3 ~/dir2 ~/dir1

	  pushd	+1
	  # Working directory is now ~/dir3
	  # Directory stack contains ~/dir2 ~/dir1 /tmp

	  popd
	  # Working directory is now ~/dir2
	  # Directory stack contains ~/dir1 /tmp

   See Also
       o the dirs command to print the directory stack

       o the  cdh  command  which provides a more intuitive way	to navigate to
	 recently visited directories.

   pwd - output	the current working directory
   Synopsis
	  pwd [(-P | --physical)] [(-L | --logical)]

   Description
       pwd outputs (prints) the	current	working	directory.

       The following options are available:

       o -L or --logical Output	the logical working directory, without resolv-
	 ing symlinks (default behavior).

       o -P or --physical Output the physical working directory, with symlinks
	 resolved.

   See Also
       Navigate	directories using the directory	history	or the directory stack

   random - generate random number
   Synopsis
	  random
	  random SEED
	  random START END
	  random START STEP END
	  random choice	[ITEMS...]

   Description
       random generates	a pseudo-random	integer	from a	uniform	 distribution.
       The  range (inclusive) depends on the arguments.	 No arguments indicate
       a range of 0 to 32767 (inclusive).

       If one argument is specified, the internal engine will be  seeded  with
       the  argument  for  future  invocations of random and no	output will be
       produced.

       Two arguments indicate a	range from START to END	(both  START  and  END
       included).

       Three  arguments	 indicate  a range from	START to END with a spacing of
       STEP between possible outputs.  random choice will  select  one	random
       item from the succeeding	arguments.

       Note  that seeding the engine will NOT give the same result across dif-
       ferent systems.

       You should not consider random cryptographically	secure,	or  even  sta-
       tistically accurate.

   Example
       The following code will count down from a random	even number between 10
       and 20 to 1:

	  for i	in (seq	(random	10 2 20) -1 1)
	      echo $i
	  end

       And this	will open a random picture from	any of the subdirectories:

	  open (random choice **.jpg)

       Or, to only get even numbers from 2 to 20:

	  random 2 2 20

       Or odd numbers from 1 to	3:

	  random 1 2 3 # or 1 2	4

   read	- read line of input into variables
   Synopsis
	  read [OPTIONS] [VARIABLE ...]

   Description
       read reads from standard	input and either writes	 the  result  back  to
       standard	output (for use	in command substitution), or stores the	result
       in one or more shell variables. By default, read	reads  a  single  line
       and  splits  it into variables on spaces	or tabs. Alternatively,	a null
       character or a maximum number of	characters can be  used	 to  terminate
       the  input,  and	 other	delimiters  can	be given. Unlike other shells,
       there is	no default variable (such as REPLY) for	storing	the  result  -
       instead,	it is printed on standard output.

       The following options are available:

       o -c  CMD  or  --command=CMD sets the initial string in the interactive
	 mode command buffer to	CMD.

       o -d DELIMITER or --delimiter=DELIMITER splits on DELIMITER.  DELIMITER
	 will  be  used	 as an entire string to	split on, not a	set of charac-
	 ters.

       o -g or --global	makes the variables global.

       o -s or --silent	masks characters written to  the  terminal,  replacing
	 them with asterisks. This is useful for reading things	like passwords
	 or other sensitive information.

       o -l or --local makes the variables local.

       o -n NCHARS or --nchars=NCHARS makes read return	after  reading	NCHARS
	 characters or the end of the line, whichever comes first.

       o -p  PROMPT_CMD	 or  --prompt=PROMPT_CMD  uses the output of the shell
	 command PROMPT_CMD as the prompt for the interactive  mode.  The  de-
	 fault prompt command is set_color green; echo read; set_color normal;
	 echo "> "

       o -P PROMPT_STR or  --prompt-str=PROMPT_STR  uses  the  string  as  the
	 prompt	 for the interactive mode. It is equivalent to echo PROMPT_STR
	 and is	provided solely	to avoid the need to frame  the	 prompt	 as  a
	 command.  All	special	characters in the string are automatically es-
	 caped before being passed to the echo command.

       o -R RIGHT_PROMPT_CMD or	--right-prompt=RIGHT_PROMPT_CMD	uses the  out-
	 put of	the shell command RIGHT_PROMPT_CMD as the right	prompt for the
	 interactive mode. There is no default right prompt command.

       o -S or --shell enables syntax highlighting, tab	completions  and  com-
	 mand termination suitable for entering	shellscript code in the	inter-
	 active	mode. NOTE: Prior to fish 3.0, the short opt for  --shell  was
	 -s,  but  it  has been	changed	for compatibility with bash's -s short
	 opt for --silent.

       o -t -or	--tokenize causes read to split	the input  into	 variables  by
	 the  shell's  tokenization rules. This	means it will honor quotes and
	 escaping. This	option is of course incompatible with other options to
	 control  splitting  like  --delimiter	and  does not honor $IFS (like
	 fish's	tokenizer). It saves the tokens	in the manner they'd be	passed
	 to  commands  on the commandline, so e.g. a\ b	is stored as a b. Note
	 that currently	it leaves command substitutions	intact along with  the
	 parentheses.

       o -u  or	--unexport prevents the	variables from being exported to child
	 processes (default behaviour).

       o -U or --universal causes the specified	shell variable to be made uni-
	 versal.

       o -x or --export	exports	the variables to child processes.

       o -a  or	 --list	stores the result as a list in a single	variable. This
	 option	is also	available as --array for backwards compatibility.

       o -z or --null marks the	end of the line	with the  NUL  character,  in-
	 stead of newline. This	also disables interactive mode.

       o -L or --line reads each line into successive variables, and stops af-
	 ter each variable has been filled. This cannot	be combined  with  the
	 --delimiter option.

       Without the --line option, read reads a single line of input from stan-
       dard input, breaks it into tokens, and then assigns one token  to  each
       variable	 specified  in	VARIABLES. If there are	more tokens than vari-
       ables, the complete remainder is	assigned to the	last variable.

       If no option to determine how to	 split	like  --delimiter,  --line  or
       --tokenize  is  given, the variable IFS is used as a list of characters
       to split	on. Relying on the use of IFS is deprecated and	this behaviour
       will  be	 removed in future versions. The default value of IFS contains
       space, tab and newline characters. As a special case, if	IFS is set  to
       the  empty string, each character of the	input is considered a separate
       token.

       With the	--line option, read reads a line of input from standard	 input
       into  each  provided  variable,	stopping  when	each variable has been
       filled. The line	is not tokenized.

       If no variable names are	provided, read enters a	special	case that sim-
       ply provides redirection	from standard input to standard	output,	useful
       for command substitution. For instance, the fish	 shell	command	 below
       can be used to read data	that should be provided	via a command line ar-
       gument from the console instead of hardcoding it	in the command itself,
       allowing	 the  command to both be reused	as-is in various contexts with
       different input values and preventing possibly sensitive	text from  be-
       ing included in the shell history:

	  mysql	-uuser -p(read)

       When running in this mode, read does not	split the input	in any way and
       text is redirected to standard output without any further processing or
       manipulation.

       If -a or	--array	is provided, only one variable name is allowed and the
       tokens are stored as a list in this variable.

       See the documentation for set for more details on the scoping rules for
       variables.

       When  read reaches the end-of-file (EOF)	instead	of the terminator, the
       exit status is set to 1.	 Otherwise, it is set to 0.

       In order	to protect the shell from consuming too	many system resources,
       read  will  only	consume	a maximum of 100 MiB (104857600	bytes);	if the
       terminator is not reached before	this limit then	 VARIABLE  is  set  to
       empty and the exit status is set	to 122.	This limit can be altered with
       the fish_read_limit variable. If	set to 0 (zero), the limit is removed.

   Example
       The following code stores the value 'hello' in the shell	variable $foo.

	  echo hello|read foo

	  # This is a neat way to handle command output	by-line:
	  printf '%s\n'	line1 line2 line3 line4	| while	read -l	foo
			    echo "This is another line:	$foo"
			end

	  # Delimiters given via "-d" are taken	as one string
	  echo a==b==c | read -d == -l a b c
	  echo $a # a
	  echo $b # b
	  echo $c # c

	  # --tokenize honors quotes and escaping like the shell's argument passing:
	  echo 'a\ b' |	read -t	first second
	  echo $first #	outputs	"a b", $second is empty

	  echo 'a"foo bar"b (command echo wurst)*" "{a,b}' | read -lt -l a b c
	  echo $a # outputs 'afoo bar' (without	the quotes)
	  echo $b # outputs '(command echo wurst)* {a,b}' (without the quotes)
	  echo $c # nothing

   realpath - convert a	path to	an absolute path without symlinks
   Synopsis
	  realpath PATH

   Description
       realpath	resolves a path	to its absolute	path.

       fish provides a realpath	builtin	as a fallback for systems where	 there
       is  no realpath command,	your OS	might provide a	version	with more fea-
       tures.

       If a realpath command exists, it	will be	preferred, so if you  want  to
       use the builtin you should use builtin realpath explicitly.

       The following options are available:

       o -s  or	 --no-symlinks:	 Don't resolve symlinks, only make paths abso-
	 lute, squash multiple slashes and remove trailing slashes.

   return - stop the current inner function
   Synopsis
	  function NAME; [COMMANDS...;]	return [STATUS]; [COMMANDS...;]	end

   Description
       return halts a currently	running	function. The exit status  is  set  to
       STATUS if it is given.

       It  is usually added inside of a	conditional block such as an if	state-
       ment or a switch	statement to conditionally stop	the executing function
       and  return  to the caller, but it can also be used to specify the exit
       status of a function.

   Example
       The following code is an	implementation of the false command as a  fish
       function

	  function false
	      return 1
	  end

   set - display and change shell variables
   Synopsis
	  set [SCOPE_OPTIONS]
	  set [OPTIONS]	VARIABLE_NAME VALUES...
	  set [OPTIONS]	VARIABLE_NAME[INDICES]... VALUES...
	  set (	-q | --query ) [SCOPE_OPTIONS] VARIABLE_NAMES...
	  set (	-e | --erase ) [SCOPE_OPTIONS] VARIABLE_NAME...
	  set (	-e | --erase ) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]...
	  set (	-S | --show ) [VARIABLE_NAME]...

   Description
       set manipulates shell variables.

       If both a variable name and values are provided,	set assigns the	values
       to the variable of that name. Because all variables in fish are	lists,
       multiple	values are allowed.

       If  only	 a  variable name has been given, set sets the variable	to the
       empty list.

       If set is called	with no	arguments, it prints the names and  values  of
       all  shell variables in sorted order. Passing scope or export flags al-
       lows filtering this to only matching variables, so  set	--local	 would
       only show local variables.

       With  --erase  and  optionally a	scope flag set will erase the matching
       variable	(or the	variable of that name in the smallest possible scope).

       With --show, set	will describe the given	variable names,	explaining how
       they have been defined -	in which scope with which values and options.

       The following options control variable scope:

       o -l or --local forces the specified shell variable to be given a scope
	 that is local to the current block, even if a variable	with the given
	 name exists and is non-local

       o -g  or	 --global  causes  the	specified shell	variable to be given a
	 global	scope. Non-global variables disappear when the block they  be-
	 long to ends

       o -U  or	 --universal causes the	specified shell	variable to be given a
	 universal scope. If this option is supplied,  the  variable  will  be
	 shared	 between  all the current user's fish instances	on the current
	 computer, and will be preserved across	restarts of the	shell.

       These options control additional	variable options:

       o -x or --export	causes the specified shell variable to be exported  to
	 child processes (making it an "environment variable")

       o -u  or	 --unexport  causes the	specified shell	variable to NOT	be ex-
	 ported	to child processes

       o --path	causes the specified variable to be treated as	a  path	 vari-
	 able,	meaning	 it will automatically be split	on colons,  and	joined
	 using colons when quoted (echo	"$PATH") or exported.

       o --unpath causes the specified variable	to not be treated  as  a  path
	 variable.  Variables  with  a name ending in "PATH" are automatically
	 path variables, so this can be	used to	treat  such  a	variable  nor-
	 mally.

       The following other options are available:

       o -a or --append	causes the values to be	appended to the	current	set of
	 values	for the	variable. This can be used with	--prepend to both  ap-
	 pend and prepend at the same time. This cannot	be used	when assigning
	 to a variable slice.

       o -p or --prepend causes	the values to be prepended to the current  set
	 of  values  for  the variable.	This can be used with --append to both
	 append	and prepend at the same	time. This cannot be used when assign-
	 ing to	a variable slice.

       o -e or --erase causes the specified shell variables to be erased

       o -q  or	--query	test if	the specified variable names are defined. Does
	 not output anything, but the builtins exit status is  the  number  of
	 variables  specified  that  were not defined, or 255 if more than 255
	 variables are not defined.

       o -n or --names:	List only the names  of	 all  defined  variables,  not
	 their value. The names	are guaranteed to be sorted.

       o -S or --show shows information	about the given	variables. If no vari-
	 able names are	given then all variables are shown in sorted order. It
	 shows	the scopes the given variables are set in, along with the val-
	 ues in	each and whether or not	it is exported.	No other flags can  be
	 used with this	option.

       o -L  or	 --long	 do not	abbreviate long	values when printing set vari-
	 ables

       If a variable is	set to more than one value, the	 variable  will	 be  a
       list  with  the	specified  elements. If	a variable is set to zero ele-
       ments, it will become a list with zero elements.

       If the variable name is one or more list	elements, such as PATH[1 3 7],
       only  those  list  elements specified will be changed. If you specify a
       negative	index when expanding or	assigning to a list variable, the  in-
       dex will	be calculated from the end of the list.	For example, the index
       -1 means	the last index of a list.

       The scoping rules when creating or updating a variable are:

       o Variables may be explicitly set to universal, global or local.	 Vari-
	 ables with the	same name in different scopes will not be changed.

       o If a variable is not explicitly set to	be either universal, global or
	 local,	but has	been previously	defined, the previous  variable	 scope
	 is used.

       o If a variable is not explicitly set to	be either universal, global or
	 local and has never before been defined, the variable will  be	 local
	 to the	currently executing function. Note that	this is	different from
	 using the -l or --local flag. If one of  those	 flags	is  used,  the
	 variable  will	 be local to the most inner currently executing	block,
	 while without these the variable will be local	to the function. If no
	 function is executing,	the variable will be global.

       The  exporting rules when creating or updating a	variable are identical
       to the scoping rules for	variables:

       o Variables may be explicitly set to either exported or	not  exported.
	 When an exported variable goes	out of scope, it is unexported.

       o If  a	variable is not	explicitly set to be exported or not exported,
	 but has been previously defined, the previous exporting rule for  the
	 variable is kept.

       o If  a	variable  is not explicitly set	to be either exported or unex-
	 ported	and has	never before been defined, the variable	 will  not  be
	 exported.

       In query	mode, the scope	to be examined can be specified.

       In  erase  mode,	 if variable indices are specified, only the specified
       slices of the list variable will	be erased.

       set requires all	options	to come	before any other arguments. For	 exam-
       ple,  set  flags	 -l  will  have	the effect of setting the value	of the
       variable	flags to '-l', not making the variable local.

   Exit	status
       In assignment mode, set does not	modify the  exit  status,  but	passes
       along  whatever	$status	 was  set, including by	command	substitutions.
       This allows capturing the output	and exit status	of a subcommand,  like
       in if set output	(command).

       In query	mode, the exit status is the number of variables that were not
       found.

       In erase	mode, set exits	with a zero exit status	in  case  of  success,
       with  a	non-zero exit status if	the commandline	was invalid, if	any of
       the variables did not exist or was a special read-only variable.

   Examples
	  # Prints all global, exported	variables.
	  set -xg

	  # Sets the value of the variable $foo	to be 'hi'.
	  set foo hi

	  # Appends the	value "there" to the variable $foo.
	  set -a foo there

	  # Does the same thing	as the previous	two commands the way it	would be done pre-fish 3.0.
	  set foo hi
	  set foo $foo there

	  # Removes the	variable $smurf
	  set -e smurf

	  # Changes the	fourth element of the $PATH list to ~/bin
	  set PATH[4] ~/bin

	  # Outputs the	path to	Python if ``type -p`` returns true.
	  if set python_path (type -p python)
	      echo "Python is at $python_path"
	  end

	  # Setting a variable doesn't modify $status!
	  false
	  set foo bar
	  echo $status # prints	1, because of the "false" above.

	  true
	  set foo banana (false)
	  echo $status # prints	1, because of the "(false)" above.

	  # Like other shells, pass a variable to just one command:
	  # Run	fish with a temporary home directory.
	  HOME=(mktemp -d) fish
	  # Which is essentially the same as:
	  begin; set -lx HOME (mktemp -d); fish; end

   Notes
       Fish versions prior to 3.0 supported the	 syntax	 set  PATH[1]  PATH[4]
       /bin /sbin, which worked	like set PATH[1	4] /bin	/sbin. This syntax was
       not widely used,	and was	ambiguous and inconsistent.

   set_color - set the terminal	color
   Synopsis
	  set_color [OPTIONS] VALUE

   Description
       set_color is used to control the	color and styling of text in the  ter-
       minal.  VALUE  describes	 that styling. It's a reserved color name like
       red or a	RGB color value	given as 3 or 6	hexadecimal digits  ("F27"  or
       "FF2277").  A special keyword normal resets text	formatting to terminal
       defaults.

       Valid colors include:

	  o black, red,	green, yellow, blue, magenta, cyan, white

	  o brblack, brred, brgreen, bryellow, brblue, brmagenta, brcyan,  br-
	    white

       The  br-	 (as  in 'bright') forms are full-brightness variants of the 8
       standard-brightness  colors  on	many  terminals.  brblack  has	higher
       brightness than black - towards gray.

       An RGB value with three or six hex digits, such as A0FF33 or f2f	can be
       used. fish will choose the closest supported color. A three digit value
       is  equivalent  to  specifying each digit twice;	e.g., set_color	2BC is
       the same	as set_color 22BBCC. Hexadecimal RGB values can	be in lower or
       uppercase.  Depending  on  the  capabilities  of	your terminal (and the
       level of	support	set_color has for it) the actual color may be approxi-
       mated  by  a  nearby  matching reserved color name or set_color may not
       have an effect on color.

       A second	color may be given as a	desired	fallback color.	e.g. set_color
       124212  brblue  will  instruct set_color	to use brblue if a terminal is
       not capable of the exact	shade of grey desired.	This  is  very	useful
       when an 8 or 16 color terminal might otherwise not use a	color.

       The following options are available:

       o -b, --background COLOR	sets the background color.

       o -c, --print-colors prints a list of the 16 named colors.

       o -o, --bold sets bold mode.

       o -d, --dim sets	dim mode.

       o -i, --italics sets italics mode.

       o -r, --reverse sets reverse mode.

       o -u, --underline sets underlined mode.

       Using  the  normal  keyword  will reset foreground, background, and all
       formatting back to default.

   Notes
       1. Using	the normal keyword will	reset both background  and  foreground
	  colors to whatever is	the default for	the terminal.

       2. Setting the background color only affects subsequently written char-
	  acters. Fish provides	no way to set the background color for the en-
	  tire	terminal  window. Configuring the window background color (and
	  other	attributes such	as its opacity)	has to be done using  whatever
	  mechanisms the terminal provides. Look for a config option.

       3. Some	terminals  use	the  --bold  escape  sequence  to  switch to a
	  brighter color set rather than increasing the	weight of text.

       4. set_color works by printing sequences	of characters  to  stdout.  If
	  used	in  command substitution or a pipe, these characters will also
	  be captured. This may	or may not be  desirable.  Checking  the  exit
	  status  of isatty stdout before using	set_color can be useful	to de-
	  cide not to colorize output in a script.

   Examples
	  set_color red; echo "Roses are red"
	  set_color blue; echo "Violets	are blue"
	  set_color 62A; echo "Eggplants are dark purple"
	  set_color normal; echo "Normal is nice" # Resets the background too

   Terminal Capability Detection
       Fish uses some heuristics to determine what colors a terminal  supports
       to avoid	sending	sequences that it won't	understand.

       In particular it	will:

       o Enable	 256 colors if $TERM contains "xterm", except for known	excep-
	 tions (like MacOS 10.6	Terminal.app)

       o Enable	24-bit ("true-color") even if the $TERM	entry only reports 256
	 colors.  This	includes  modern xterm,	VTE-based terminals like Gnome
	 Terminal, Konsole and iTerm2.

       o Detect	support	for italics, dim, reverse and other modes.

       If terminfo reports 256 color support for a terminal, 256 color support
       will always be enabled.

       To  force  true-color support on	or off,	set $fish_term24bit to "1" for
       on and 0	for off	- set -g fish_term24bit	1.

       To debug	color palette problems,	tput colors may	be useful to  see  the
       number  of colors in terminfo for a terminal. Fish launched as fish -d2
       will include diagnostic messages	that indicate the color	 support  mode
       in use.

       The  set_color  command	uses  the  terminfo database to	look up	how to
       change terminal colors on whatever terminal is  in  use.	 Some  systems
       have  old and incomplete	terminfo databases, and	lack color information
       for terminals that support it. Fish assumes that	all terminals can  use
       the [ANSI X3.64](https://en.wikipedia.org/wiki/ANSI_escape_code)	escape
       sequences if the	terminfo definition indicates a	color below 16 is  not
       supported.

   source - evaluate contents of file
   Synopsis
	  source FILENAME [ARGUMENTS...]
	  somecommand |	source

   Description
       source  evaluates  the  commands	 of  the specified file	in the current
       shell as	a new block of code. This is different	from  starting	a  new
       process	to  perform the	commands (i.e. fish < FILENAME)	since the com-
       mands will be evaluated by the current shell, which means that  changes
       in  shell  variables will affect	the current shell. If additional argu-
       ments are specified after the file name,	they will be inserted into the
       $argv  variable.	 The  $argv  variable will not include the name	of the
       sourced file.

       fish will search	the working directory to resolve  relative  paths  but
       will not	search $PATH.

       If  no  file is specified and stdin is not the terminal,	or if the file
       name - is used, stdin will be read.

       The exit	status of source is the	exit status of the last	 job  to  exe-
       cute. If	something goes wrong while opening or reading the file,	source
       exits with a non-zero status.

       . (a single period) is an alias for the source command. The use of . is
       deprecated  in favour of	source,	and . will be removed in a future ver-
       sion of fish.

       source creates a	new local scope; set --local within  a	sourced	 block
       will not	affect variables in the	enclosing scope.

   Example
	  source ~/.config/fish/config.fish
	  # Causes fish	to re-read its initialization file.

   Caveats
       In fish versions	prior to 2.3.0,	the $argv variable would have a	single
       element (the name of the	sourced	file) if  no  arguments	 are  present.
       Otherwise,  it  would contain arguments without the name	of the sourced
       file. That behavior was very confusing and unlike other shells such  as
       bash and	zsh.

   status - query fish runtime information
   Synopsis
	  status
	  status is-login
	  status is-interactive
	  status is-block
	  status is-breakpoint
	  status is-command-substitution
	  status is-no-job-control
	  status is-full-job-control
	  status is-interactive-job-control
	  status current-command
	  status filename
	  status basename
	  status dirname
	  status fish-path
	  status function
	  status line-number
	  status stack-trace
	  status job-control CONTROL_TYPE
	  status features
	  status test-feature FEATURE

   Description
       With  no	 arguments, status displays a summary of the current login and
       job control status of the shell.

       The following operations	(sub-commands) are available:

       o is-command-substitution returns 0 if fish is  currently  executing  a
	 command substitution. Also -c or --is-command-substitution.

       o is-block  returns  0  if fish is currently executing a	block of code.
	 Also -b or --is-block.

       o is-breakpoint returns 0 if fish is currently showing a	prompt in  the
	 context  of a breakpoint command. See also the	fish_breakpoint_prompt
	 function.

       o is-interactive	returns	0 if fish is interactive - that	is,  connected
	 to a keyboard.	Also -i	or --is-interactive.

       o is-login returns 0 if fish is a login shell - that is,	if fish	should
	 perform login tasks such as setting up	the PATH. Also -l or  --is-lo-
	 gin.

       o is-full-job-control  returns  0  if full job control is enabled. Also
	 --is-full-job-control (no short flag).

       o is-interactive-job-control returns 0 if interactive  job  control  is
	 enabled. Also,	--is-interactive-job-control (no short flag).

       o is-no-job-control  returns  0	if  no	job  control  is enabled. Also
	 --is-no-job-control (no short flag).

       o current-command prints	the name of the	currently-running function  or
	 command, like the deprecated _	variable.

       o filename  prints  the	filename of the	currently running script. Also
	 current-filename, -f or --current-filename. This depends on  how  the
	 script	 was called - if it was	called via a symlink, the symlink will
	 be returned, and if the current script	was  received  via  source  it
	 will be -.

       o basename  prints just the filename of the running script, without any
	 path-components before.

       o dirname prints	just the path to the running script, without  the  ac-
	 tual  filename	 itself.  This can be relative to $PWD (including just
	 "."), depending on how	the script was called. This  is	 the  same  as
	 passing  the  filename	 to dirname(3).	It's useful if you want	to use
	 other files in	the current script's directory or similar.

       o fish-path prints the absolute path to	the  currently	executing  in-
	 stance	of fish.

       o function  prints  the	name of	the currently called function if able,
	 when missing displays "Not  a	function"  (or	equivalent  translated
	 string). Also current-function.

       o line-number  prints  the line number of the currently running script.
	 Also current-line-number, -n or --current-line-number.

       o stack-trace prints a stack trace of all function calls	 on  the  call
	 stack.	Also print-stack-trace,	-t or --print-stack-trace.

       o job-control  CONTROL_TYPE  sets  the  job  control type, which	can be
	 none, full, or	interactive. Also  -j  CONTROL_TYPE  or	 --job-control
	 CONTROL_TYPE.

       o features lists	all available feature flags.

       o test-feature  FEATURE	returns	 0 when	FEATURE	is enabled, 1 if it is
	 disabled, and 2 if it is not recognized.

   Notes
       For backwards compatibility most	subcommands can	also be	specified as a
       long  or	short option. For example, rather than status is-login you can
       type status --is-login. The flag	forms are deprecated and  may  be  re-
       moved in	a future release (but not before fish 4.0).

       You  can	only specify one subcommand per	invocation even	if you use the
       flag form of the	subcommand.

   string - manipulate strings
   Synopsis
	  string collect [(-N |	--no-trim-newlines)] [STRING...]
	  string escape	[(-n | --no-quoted)] [--style=xxx] [STRING...]
	  string join [(-q | --quiet)] SEP [STRING...]
	  string join0 [(-q | --quiet)]	[STRING...]
	  string length	[(-q | --quiet)] [STRING...]
	  string lower [(-q | --quiet)]	[STRING...]
	  string match [(-a | --all)] [(-e | --entire)]	[(-i | --ignore-case)] [(-r | --regex)]	[(-n | --index)] [(-q |	--quiet)] [(-v | --invert)] PATTERN [STRING...]
	  string pad [(-r | --right)] [(-c | --char) CHAR] [(-w	| --width) INTEGER] [STRING...]
	  string repeat	[(-n | --count)	COUNT] [(-m | --max) MAX] [(-N | --no-newline)]	[(-q | --quiet)] [STRING...]
	  string replace [(-a |	--all)]	[(-f | --filter)] [(-i | --ignore-case)] [(-r |	--regex)] [(-q | --quiet)] PATTERN REPLACEMENT [STRING...]
	  string split [(-m | --max) MAX] [(-n | --no-empty)] [(-q | --quiet)] [(-r | --right)]	SEP [STRING...]
	  string split0	[(-m | --max) MAX] [(-n	| --no-empty)] [(-q | --quiet)]	[(-r | --right)] [STRING...]
	  string sub [(-s | --start) START] [(-l | --length) LENGTH] [(-q | --quiet)] [STRING...]
	  string trim [(-l | --left)] [(-r | --right)] [(-c | --chars CHARS)] [(-q | --quiet)] [STRING...]
	  string unescape [--style=xxx]	[STRING...]
	  string upper [(-q | --quiet)]	[STRING...]

   Description
       string performs operations on strings.

       STRING arguments	are taken from the command line	unless standard	 input
       is  connected  to  a  pipe  or a	file, in which case they are read from
       standard	input, one STRING per line. It is an error  to	supply	STRING
       arguments on the	command	line and on standard input.

       Arguments  beginning  with  -  are normally interpreted as switches; --
       causes the following arguments not to be	treated	as  switches  even  if
       they  begin with	-. Switches and	required arguments are recognized only
       on the command line.

       Most subcommands	accept a -q or --quiet switch,	which  suppresses  the
       usual  output  but exits	with the documented status. In this case these
       commands	will quit early, without reading all of	the available input.

       The following subcommands are available.

   collect subcommand
	  string collect [(-N |	--no-trim-newlines)] [STRING...]

       string collect collects its input into a	single output argument,	 with-
       out  splitting  the output when used in a command substitution. This is
       useful when trying to collect multiline	output	from  another  command
       into a variable.	Exit status: 0 if any output argument is non-empty, or
       1 otherwise.

       If invoked with multiple	arguments instead  of  input,  string  collect
       preserves  each	argument  separately, where the	number of output argu-
       ments is	equal to the number of arguments given to string collect.

       Any trailing newlines on	the input are trimmed, just as	with  "$(cmd)"
       substitution  in	sh. --no-trim-newlines can be used to disable this be-
       havior, which may be useful when	running	a command such as set contents
       (cat filename | string collect -N).

   Examples
	  >_ echo \"(echo one\ntwo\nthree | string collect)\"
	  "one
	  two
	  three"

	  >_ echo \"(echo one\ntwo\nthree | string collect -N)\"
	  "one
	  two
	  three
	  "

   escape and unescape subcommands
	  string escape	[(-n | --no-quoted)] [--style=xxx] [STRING...]
	  string unescape [--style=xxx]	[STRING...]

       string  escape  escapes	each STRING in one of three ways. The first is
       --style=script. This is the default. It alters the string such that  it
       can  be	passed back to eval to produce the original argument again. By
       default,	all special characters are escaped, and	 quotes	 are  used  to
       simplify	 the  output when possible. If -n or --no-quoted is given, the
       simplifying quoted format is not	used. Exit status: 0 if	at  least  one
       string was escaped, or 1	otherwise.

       --style=var  ensures  the  string can be	used as	a variable name	by hex
       encoding	any non-alphanumeric characters. The string is first converted
       to UTF-8	before being encoded.

       --style=url ensures the string can be used as a URL by hex encoding any
       character which is not legal in a URL. The string is first converted to
       UTF-8 before being encoded.

       --style=regex  escapes  an  input  string for literal matching within a
       regex expression. The string is first converted to UTF-8	 before	 being
       encoded.

       string  unescape	 performs the inverse of the string escape command. If
       the string to be	unescaped is not properly formatted it is ignored. For
       example,	 doing	string unescape	--style=var (string escape --style=var
       $str) will return the original string. There is no support for unescap-
       ing --style=regex.

   Examples
	  >_ echo \x07 | string	escape
	  \cg

	  >_ string escape --style=var 'a1 b2'\u6161
	  a1_20_b2_E6_85_A1_

   join	and join0 subcommands
	  string join [(-q | --quiet)] SEP [STRING...]
	  string join0 [(-q | --quiet)]	[STRING...]

       string  join  joins its STRING arguments	into a single string separated
       by SEP, which can be an empty string. Exit status: 0 if	at  least  one
       join was	performed, or 1	otherwise.

       string  join0 joins its STRING arguments	into a single string separated
       by the zero byte	(NUL), and adds	a trailing NUL.	This is	most useful in
       conjunction  with  tools	 that accept NUL-delimited input, such as sort
       -z. Exit	status:	0 if at	least one join was performed, or 1 otherwise.

       Because Unix uses NUL as	the string terminator, passing the  output  of
       string  join0  as an argument to	a command (via a command substitution)
       won't actually work. Fish will pass the correct bytes  along,  but  the
       command	won't be able to tell where the	argument ends. This is a limi-
       tation of Unix' argument	passing.

   Examples
	  >_ seq 3 | string join ...
	  1...2...3

	  # Give a list	of NUL-separated filenames to du (this is a GNU	extension)
	  >_ string join0 file1	file2 file\nwith\nmultiple\nlines | du --files0-from=-

	  # Just put the strings together without a separator
	  >_ string join '' a b	c
	  abc

   length subcommand
	  string length	[(-q | --quiet)] [STRING...]

       string length reports the length	of each	string argument	in characters.
       Exit  status: 0 if at least one non-empty STRING	was given, or 1	other-
       wise.

   Examples
	  >_ string length 'hello, world'
	  12

	  >_ set str foo
	  >_ string length -q $str; echo $status
	  0
	  # Equivalent to test -n "$str"

   lower subcommand
	  string lower [(-q | --quiet)]	[STRING...]

       string lower converts each string argument to lowercase.	Exit status: 0
       if  at  least one string	was converted to lowercase, else 1. This means
       that in conjunction with	the -q flag you	can  readily  test  whether  a
       string is already lowercase.

   match subcommand
	  string match [(-a | --all)] [(-e | --entire)]	[(-i | --ignore-case)] [(-r | --regex)]	[(-n | --index)] [(-q |	--quiet)] [(-v | --invert)] PATTERN [STRING...]

       string match tests each STRING against PATTERN and prints matching sub-
       strings.	Only the first match for each STRING is	reported unless	-a  or
       --all is	given, in which	case all matches are reported.

       If  you specify the -e or --entire then each matching string is printed
       including any prefix or suffix not matched by the  pattern  (equivalent
       to  grep	without	the -o flag). You can, obviously, achieve the same re-
       sult by prepending and appending	* or .*	depending on  whether  or  not
       you  have specified the --regex flag. The --entire flag is simply a way
       to avoid	having to complicate the pattern in that fashion and make  the
       intent  of  the	string	match clearer. Without --entire	and --regex, a
       PATTERN will need to match the entire STRING  before  it	 will  be  re-
       ported.

       Matching	can be made case-insensitive with --ignore-case	or -i.

       If  --index  or	-n is given, each match	is reported as a 1-based start
       position	and a length. By default, PATTERN is  interpreted  as  a  glob
       pattern	matched	against	each entire STRING argument. A glob pattern is
       only considered a valid match if	it matches the entire STRING.

       If --regex or -r	is given, PATTERN is interpreted as a  Perl-compatible
       regular expression, which does not have to match	the entire STRING. For
       a regular expression containing capturing groups, multiple  items  will
       be  reported  for each match, one for the entire	match and one for each
       capturing group.	With this, only	the matching part of the  STRING  will
       be reported, unless --entire is given.

       When  matching via regular expressions, string match automatically sets
       variables for all named capturing groups	((?<name>expression)). It will
       create a	variable with the name of the group, in	the default scope, for
       each named capturing group, and set it to the value  of	the  capturing
       group  in  the first matched argument. If a named capture group matched
       an empty	string,	the variable will be set to the	empty string (like set
       var "").	If it did not match, the variable will be set to nothing (like
       set var).  When --regex is used with --all, this	behavior changes. Each
       named  variable	will  contain  a list of matches, with the first match
       contained in the	first element, the second match	in the second, and  so
       on.  If the group was empty or did not match, the corresponding element
       will be an empty	string.

       If --invert or -v is used the selected lines will be only  those	 which
       do not match the	given glob pattern or regular expression.

       Exit status: 0 if at least one match was	found, or 1 otherwise.

   Match Glob Examples
	  >_ string match '?' a
	  a

	  >_ string match 'a*b'	axxb
	  axxb

	  >_ string match -i 'a??B' Axxb
	  Axxb

	  >_ echo 'ok?'	| string match '*\?'
	  ok?

	  # Note that only the second STRING will match	here.
	  >_ string match 'foo'	'foo1' 'foo' 'foo2'
	  foo

	  >_ string match -e 'foo' 'foo1' 'foo'	'foo2'
	  foo1
	  foo
	  foo2

	  >_ string match 'foo?' 'foo1'	'foo' 'foo2'
	  foo1
	  foo2

   Match Regex Examples
	  >_ string match -r 'cat|dog|fish' 'nice dog'
	  dog

	  >_ string match -r -v	"c.*[12]" {cat,dog}(seq	1 4)
	  dog1
	  dog2
	  cat3
	  dog3
	  cat4
	  dog4

	  >_ string match -r '(\d\d?):(\d\d):(\d\d)' 2:34:56
	  2:34:56
	  2
	  34
	  56

	  >_ string match -r '^(\w{2,4})\1$' papa mud murmur
	  papa
	  pa
	  murmur
	  mur

	  >_ string match -r -a	-n at ratatat
	  2 2
	  4 2
	  6 2

	  >_ string match -r -i	'0x[0-9a-f]{1,8}' 'int magic = 0xBadC0de;'
	  0xBadC0de

	  >_ echo $version
	  3.1.2-1575-ga2ff32d90
	  >_ string match -rq '(?<major>\d+).(?<minor>\d+).(?<revision>\d+)' --	$version
	  >_ echo "You are using fish $major!"
	  You are using	fish 3!

	  >_ string match -raq ' *(?<sentence>[^.!?]+)(?<punctuation>[.!?])?' "hello, friend. goodbye"
	  >_ printf "%s\n" -- $sentence
	  hello, friend
	  goodbye
	  >_ printf "%s\n" -- $punctuation
	  .

	  >_ string match -rq '(?<word>hello)' 'hi'
	  >_ count $word
	  0

   pad subcommand
	  string pad [(-r | --right)] [(-c | --char) CHAR] [(-w	| --width) INTEGER] [STRING...]

       string pad extends each STRING to the given width by adding CHAR	to the
       left.

       If -r or	--right	is given, add the padding after	a string.

       If -c or	--char is given, pad with CHAR instead of whitespace.

       The output is padded to the maximum width of all	input strings.	If  -w
       or --width is given, use	at least that.

	  >_ string pad	-w 10 abc abcdef
		 abc
	      abcdef

	  >_ string pad	--right	--char=dh "fish	are pretty" "rich. "
	  fish are pretty
	  rich.	 dhdhdhdh

	  >_ string pad	-w$COLUMNS (date)
	  # Prints the current time on the right edge of the screen.

   See Also
       o The  printf  command can do simple padding, for example printf	%10s\n
	 works like string pad -w10.

   repeat subcommand
	  string repeat	[(-n | --count)	COUNT] [(-m | --max) MAX] [(-N | --no-newline)]	[(-q | --quiet)] [STRING...]

       string repeat repeats the STRING	-n or --count times. The -m  or	 --max
       option will limit the number of outputted char (excluding the newline).
       This option can be used by itself or in conjunction  with  --count.  If
       both  --count  and  --max are present, max char will be outputed	unless
       the final repeated string size is less than  max,  in  that  case,  the
       string will repeat until	count has been reached.	Both --count and --max
       will accept a number greater than or equal to  zero,  in	 the  case  of
       zero,  nothing  will  be	 outputed. If -N or --no-newline is given, the
       output won't contain a newline character	at the end. Exit status: 0  if
       yielded string is not empty, 1 otherwise.

   Examples
   Repeat Examples
	  >_ string repeat -n 2	'foo '
	  foo foo

	  >_ echo foo |	string repeat -n 2
	  foofoo

	  >_ string repeat -n 2	-m 5 'foo'
	  foofo

	  >_ string repeat -m 5	'foo'
	  foofo

   replace subcommand
	  string replace [(-a |	--all)]	[(-f | --filter)] [(-i | --ignore-case)] [(-r |	--regex)] [(-q | --quiet)] PATTERN REPLACEMENT [STRING...]

       string  replace is similar to string match but replaces non-overlapping
       matching	substrings with	a replacement string and prints	the result. By
       default,	PATTERN	is treated as a	literal	substring to be	matched.

       If  -r or --regex is given, PATTERN is interpreted as a Perl-compatible
       regular expression, and REPLACEMENT  can	 contain  C-style  escape  se-
       quences	like \t	as well	as references to capturing groups by number or
       name as $n or ${n}.

       If you specify the -f or	 --filter  flag	 then  each  input  string  is
       printed	only if	a replacement was done.	This is	useful where you would
       otherwise use this idiom: a_cmd | string	match pattern |	string replace
       pattern	new_pattern. You can instead just write	a_cmd |	string replace
       --filter	pattern	new_pattern.

       Exit status: 0 if at least one replacement was performed, or  1	other-
       wise.

   Replace Literal Examples
	  >_ string replace is was 'blue is my favorite'
	  blue was my favorite

	  >_ string replace 3rd	last 1st 2nd 3rd
	  1st
	  2nd
	  last

	  >_ string replace -a ' ' _ 'spaces to	underscores'
	  spaces_to_underscores

   Replace Regex Examples
	  >_ string replace -r -a '[^\d.]+' ' '	'0 one two 3.14	four 5x'
	  0 3.14 5

	  >_ string replace -r '(\w+)\s+(\w+)' '$2 $1 $$' 'left	right'
	  right	left $

	  >_ string replace -r '\s*newline\s*' '\n' 'put a newline here'
	  put a
	  here

   split and split0 subcommands
	  string split [(-f | --fields)	FIELDS]	[(-m | --max) MAX] [(-n	| --no-empty)] [(-q | --quiet)]	[(-r | --right)] SEP [STRING...]
	  string split0	[(-f | --fields) FIELDS] [(-m |	--max) MAX] [(-n | --no-empty)]	[(-q | --quiet)] [(-r |	--right)] [STRING...]

       string  split  splits each STRING on the	separator SEP, which can be an
       empty string. If	-m or --max is specified, at most MAX splits are  done
       on  each	 STRING.  If  -r  or  --right is given,	splitting is performed
       right-to-left. This is useful in	combination with -m or --max. With  -n
       or  --no-empty,	empty  results	are  excluded from consideration (e.g.
       hello\n\nworld would expand to two strings and not three). Exit status:
       0 if at least one split was performed, or 1 otherwise.

       Use  -f	or --fields to print out specific fields. Unless --allow-empty
       is used,	if a given field does not exist, then the command  exits  with
       status 1	and does not print anything.

       See also	the --delimiter	option of the read command.

       string  split0  splits  each STRING on the zero byte (NUL). Options are
       the same	as string split	except that no separator is given.

       split0 has the important	property that its output is not	further	 split
       when used in a command substitution, allowing for the command substitu-
       tion to produce elements	containing newlines. This is most useful  when
       used  with  Unix	tools that produce zero	bytes, such as find -print0 or
       sort -z.	See split0 examples below.

   Examples
	  >_ string split . example.com
	  example
	  com

	  >_ string split -r -m1 / /usr/local/bin/fish
	  /usr/local/bin
	  fish

	  >_ string split '' abc
	  a
	  b
	  c

	  >_ string split --allow-empty	-f1,3,5	'' abc
	  a
	  c

   NUL Delimited Examples
	  >_ # Count files in a	directory, without being confused by newlines.
	  >_ count (find . -print0 | string split0)
	  42

	  >_ # Sort a list of elements which may contain newlines
	  >_ set foo beta alpha\ngamma
	  >_ set foo (string join0 $foo	| sort -z | string split0)
	  >_ string escape $foo[1]
	  alpha\ngamma

   sub subcommand
	  string sub [(-s | --start) START] [(-e | --end) END] [(-l | --length)	LENGTH]	[(-q | --quiet)] [STRING...]

       string sub prints a substring of	each string argument. The start/end of
       the  substring can be specified with -s/-e or --start/--end followed by
       a 1-based index value. Positive index values are	relative to the	 start
       of  the string and negative index values	are relative to	the end	of the
       string. The default start value is 1. The length	of the	substring  can
       be  specified  with  -l or --length. If the length or end is not	speci-
       fied, the substring continues to	the end	of each	STRING.	Exit status: 0
       if  at  least  one  substring  operation	 was  performed,  1 otherwise.
       --length	is mutually exclusive with --end.

   Examples
	  >_ string sub	--length 2 abcde
	  ab

	  >_ string sub	-s 2 -l	2 abcde
	  bc

	  >_ string sub	--start=-2 abcde
	  de

	  >_ string sub	--end=3	abcde
	  abc

	  >_ string sub	-e -1 abcde
	  abcd

	  >_ string sub	-s 2 -e	-1 abcde
	  bcd

	  >_ string sub	-s -3 -e -2 abcde
	  c

   trim	subcommand
	  string trim [(-l | --left)] [(-r | --right)] [(-c | --chars CHARS)] [(-q | --quiet)] [STRING...]

       string trim removes leading and trailing	whitespace from	 each  STRING.
       If  -l or --left	is given, only leading whitespace is removed. If -r or
       --right is given, only  trailing	 whitespace  is	 trimmed.  The	-c  or
       --chars	switch causes the characters in	CHARS to be removed instead of
       whitespace. Exit	status:	0 if at	least one character was	trimmed, or  1
       otherwise.

   Examples
	  >_ string trim ' abc	'
	  abc

	  >_ string trim --right --chars=yz xyzzy zany
	  x
	  zan

   upper subcommand
	  string upper [(-q | --quiet)]	[STRING...]

       string upper converts each string argument to uppercase.	Exit status: 0
       if at least one string was converted to uppercase, else 1.  This	 means
       that  in	 conjunction  with  the	-q flag	you can	readily	test whether a
       string is already uppercase.

   Regular Expressions
       Both the	match and replace subcommand support regular expressions  when
       used with the -r	or --regex option. The dialect is that of PCRE2.

       In  general,  special  characters are special by	default, so a+ matches
       one or more "a"s, while a\+ matches an "a" and then a "+". (a+) matches
       one or more "a"s	in a capturing group ((?:XXXX) denotes a non-capturing
       group). For the replacement parameter of	replace, $n refers to the n-th
       group of	the match. In the match	parameter, \n (e.g. \1)	refers back to
       groups.

       Some features include repetitions:

       o * refers to 0 or more repetitions of the previous expression

       o + 1 or	more

       o ? 0 or	1.

       o {n} to	exactly	n (where n is a	number)

       o {n,m} at least	n, no more than	m.

       o {n,} n	or more

       Character classes, some of the more important:

       o . any character except	newline

       o \d a decimal digit and	\D, not	a decimal digit

       o \s whitespace and \S, not whitespace

       o \w a "word" character and \W, a "non-word" character

       o [...] (where "..." is some characters)	is a character set

       o [^...]	is the inverse of the given character set

       o [x-y] is the range of characters from x-y

       o [[:xxx:]] is a	named character	set

       o [[:^xxx:]] is the inverse of a	named character	set

       o [[:alnum:]]  :	"alphanumeric"

       o [[:alpha:]]  :	"alphabetic"

       o [[:ascii:]]  :	"0-127"

       o [[:blank:]]  :	"space or tab"

       o [[:cntrl:]]  :	"control character"

       o [[:digit:]]  :	"decimal digit"

       o [[:graph:]]  :	"printing, excluding space"

       o [[:lower:]]  :	"lower case letter"

       o [[:print:]]  :	"printing, including space"

       o [[:punct:]]  :	"printing, excluding alphanumeric"

       o [[:space:]]  :	"white space"

       o [[:upper:]]  :	"upper case letter"

       o [[:word:]]   :	"same as w"

       o [[:xdigit:]] :	"hexadecimal digit"

       Groups:

       o (...) is a capturing group

       o (?:...) is a non-capturing group

       o \n is a backreference (where n	is the number of the  group,  starting
	 with 1)

       o $n  is	 a reference from the replacement expression to	a group	in the
	 match expression.

       And some	other things:

       o \b denotes a word boundary, \B	is not a word boundary.

       o ^ is the start	of the string or line, $ the end.

       o | is "alternation", i.e. the "or".

   Comparison to other tools
       Most operations string supports can also	be  done  by  external	tools.
       Some of these include grep, sed and cut.

       If you are familiar with	these, it is useful to know how	string differs
       from them.

       In contrast to these classics, string reads input either	from stdin  or
       as  arguments.  string  also  does  not deal with files,	so it requires
       redirections to be used with them.

       In contrast to grep, string's match defaults to	glob-mode,  while  re-
       place defaults to literal matching. If set to regex-mode, they use PCRE
       regular expressions, which is comparable	to grep's -P option. match de-
       faults  to  printing  just  the	match, which is	like grep with -o (use
       --entire	to enable grep-like behavior).

       Like sed's s/old/new/ command, string replace still prints strings that
       don't  match.  sed's -n in combination with a /p	modifier or command is
       like string replace -f.

       string split somedelimiter is a replacement for tr somedelimiter	\n.

   string-collect - join strings into one
   Synopsis
	  string collect [(-N |	--no-trim-newlines)] [STRING...]

   Description
       string collect collects its input into a	single output argument,	 with-
       out  splitting  the output when used in a command substitution. This is
       useful when trying to collect multiline	output	from  another  command
       into a variable.	Exit status: 0 if any output argument is non-empty, or
       1 otherwise.

       If invoked with multiple	arguments instead  of  input,  string  collect
       preserves  each	argument  separately, where the	number of output argu-
       ments is	equal to the number of arguments given to string collect.

       Any trailing newlines on	the input are trimmed, just as	with  "$(cmd)"
       substitution  in	sh. --no-trim-newlines can be used to disable this be-
       havior, which may be useful when	running	a command such as set contents
       (cat filename | string collect -N).

   Examples
	  >_ echo \"(echo one\ntwo\nthree | string collect)\"
	  "one
	  two
	  three"

	  >_ echo \"(echo one\ntwo\nthree | string collect -N)\"
	  "one
	  two
	  three
	  "

   string-escape - escape special characters
   Synopsis
	  string escape	[(-n | --no-quoted)] [--style=xxx] [STRING...]
	  string unescape [--style=xxx]	[STRING...]

   Description
       string  escape  escapes	each STRING in one of three ways. The first is
       --style=script. This is the default. It alters the string such that  it
       can  be	passed back to eval to produce the original argument again. By
       default,	all special characters are escaped, and	 quotes	 are  used  to
       simplify	 the  output when possible. If -n or --no-quoted is given, the
       simplifying quoted format is not	used. Exit status: 0 if	at  least  one
       string was escaped, or 1	otherwise.

       --style=var  ensures  the  string can be	used as	a variable name	by hex
       encoding	any non-alphanumeric characters. The string is first converted
       to UTF-8	before being encoded.

       --style=url ensures the string can be used as a URL by hex encoding any
       character which is not legal in a URL. The string is first converted to
       UTF-8 before being encoded.

       --style=regex  escapes  an  input  string for literal matching within a
       regex expression. The string is first converted to UTF-8	 before	 being
       encoded.

       string  unescape	 performs the inverse of the string escape command. If
       the string to be	unescaped is not properly formatted it is ignored. For
       example,	 doing	string unescape	--style=var (string escape --style=var
       $str) will return the original string. There is no support for unescap-
       ing --style=regex.

   Examples
	  >_ echo \x07 | string	escape
	  \cg

	  >_ string escape --style=var 'a1 b2'\u6161
	  a1_20_b2_E6_85_A1_

   string-join - join strings with delimiter
   Synopsis
	  string join [(-q | --quiet)] SEP [STRING...]
	  string join0 [(-q | --quiet)]	[STRING...]

   Description
       string  join  joins its STRING arguments	into a single string separated
       by SEP, which can be an empty string. Exit status: 0 if	at  least  one
       join was	performed, or 1	otherwise.

       string  join0 joins its STRING arguments	into a single string separated
       by the zero byte	(NUL), and adds	a trailing NUL.	This is	most useful in
       conjunction  with  tools	 that accept NUL-delimited input, such as sort
       -z. Exit	status:	0 if at	least one join was performed, or 1 otherwise.

       Because Unix uses NUL as	the string terminator, passing the  output  of
       string  join0  as an argument to	a command (via a command substitution)
       won't actually work. Fish will pass the correct bytes  along,  but  the
       command	won't be able to tell where the	argument ends. This is a limi-
       tation of Unix' argument	passing.

   Examples
	  >_ seq 3 | string join ...
	  1...2...3

	  # Give a list	of NUL-separated filenames to du (this is a GNU	extension)
	  >_ string join0 file1	file2 file\nwith\nmultiple\nlines | du --files0-from=-

	  # Just put the strings together without a separator
	  >_ string join '' a b	c
	  abc

   string-join0	- join strings with zero bytes
   Synopsis
	  string join [(-q | --quiet)] SEP [STRING...]
	  string join0 [(-q | --quiet)]	[STRING...]

   Description
       string join joins its STRING arguments into a single  string  separated
       by  SEP,	 which	can be an empty	string.	Exit status: 0 if at least one
       join was	performed, or 1	otherwise.

       string join0 joins its STRING arguments into a single string  separated
       by the zero byte	(NUL), and adds	a trailing NUL.	This is	most useful in
       conjunction with	tools that accept NUL-delimited	input,	such  as  sort
       -z. Exit	status:	0 if at	least one join was performed, or 1 otherwise.

       Because	Unix  uses NUL as the string terminator, passing the output of
       string join0 as an argument to a	command	(via a	command	 substitution)
       won't  actually	work.  Fish will pass the correct bytes	along, but the
       command won't be	able to	tell where the argument	ends. This is a	 limi-
       tation of Unix' argument	passing.

   Examples
	  >_ seq 3 | string join ...
	  1...2...3

	  # Give a list	of NUL-separated filenames to du (this is a GNU	extension)
	  >_ string join0 file1	file2 file\nwith\nmultiple\nlines | du --files0-from=-

	  # Just put the strings together without a separator
	  >_ string join '' a b	c
	  abc

   string-length - print string	lengths
   Synopsis
	  string length	[(-q | --quiet)] [STRING...]

   Description
       string length reports the length	of each	string argument	in characters.
       Exit status: 0 if at least one non-empty	STRING was given, or 1	other-
       wise.

   Examples
	  >_ string length 'hello, world'
	  12

	  >_ set str foo
	  >_ string length -q $str; echo $status
	  0
	  # Equivalent to test -n "$str"

   string-lower	- convert strings to lowercase
   Synopsis
	  string lower [(-q | --quiet)]	[STRING...]

   Description
       string lower converts each string argument to lowercase.	Exit status: 0
       if at least one string was converted to lowercase, else 1.  This	 means
       that  in	 conjunction  with  the	-q flag	you can	readily	test whether a
       string is already lowercase.

   string-match	- match	substrings
   Synopsis
	  string match [(-a | --all)] [(-e | --entire)]	[(-i | --ignore-case)] [(-r | --regex)]	[(-n | --index)] [(-q |	--quiet)] [(-v | --invert)] PATTERN [STRING...]

   Description
       string match tests each STRING against PATTERN and prints matching sub-
       strings.	 Only the first	match for each STRING is reported unless -a or
       --all is	given, in which	case all matches are reported.

       If you specify the -e or	--entire then each matching string is  printed
       including  any  prefix or suffix	not matched by the pattern (equivalent
       to grep without the -o flag). You can, obviously, achieve the same  re-
       sult  by	 prepending  and appending * or	.* depending on	whether	or not
       you have	specified the --regex flag. The	--entire flag is simply	a  way
       to  avoid having	to complicate the pattern in that fashion and make the
       intent of the string match clearer. Without  --entire  and  --regex,  a
       PATTERN	will  need  to	match  the entire STRING before	it will	be re-
       ported.

       Matching	can be made case-insensitive with --ignore-case	or -i.

       If --index or -n	is given, each match is	reported as  a	1-based	 start
       position	 and  a	 length.  By default, PATTERN is interpreted as	a glob
       pattern matched against each entire STRING argument. A glob pattern  is
       only considered a valid match if	it matches the entire STRING.

       If  --regex or -r is given, PATTERN is interpreted as a Perl-compatible
       regular expression, which does not have to match	the entire STRING. For
       a  regular  expression containing capturing groups, multiple items will
       be reported for each match, one for the entire match and	one  for  each
       capturing  group.  With this, only the matching part of the STRING will
       be reported, unless --entire is given.

       When matching via regular expressions, string match automatically  sets
       variables for all named capturing groups	((?<name>expression)). It will
       create a	variable with the name of the group, in	the default scope, for
       each  named  capturing  group, and set it to the	value of the capturing
       group in	the first matched argument. If a named capture	group  matched
       an empty	string,	the variable will be set to the	empty string (like set
       var "").	If it did not match, the variable will be set to nothing (like
       set var).  When --regex is used with --all, this	behavior changes. Each
       named variable will contain a list of matches,  with  the  first	 match
       contained  in the first element,	the second match in the	second,	and so
       on. If the group	was empty or did not match, the	corresponding  element
       will be an empty	string.

       If  --invert  or	-v is used the selected	lines will be only those which
       do not match the	given glob pattern or regular expression.

       Exit status: 0 if at least one match was	found, or 1 otherwise.

   Examples
   Match Glob Examples
	  >_ string match '?' a
	  a

	  >_ string match 'a*b'	axxb
	  axxb

	  >_ string match -i 'a??B' Axxb
	  Axxb

	  >_ echo 'ok?'	| string match '*\?'
	  ok?

	  # Note that only the second STRING will match	here.
	  >_ string match 'foo'	'foo1' 'foo' 'foo2'
	  foo

	  >_ string match -e 'foo' 'foo1' 'foo'	'foo2'
	  foo1
	  foo
	  foo2

	  >_ string match 'foo?' 'foo1'	'foo' 'foo2'
	  foo1
	  foo2

   Match Regex Examples
	  >_ string match -r 'cat|dog|fish' 'nice dog'
	  dog

	  >_ string match -r -v	"c.*[12]" {cat,dog}(seq	1 4)
	  dog1
	  dog2
	  cat3
	  dog3
	  cat4
	  dog4

	  >_ string match -r '(\d\d?):(\d\d):(\d\d)' 2:34:56
	  2:34:56
	  2
	  34
	  56

	  >_ string match -r '^(\w{2,4})\1$' papa mud murmur
	  papa
	  pa
	  murmur
	  mur

	  >_ string match -r -a	-n at ratatat
	  2 2
	  4 2
	  6 2

	  >_ string match -r -i	'0x[0-9a-f]{1,8}' 'int magic = 0xBadC0de;'
	  0xBadC0de

	  >_ echo $version
	  3.1.2-1575-ga2ff32d90
	  >_ string match -rq '(?<major>\d+).(?<minor>\d+).(?<revision>\d+)' --	$version
	  >_ echo "You are using fish $major!"
	  You are using	fish 3!

	  >_ string match -raq ' *(?<sentence>[^.!?]+)(?<punctuation>[.!?])?' "hello, friend. goodbye"
	  >_ printf "%s\n" -- $sentence
	  hello, friend
	  goodbye
	  >_ printf "%s\n" -- $punctuation
	  .

	  >_ string match -rq '(?<word>hello)' 'hi'
	  >_ count $word
	  0

   string-pad -	pad strings to a fixed width
   Synopsis
	  string pad [(-r | --right)] [(-c | --char) CHAR] [(-w	| --width) INTEGER] [STRING...]

   Description
       string pad extends each STRING to the given width by adding CHAR	to the
       left.

       If -r or	--right	is given, add the padding after	a string.

       If -c or	--char is given, pad with CHAR instead of whitespace.

       The  output  is padded to the maximum width of all input	strings. If -w
       or --width is given, use	at least that.

   Examples
	  >_ string pad	-w 10 abc abcdef
		 abc
	      abcdef

	  >_ string pad	--right	--char=dh "fish	are pretty" "rich. "
	  fish are pretty
	  rich.	 dhdhdhdh

	  >_ string pad	-w$COLUMNS (date)
	  # Prints the current time on the right edge of the screen.

   See Also
       o The printf command can	do simple padding, for example	printf	%10s\n
	 works like string pad -w10.

   string-repeat - multiply a string
   Synopsis
	  string repeat	[(-n | --count)	COUNT] [(-m | --max) MAX] [(-N | --no-newline)]	[(-q | --quiet)] [STRING...]

   Description
       string  repeat  repeats the STRING -n or	--count	times. The -m or --max
       option will limit the number of outputted char (excluding the newline).
       This  option  can  be used by itself or in conjunction with --count. If
       both --count and	--max are present, max char will  be  outputed	unless
       the  final  repeated  string  size  is less than	max, in	that case, the
       string will repeat until	count has been reached.	Both --count and --max
       will  accept  a	number	greater	 than or equal to zero,	in the case of
       zero, nothing will be outputed. If -N or	 --no-newline  is  given,  the
       output  won't contain a newline character at the	end. Exit status: 0 if
       yielded string is not empty, 1 otherwise.

   Examples
   Repeat Examples
	  >_ string repeat -n 2	'foo '
	  foo foo

	  >_ echo foo |	string repeat -n 2
	  foofoo

	  >_ string repeat -n 2	-m 5 'foo'
	  foofo

	  >_ string repeat -m 5	'foo'
	  foofo

   string-replace - replace substrings
   Synopsis
	  string replace [(-a |	--all)]	[(-f | --filter)] [(-i | --ignore-case)] [(-r |	--regex)] [(-q | --quiet)] PATTERN REPLACEMENT [STRING...]

   Description
       string replace is similar to string match but replaces  non-overlapping
       matching	substrings with	a replacement string and prints	the result. By
       default,	PATTERN	is treated as a	literal	substring to be	matched.

       If -r or	--regex	is given, PATTERN is interpreted as a  Perl-compatible
       regular	expression,  and  REPLACEMENT  can  contain C-style escape se-
       quences like \t as well as references to	capturing groups by number  or
       name as $n or ${n}.

       If  you	specify	 the  -f  or  --filter	flag then each input string is
       printed only if a replacement was done. This is useful where you	 would
       otherwise use this idiom: a_cmd | string	match pattern |	string replace
       pattern new_pattern. You	can instead just write a_cmd | string  replace
       --filter	pattern	new_pattern.

       Exit  status:  0	if at least one	replacement was	performed, or 1	other-
       wise.

   Examples
   Replace Literal Examples
	  >_ string replace is was 'blue is my favorite'
	  blue was my favorite

	  >_ string replace 3rd	last 1st 2nd 3rd
	  1st
	  2nd
	  last

	  >_ string replace -a ' ' _ 'spaces to	underscores'
	  spaces_to_underscores

   Replace Regex Examples
	  >_ string replace -r -a '[^\d.]+' ' '	'0 one two 3.14	four 5x'
	  0 3.14 5

	  >_ string replace -r '(\w+)\s+(\w+)' '$2 $1 $$' 'left	right'
	  right	left $

	  >_ string replace -r '\s*newline\s*' '\n' 'put a newline here'
	  put a
	  here

   string-split	- split	strings	by delimiter
   Synopsis
	  string split [(-f | --fields)	FIELDS]	[(-m | --max) MAX] [(-n	| --no-empty)] [(-q | --quiet)]	[(-r | --right)] SEP [STRING...]
	  string split0	[(-f | --fields) FIELDS] [(-m |	--max) MAX] [(-n | --no-empty)]	[(-q | --quiet)] [(-r |	--right)] [STRING...]

   Description
       string split splits each	STRING on the separator	SEP, which can	be  an
       empty  string. If -m or --max is	specified, at most MAX splits are done
       on each STRING. If -r or	 --right  is  given,  splitting	 is  performed
       right-to-left.  This is useful in combination with -m or	--max. With -n
       or --no-empty, empty results  are  excluded  from  consideration	 (e.g.
       hello\n\nworld would expand to two strings and not three). Exit status:
       0 if at least one split was performed, or 1 otherwise.

       Use -f or --fields to print out specific	fields.	 Unless	 --allow-empty
       is  used,  if a given field does	not exist, then	the command exits with
       status 1	and does not print anything.

       See also	the --delimiter	option of the read command.

       string split0 splits each STRING	on the zero byte  (NUL).  Options  are
       the same	as string split	except that no separator is given.

       split0  has the important property that its output is not further split
       when used in a command substitution, allowing for the command substitu-
       tion  to	produce	elements containing newlines. This is most useful when
       used with Unix tools that produce zero bytes, such as find  -print0  or
       sort -z.	See split0 examples below.

   Examples
	  >_ string split . example.com
	  example
	  com

	  >_ string split -r -m1 / /usr/local/bin/fish
	  /usr/local/bin
	  fish

	  >_ string split '' abc
	  a
	  b
	  c

	  >_ string split --allow-empty	-f1,3,5	'' abc
	  a
	  c

   NUL Delimited Examples
	  >_ # Count files in a	directory, without being confused by newlines.
	  >_ count (find . -print0 | string split0)
	  42

	  >_ # Sort a list of elements which may contain newlines
	  >_ set foo beta alpha\ngamma
	  >_ set foo (string join0 $foo	| sort -z | string split0)
	  >_ string escape $foo[1]
	  alpha\ngamma

   string-split0 - split on zero bytes
   Synopsis
	  string split [(-f | --fields)	FIELDS]	[(-m | --max) MAX] [(-n	| --no-empty)] [(-q | --quiet)]	[(-r | --right)] SEP [STRING...]
	  string split0	[(-f | --fields) FIELDS] [(-m |	--max) MAX] [(-n | --no-empty)]	[(-q | --quiet)] [(-r |	--right)] [STRING...]

   Description
       string  split  splits each STRING on the	separator SEP, which can be an
       empty string. If	-m or --max is specified, at most MAX splits are  done
       on  each	 STRING.  If  -r  or  --right is given,	splitting is performed
       right-to-left. This is useful in	combination with -m or --max. With  -n
       or  --no-empty,	empty  results	are  excluded from consideration (e.g.
       hello\n\nworld would expand to two strings and not three). Exit status:
       0 if at least one split was performed, or 1 otherwise.

       Use  -f	or --fields to print out specific fields. Unless --allow-empty
       is used,	if a given field does not exist, then the command  exits  with
       status 1	and does not print anything.

       See also	the --delimiter	option of the read command.

       string  split0  splits  each STRING on the zero byte (NUL). Options are
       the same	as string split	except that no separator is given.

       split0 has the important	property that its output is not	further	 split
       when used in a command substitution, allowing for the command substitu-
       tion to produce elements	containing newlines. This is most useful  when
       used  with  Unix	tools that produce zero	bytes, such as find -print0 or
       sort -z.	See split0 examples below.

   Examples
	  >_ string split . example.com
	  example
	  com

	  >_ string split -r -m1 / /usr/local/bin/fish
	  /usr/local/bin
	  fish

	  >_ string split '' abc
	  a
	  b
	  c

	  >_ string split --allow-empty	-f1,3,5	'' abc
	  a
	  c

   NUL Delimited Examples
	  >_ # Count files in a	directory, without being confused by newlines.
	  >_ count (find . -print0 | string split0)
	  42

	  >_ # Sort a list of elements which may contain newlines
	  >_ set foo beta alpha\ngamma
	  >_ set foo (string join0 $foo	| sort -z | string split0)
	  >_ string escape $foo[1]
	  alpha\ngamma

   string-sub -	extract	substrings
   Synopsis
	  string sub [(-s | --start) START] [(-e | --end) END] [(-l | --length)	LENGTH]	[(-q | --quiet)] [STRING...]

   Description
       string sub prints a substring of	each string argument. The start/end of
       the  substring can be specified with -s/-e or --start/--end followed by
       a 1-based index value. Positive index values are	relative to the	 start
       of  the string and negative index values	are relative to	the end	of the
       string. The default start value is 1. The length	of the	substring  can
       be  specified  with  -l or --length. If the length or end is not	speci-
       fied, the substring continues to	the end	of each	STRING.	Exit status: 0
       if  at  least  one  substring  operation	 was  performed,  1 otherwise.
       --length	is mutually exclusive with --end.

   Examples
	  >_ string sub	--length 2 abcde
	  ab

	  >_ string sub	-s 2 -l	2 abcde
	  bc

	  >_ string sub	--start=-2 abcde
	  de

	  >_ string sub	--end=3	abcde
	  abc

	  >_ string sub	-e -1 abcde
	  abcd

	  >_ string sub	-s 2 -e	-1 abcde
	  bcd

	  >_ string sub	-s -3 -e -2 abcde
	  c

   string-trim - remove	trailing whitespace
   Synopsis
	  string trim [(-l | --left)] [(-r | --right)] [(-c | --chars CHARS)] [(-q | --quiet)] [STRING...]

   Description
       string trim removes leading and trailing	whitespace from	 each  STRING.
       If  -l or --left	is given, only leading whitespace is removed. If -r or
       --right is given, only  trailing	 whitespace  is	 trimmed.  The	-c  or
       --chars	switch causes the characters in	CHARS to be removed instead of
       whitespace. Exit	status:	0 if at	least one character was	trimmed, or  1
       otherwise.

   Examples
	  >_ string trim ' abc	'
	  abc

	  >_ string trim --right --chars=yz xyzzy zany
	  x
	  zan

   string-unescape - expand escape sequences
   Synopsis
	  string escape	[(-n | --no-quoted)] [--style=xxx] [STRING...]
	  string unescape [--style=xxx]	[STRING...]

   Description
       string  escape  escapes	each STRING in one of three ways. The first is
       --style=script. This is the default. It alters the string such that  it
       can  be	passed back to eval to produce the original argument again. By
       default,	all special characters are escaped, and	 quotes	 are  used  to
       simplify	 the  output when possible. If -n or --no-quoted is given, the
       simplifying quoted format is not	used. Exit status: 0 if	at  least  one
       string was escaped, or 1	otherwise.

       --style=var  ensures  the  string can be	used as	a variable name	by hex
       encoding	any non-alphanumeric characters. The string is first converted
       to UTF-8	before being encoded.

       --style=url ensures the string can be used as a URL by hex encoding any
       character which is not legal in a URL. The string is first converted to
       UTF-8 before being encoded.

       --style=regex  escapes  an  input  string for literal matching within a
       regex expression. The string is first converted to UTF-8	 before	 being
       encoded.

       string  unescape	 performs the inverse of the string escape command. If
       the string to be	unescaped is not properly formatted it is ignored. For
       example,	 doing	string unescape	--style=var (string escape --style=var
       $str) will return the original string. There is no support for unescap-
       ing --style=regex.

   Examples
	  >_ echo \x07 | string	escape
	  \cg

	  >_ string escape --style=var 'a1 b2'\u6161
	  a1_20_b2_E6_85_A1_

   string-upper	- convert strings to uppercase
   Synopsis
	  string upper [(-q | --quiet)]	[STRING...]

   Description
       string upper converts each string argument to uppercase.	Exit status: 0
       if at least one string was converted to uppercase, else 1.  This	 means
       that  in	 conjunction  with  the	-q flag	you can	readily	test whether a
       string is already uppercase.

   suspend - suspend the current shell
   Synopsis
	  suspend [--force]

   Description
       suspend suspends	execution of the current shell by sending it a SIGTSTP
       signal,	returning  to the controlling process. It can be resumed later
       by sending it a SIGCONT.	 In order to prevent suspending	a  shell  that
       doesn't have a controlling process, it will not suspend the shell if it
       is a login shell. This requirement is bypassed if the --force option is
       given or	the shell is not interactive.

   switch - conditionally execute a block of commands
   Synopsis
	  switch VALUE;	[case [WILDCARD...]; [COMMANDS...]; ...] end

   Description
       switch performs one of several blocks of	commands, depending on whether
       a specified value equals	one of several wildcarded values. case is used
       together	 with  the  switch statement in	order to determine which block
       should be executed.

       Each case command is given one or more parameters. The first case  com-
       mand  with  a parameter that matches the	string specified in the	switch
       command will be evaluated. case parameters may contain wildcards. These
       need  to	be escaped or quoted in	order to avoid regular wildcard	expan-
       sion using filenames.

       Note that fish does not fall through on case statements.	Only the first
       matching	case is	executed.

       Note  that  command substitutions in a case statement will be evaluated
       even if its body	is not taken.  All  substitutions,  including  command
       substitutions,  must  be	 performed  before  the	 value can be compared
       against the parameter.

   Example
       If the variable $animal contains	the name of an animal,	the  following
       code would attempt to classify it:

	  switch $animal
	      case cat
		  echo evil
	      case wolf	dog human moose	dolphin	whale
		  echo mammal
	      case duck	goose albatross
		  echo bird
	      case shark trout stingray
		  echo fish
	      case '*'
		  echo I have no idea what a $animal is
	  end

       If  the	above code was run with	$animal	set to whale, the output would
       be mammal.

   test	- perform tests	on files and text
   Synopsis
	  test [EXPRESSION]
	  [ [EXPRESSION] ]

   Description
       Tests the expression given and sets the exit status to 0	if true, and 1
       if  false.  An expression is made up of one or more operators and their
       arguments.

       The first form  (test)  is  preferred.  For  compatibility  with	 other
       shells,	the second form	is available: a	matching pair of square	brack-
       ets ([ [EXPRESSION ] ]).

       This test is mostly POSIX-compatible.

       When using a variable as	an argument for	a test operator	you should al-
       most  always enclose it in double-quotes. There are only	two situations
       it is safe to omit the quote marks. The first is	when the argument is a
       literal	string	with  no whitespace or other characters	special	to the
       shell (e.g., semicolon).	For example, test -b /my/file. The  second  is
       using  a	variable that expands to exactly one element including if that
       element is the empty string (e.g., set x	''). If	the  variable  is  not
       set,  set but with no value, or set to more than	one value you must en-
       close it	in double-quotes. For example, test "$x" = "$y". Since	it  is
       always safe to enclose variables	in double-quotes when used as test ar-
       guments that is the recommended practice.

   Operators for files and directories
       o -b FILE returns true if FILE is a block device.

       o -c FILE returns true if FILE is a character device.

       o -d FILE returns true if FILE is a directory.

       o -e FILE returns true if FILE exists.

       o -f FILE returns true if FILE is a regular file.

       o -g FILE returns true if FILE has the set-group-ID bit set.

       o -G FILE returns true if FILE exists and has the same group ID as  the
	 current user.

       o -k  FILE  returns true	if FILE	has the	sticky bit set.	If the OS does
	 not	support	   the	  concept    it	    returns	false.	   See
	 https://en.wikipedia.org/wiki/Sticky_bit.

       o -L FILE returns true if FILE is a symbolic link.

       o -O FILE returns true if FILE exists and is owned by the current user.

       o -p FILE returns true if FILE is a named pipe.

       o -r FILE returns true if FILE is marked	as readable.

       o -s FILE returns true if the size of FILE is greater than zero.

       o -S FILE returns true if FILE is a socket.

       o -t FD returns true if the file	descriptor FD is a terminal (TTY).

       o -u FILE returns true if FILE has the set-user-ID bit set.

       o -w  FILE  returns  true if FILE is marked as writable;	note that this
	 does not check	if the filesystem is read-only.

       o -x FILE returns true if FILE is marked	as executable.

   Operators for text strings
       o STRING1 = STRING2 returns true	if the strings STRING1 and STRING2 are
	 identical.

       o STRING1  !=  STRING2  returns true if the strings STRING1 and STRING2
	 are not identical.

       o -n STRING returns true	if the length of STRING	is non-zero.

       o -z STRING returns true	if the length of STRING	is zero.

   Operators to	compare	and examine numbers
       o NUM1 -eq NUM2 returns true if NUM1 and	NUM2 are numerically equal.

       o NUM1 -ne NUM2 returns true if	NUM1  and  NUM2	 are  not  numerically
	 equal.

       o NUM1 -gt NUM2 returns true if NUM1 is greater than NUM2.

       o NUM1 -ge NUM2 returns true if NUM1 is greater than or equal to	NUM2.

       o NUM1 -lt NUM2 returns true if NUM1 is less than NUM2.

       o NUM1 -le NUM2 returns true if NUM1 is less than or equal to NUM2.

       Both integers and floating point	numbers	are supported.

   Operators to	combine	expressions
       o COND1 -a COND2	returns	true if	both COND1 and COND2 are true.

       o COND1 -o COND2	returns	true if	either COND1 or	COND2 are true.

       Expressions can be inverted using the ! operator:

       o !  EXPRESSION	returns	 true if EXPRESSION is false, and false	if EX-
	 PRESSION is true.

       Expressions can be grouped using	parentheses.

       o ( EXPRESSION )	returns	the value of EXPRESSION.
	  Note that parentheses	will usually require escaping with \( to avoid
	  being	interpreted as a command substitution.

   Examples
       If the /tmp directory exists, copy the /etc/motd	file to	it:

	  if test -d /tmp
	      cp /etc/motd /tmp/motd
	  end

       If  the	variable MANPATH is defined and	not empty, print the contents.
       (If MANPATH is not defined, then	it will	expand to zero arguments,  un-
       less quoted.)

	  if test -n "$MANPATH"
	      echo $MANPATH
	  end

       Parentheses and the -o and -a operators can be combined to produce more
       complicated expressions.	In this	example, success is printed  if	 there
       is a /foo or /bar file as well as a /baz	or /bat	file.

	  if test \( -f	/foo -o	-f /bar	\) -a \( -f /baz -o -f /bat \)
	      echo Success.
	  end.

       Numerical  comparisons will simply fail if one of the operands is not a
       number:

	  if test 42 -eq "The answer to	life, the universe and everything"
	      echo So long and thanks for all the fish # will not be executed
	  end

       A common	comparison is with $status:

	  if test $status -eq 0
	      echo "Previous command succeeded"
	  end

       The previous test can likewise be inverted:

	  if test ! $status -eq	0
	      echo "Previous command failed"
	  end

       which is	logically equivalent to	the following:

	  if test $status -ne 0
	      echo "Previous command failed"
	  end

   Standards
       test implements a subset	of the IEEE Std	 1003.1-2008  (POSIX.1)	 stan-
       dard. The following exceptions apply:

       o The < and > operators for comparing strings are not implemented.

       o Because  this	test  is a shell builtin and not a standalone utility,
	 using the -c flag on a	special	file descriptors like  standard	 input
	 and  output may not return the	same result when invoked from within a
	 pipe as one would expect when invoking	the test  utility  in  another
	 shell.
	  In  cases  such  as this, one	can use	command	test to	explicitly use
	  the system's standalone test rather than this	builtin	test.

   time	- measure how long a command or	block takes
   Synopsis
	  time COMMAND

   Description
       time causes fish	to measure how long a command takes and	print the  re-
       sults  afterwards. The command can be a simple fish command or a	block.
       The results can not currently be	redirected.

       For checking timing after a command has completed, check	$CMD_DURATION.

       Your system most	likely also has	a time command.	To use that use	 some-
       thing  like command time, as in command time sleep 10. Because it's not
       inside fish, it won't have access to fish functions and won't  be  able
       to time blocks and such.

   Example
       (for obvious reasons exact results will vary on your system)

	  >_ time sleep	1s

	  ________________________________________________________
	  Executed in	 1,01 secs   fish	    external
	     usr time	 2,32 millis	0,00 micros    2,32 millis
	     sys time	 0,88 millis  877,00 micros    0,00 millis

	  >_ time for i	in 1 2 3; sleep	1s; end

	  ________________________________________________________
	  Executed in	 3,01 secs   fish	    external
	     usr time	 9,16 millis	2,94 millis    6,23 millis
	     sys time	 0,23 millis	0,00 millis    0,23 millis

       Inline variable assignments need	to follow the time keyword:

	  >_ time a_moment=1.5m	sleep $a_moment

	  ________________________________________________________
	  Executed in	90.00 secs	fish	       external
	     usr time	 4.62 millis	4.62 millis    0.00 millis
	     sys time	 2.35 millis	0.41 millis    1.95 millis

   trap	- perform an action when the shell receives a signal
   Synopsis
	  trap [OPTIONS] [[ARG]	REASON ... ]

   Description
       trap  is	 a wrapper around the fish event delivery framework. It	exists
       for backwards compatibility with	POSIX shells. For other	 uses,	it  is
       recommended to define an	event handler.

       The following parameters	are available:

       o ARG is	the command to be executed on signal delivery.

       o REASON	 is  the name of the event to trap. For	example, a signal like
	 INT or	SIGINT,	or the special symbol EXIT.

       o -l or --list-signals prints a list of signal names.

       o -p or --print prints all defined signal handlers.

       If ARG and REASON are both specified, ARG is the	command	to be executed
       when  the  event	specified by REASON occurs (e.g., the signal is	deliv-
       ered).

       If ARG is absent	(and there is a	single REASON) or  -,  each  specified
       signal  is reset	to its original	disposition (the value it had upon en-
       trance to the shell).  If ARG is	the null string	the  signal  specified
       by each REASON is ignored by the	shell and by the commands it invokes.

       If  ARG is not present and -p has been supplied,	then the trap commands
       associated with each REASON are displayed. If no	arguments are supplied
       or  if  only  -p	 is given, trap	prints the list	of commands associated
       with each signal.

       Signal names are	case insensitive and the SIG prefix is optional.

       The exit	status is 1 if any REASON is invalid; otherwise	 trap  returns
       0.

   Example
	  trap "status --print-stack-trace" SIGUSR1
	  # Prints a stack trace each time the SIGUSR1 signal is sent to the shell.

   true	- return a successful result
   Synopsis
	  true

   Description
       true sets the exit status to 0.

   See Also
       o false command

       o $status variable

   type	- indicate how a command would be interpreted
   Synopsis
	  type [OPTIONS] NAME [NAME ...]

   Description
       With  no	 options, type indicates how each NAME would be	interpreted if
       used as a command name.

       The following options are available:

       o -a or --all prints all	 of  possible  definitions  of	the  specified
	 names.

       o -s or --short suppresses function expansion when used with no options
	 or with -a/--all.

       o -f or --no-functions suppresses function and builtin lookup.

       o -t or --type prints function, builtin,	or file	if  NAME  is  a	 shell
	 function, builtin, or disk file, respectively.

       o -p  or	 --path	 prints	 the  path to NAME if NAME resolves to an exe-
	 cutable file in $PATH,	the path to the	script containing the  defini-
	 tion  of the function NAME if NAME resolves to	a function loaded from
	 a file	on disk	(i.e. not interactively	defined	 at  the  prompt),  or
	 nothing otherwise.

       o -P or --force-path returns the	path to	the executable file NAME, pre-
	 suming	NAME is	found in $PATH,	or nothing otherwise. --force-path ex-
	 plicitly resolves only	the path to executable files in	$PATH, regard-
	 less of whether $NAME is shadowed by a	function or builtin  with  the
	 same name.

       o -q  or	--query	suppresses all output; this is useful when testing the
	 exit status. For compatibility	with old fish versions	this  is  also
	 --quiet.

       The  -q,	-p, -t and -P flags (and their long flag aliases) are mutually
       exclusive. Only one can be specified at a time.

   Example
	  >_ type fg
	  fg is	a builtin

   ulimit - set	or get resource	usage limits
   Synopsis
	  ulimit [OPTIONS] [LIMIT]

   Description
       ulimit sets or outputs the resource usage limits	of the shell  and  any
       processes  spawned  by it. If a new limit value is omitted, the current
       value of	the limit of the resource is printed; otherwise, the specified
       limit is	set to the new value.

       Use  one	 of  the following switches to specify which resource limit to
       set or report:

       o -c or --core-size: the	maximum	size of	core files created. By setting
	 this limit to zero, core dumps	can be disabled.

       o -d or --data-size: the	maximum	size of	a process' data	segment.

       o -f or --file-size: the	maximum	size of	files created by the shell.

       o -l or --lock-size: the	maximum	size that may be locked	into memory.

       o -m or --resident-set-size: the	maximum	resident set size.

       o -n  or	 --file-descriptor-count:  the maximum number of open file de-
	 scriptors (most systems do not	allow this value to be set).

       o -s or --stack-size: the maximum stack size.

       o -t or --cpu-time: the maximum amount of CPU time in seconds.

       o -u or --process-count:	the maximum number of processes	available to a
	 single	user.

       o -v  or	 --virtual-memory-size	The  maximum  amount of	virtual	memory
	 available to the shell.

       Note that not all these limits are available in all operating systems.

       The value of limit can be a number in the unit specified	 for  the  re-
       source  or  one	of  the	special	values hard, soft, or unlimited, which
       stand for the current hard limit, the current soft limit, and no	limit,
       respectively.

       If limit	is given, it is	the new	value of the specified resource. If no
       option is given,	then -f	is assumed. Values are	in  kilobytes,	except
       for  -t,	 which is in seconds and -n and	-u, which are unscaled values.
       The exit	status is 0 unless an invalid option or	argument is  supplied,
       or an error occurs while	setting	a new limit.

       ulimit  also accepts the	following switches that	determine what type of
       limit to	set:

       o -H or --hard sets hard	resource limit

       o -S or --soft sets soft	resource limit

       A hard limit can	only be	decreased. Once	it is set  it  cannot  be  in-
       creased;	 a  soft  limit	 may  be increased up to the value of the hard
       limit. If neither -H nor	-S is specified, both the soft and hard	limits
       are  updated  when  assigning  a	new limit value, and the soft limit is
       used when reporting the current value.

       The following additional	options	are also understood by ulimit:

       o -a or --all prints all	current	limits

       The fish	implementation of ulimit should	behave identically to the  im-
       plementation in bash, except for	these differences:

       o Fish ulimit supports GNU-style	long options for all switches

       o Fish ulimit does not support the -p option for	getting	the pipe size.
	 The bash implementation consists of a compile-time check that empiri-
	 cally	guesses	 this number by	writing	to a pipe and waiting for SIG-
	 PIPE. Fish does not do	this because it	 this  method  of  determining
	 pipe size is unreliable. Depending on bash version, there may also be
	 further additional limits to set in bash that do not exist in fish.

       o Fish ulimit does not support getting or setting  multiple  limits  in
	 one command, except reporting all values using	the -a switch

   Example
       ulimit -Hs 64 sets the hard stack size limit to 64 kB.

   umask - set or get the file creation	mode mask
   Synopsis
	  umask	[OPTIONS] [MASK]

   Description
       umask displays and manipulates the "umask", or file creation mode mask,
       which is	used to	restrict the default access to files.

       The umask may be	expressed either as an octal number, which  represents
       the rights that will be removed by default, or symbolically, which rep-
       resents the only	rights that will be granted by default.

       Access rights are explained in the manual page for  the	chmod(1)  pro-
       gram.

       With  no	 parameters, the current file creation mode mask is printed as
       an octal	number.

       o -h or --help prints this message.

       o -S or --symbolic prints the umask in symbolic form instead  of	 octal
	 form.

       o -p  or	--as-command outputs the umask in a form that may be reused as
	 input

       If a numeric mask is specified as  a  parameter,	 the  current  shell's
       umask  will be set to that value, and the rights	specified by that mask
       will be removed from new	files and directories by default.

       If a symbolic mask is specified,	the desired permission bits,  and  not
       the  inverse, should be specified. A symbolic mask is a comma separated
       list of rights. Each right consists of three parts:

       o The first part	specifies to whom this set of right applies,  and  can
	 be one	of u, g, o or a, where u specifies the user who	owns the file,
	 g specifies the group owner of	 the  file,  o	specific  other	 users
	 rights	and a specifies	all three should be changed.

       o The second part of a right specifies the mode,	and can	be one of =, +
	 or -, where = specifies that the rights should	 be  set  to  the  new
	 value,	 + specifies that the specified	right should be	added to those
	 previously specified and - specifies that the specified rights	should
	 be removed from those previously specified.

       o The third part	of a right specifies what rights should	be changed and
	 can be	any combination	of r, w	and x, representing  read,  write  and
	 execute rights.

       If the first and	second parts are skipped, they are assumed to be a and
       =, respectively.	As an example, r,u+w means all users should have  read
       access and the file owner should	also have write	access.

       Note that symbolic masks	currently do not work as intended.

   Example
       umask  177  or umask u=rw sets the file creation	mask to	read and write
       for the owner and no permissions	at all for any other users.

   vared - interactively edit the value	of an environment variable
   Synopsis
	  vared	VARIABLE_NAME

   Description
       vared is	used to	interactively edit the value of	an  environment	 vari-
       able. Array variables as	a whole	can not	be edited using	vared, but in-
       dividual	list elements can.

   Example
       vared PATH[3] edits the third element of	the PATH list

   wait	- wait for jobs	to complete
   Synopsis
	  wait [-n | --any] [PID | PROCESS_NAME] ...

   Description
       wait waits for child jobs to complete.

       o If a pid is specified,	the command waits for the job that the process
	 with the pid belongs to.

       o If  a	process	name is	specified, the command waits for the jobs that
	 the matched processes belong to.

       o If neither a pid nor a	process	name is	specified, the	command	 waits
	 for all background jobs.

       o If  the  -n  /	--any flag is provided,	the command returns as soon as
	 the first job completes. If it	is not provided, it returns after  all
	 jobs complete.

   Example
	  sleep	10 &
	  wait $last_pid

       spawns sleep in the background, and then	waits until it finishes.

	  for i	in (seq	1 5); sleep 10 &; end
	  wait

       spawns  five  jobs  in the background, and then waits until all of them
       finishes.

	  for i	in (seq	1 5); sleep 10 &; end
	  hoge &
	  wait sleep

       spawns five jobs	and hoge in the	background, and	then waits  until  all
       sleeps finish, and doesn't wait for hoge	finishing.

   while - perform a command multiple times
   Synopsis
	  while	CONDITION; COMMANDS...;	end

   Description
       while  repeatedly executes CONDITION, and if the	exit status is 0, then
       executes	COMMANDS.

       The exit	status of the while loop is the	exit status of the last	itera-
       tion  of	 the  COMMANDS	executed,  or  0  if none were executed. (This
       matches other shells and	is POSIX-compatible.)

       You can use and or or for complex conditions. Even more complex control
       can be achieved with while true containing a break.

   Example
	  while	test -f	foo.txt; or test -f bar.txt ; echo file	exists;	sleep 10; end
	  # outputs 'file exists' at 10	second intervals,
	  # as long as the file	foo.txt	or bar.txt exists.

   Fish	for bash users
       This  is	 to  give  you a quick overview	if you come from bash (or to a
       lesser extent other shells like zsh or ksh) and want to know  how  fish
       differs.	Fish is	intentionally not POSIX-compatible and as such some of
       the things you are used to work differently.

       Many things are similar - they both fundamentally  expand  commandlines
       to  execute  commands,  have pipes, redirections, variables, globs, use
       command output in various ways. This document is	there to quickly  show
       you the differences.

   Command substitutions
       Fish  spells  command  substitutions as (command) instead of $(command)
       (or `command`).

       In addition, it only splits them	on newlines instead of	$IFS.  If  you
       want  to	 split	on  something else, use	string split, string split0 or
       string collect. If those	are used as the	last command in	a command sub-
       stitution the splits they create	are carried over. So:

	  for i	in (find . -print0 | string split0)

       will correctly handle all possible filenames.

   Variables
       Fish  sets and erases variables with set	instead	of VAR=VAL and declare
       and unset and export. set takes options to determine the	scope and  ex-
       portedness of a variable:

	  # Define $PAGER global and exported, so this is like ``export	PAGER=less``
	  set -gx PAGER	less

	  # Define $alocalvariable only	locally	- like ``local alocalvariable=foo``
	  set -l alocalvariable	foo

       or to erase variables:

	  set -e PAGER

       VAR=VAL statements are available	as environment overrides:

	  PAGER=cat git	log

       Fish does not perform word splitting. Once a variable has been set to a
       value, that value stays as it is, so double-quoting variable expansions
       isn't the necessity it is in bash. [1]

       For instance, here's bash

	  > foo="bar baz"
	  > printf '"%s"\n' $foo # will	print two lines, because we didn't double-quote, so the	variable is split
	  "bar"
	  "baz"

       And here	is fish:

	  > set	foo "bar baz"
	  > printf '"%s"\n' $foo # foo was set as one element, so it will be passed as one element, so this is one line
	  "bar baz"

       All  variables  are "arrays" (we	use the	term "lists"), and expanding a
       variable	expands	to all its elements, with each element as its own  ar-
       gument (like bash's "${var[@]}":

	  > set	var "foo bar" banana
	  > printf %s\n	$var
	  foo bar
	  banana

       Specific	elements of a list can be selected:

	  echo $list[5..7]

       [1]  zsh	  also	does  not  perform  word  splitting  by	 default  (the
	    SH_WORD_SPLIT option controls this)

   Wildcards (globs)
       Fish only supports the *	and ** glob (and the deprecated	? glob). If  a
       glob doesn't match it fails the command (like with bash's failglob) un-
       less the	command	is for,	set or count or	the glob is used with an envi-
       ronment	override  (VAR=* command), in which case it expands to nothing
       (like with bash's nullglob option).

       Globbing	doesn't	happen on expanded variables, so:

	  set foo "*"
	  echo $foo

       will not	match any files.

       There are no options to control globbing	 so  it	 always	 behaves  like
       that.

   Quoting
       Fish  has two quoting styles: ""	and ''.	Variables are expanded in dou-
       ble-quotes, nothing is expanded in single-quotes.

       There is	no $'',	instead	the sequences that would transform are	trans-
       formed when unquoted:

	  > echo a\nb
	  a
	  b

   String manipulation
       Fish  does  not have ${foo%bar},	${foo#bar} and ${foo/bar/baz}. Instead
       string manipulation is done by the string builtin.

   Special variables
       Some bash variables and their closest fish equivalent:

       o $*, $@, $1 and	so on: $argv

       o $?: $status

       o $$: $fish_pid

       o $#: No	variable, instead use count $argv

       o $!: $last_pid

       o $0: status filename

       o $-: Mostly status is-interactive and status is-login

   Process substitution
       Instead of <(command) fish uses (command	| psub). There is  no  equiva-
       lent to >(command).

       Note that both of these are bashisms, and most things can easily	be ex-
       pressed without.	E.g. instead of:

	  source (command | psub)

       just use:

	  command | source

       as fish's source	can read from stdin.

   Heredocs
       Fish does not have <<EOF	"heredocs". Instead of:

	  cat <<EOF
	  some string
	  some more string
	  EOF

       use:

	  printf %s\n "some string" "some more string"

       or:

	  echo "some string
	  some more string"

       Quotes are followed across newlines.

   Test	(test, [, [[)
       Fish has	a POSIX-compatible test	or [ builtin. There is no [[ and  test
       does  not  accept  == as	a synonym for =. It can	compare	floating point
       numbers,	however.

       set -q can be used to determine if a variable exists or has  a  certain
       number of elements (set -q foo[2]).

   Arithmetic Expansion
       Fish  does  not have $((i+1)) arithmetic	expansion, computation is han-
       dled by math:

	  math $i + 1

       It can handle floating point numbers:

	  > math 5 / 2
	  2.5

   Prompts
       Fish does not use the $PS1, $PS2	 and  so  on  variables.  Instead  the
       prompt	is   the   output   of	the  fish_prompt  function,  plus  the
       fish_mode_prompt	  function   if	  vi-mode   is	 enabled    and	   the
       fish_right_prompt function for the right	prompt.

       As an example, here's a relatively simple bash prompt:

	  # <$HOSTNAME>	<$PWD in blue> <Prompt Sign in Yellow> <Rest in	default	light white>
	  export PS1='\h\[\e[1;34m\]\w\[\e[m\] \[\e[1;32m\]\$\[\e[m\] '

       and a rough fish	equivalent:

	  function fish_prompt
	      set -l prompt_symbol '$'
	      fish_is_root_user; and set prompt_symbol '#'

	      echo -s $hostname	(set_color blue) (prompt_pwd) \
	      (set_color yellow) $prompt_symbol	(set_color normal)
	  end

       This shows a few	differences:

       o Fish provides set_color to color text.	It can use the 16 named	colors
	 and also RGB sequences	(so you	could also use set_color 5555FF)

       o Instead of introducing	specific escapes like \h for the hostname, the
	 prompt	is simply a function, so you can use variables like $hostname.

       o Fish  offers  helper  functions for adding things to the prompt, like
	 fish_vcs_prompt for adding a display for common version control  sys-
	 tems  (git,  mercurial,  svn)	and prompt_pwd for showing a shortened
	 $PWD (the user's home directory becomes ~ and any path	 component  is
	 shortened).

       The default prompt is reasonably	full-featured and its code can be read
       via type	fish_prompt.

       Fish does not have $PS2 for continuation	lines, instead it  leaves  the
       lines indented to show that the commandline isn't complete yet.

   Blocks and loops
       Fish's blocking constructs look a little	different. They	all start with
       a word, end in end and don't have a second starting word:

	  for i	in 1 2 3; do
	     echo $i
	  done

	  # becomes

	  for i	in 1 2 3
	     echo $i
	  end

	  while	true; do
	     echo Weeee
	  done

	  # becomes

	  while	true
	     echo Weeeeeee
	  end

	  {
	     echo Hello
	  }

	  # becomes

	  begin
	     echo Hello
	  end

	  if true; then
	     echo Yes I	am true
	  else
	     echo "How is true not true?"
	  fi

	  # becomes

	  if true
	     echo Yes I	am true
	  else
	     echo "How is true not true?"
	  end

	  foo()	{
	     echo foo
	  }

	  # becomes

	  function foo
	      echo foo
	  end

	  # (note that bash specifically allows	the word "function" as an extension, but POSIX only specifies the form without,	so it's	more compatible	to just	use the	form without)

       Fish does not have an until. Use	while not or while !.

   Subshells
       Bash has	a feature called "subshells",  where  it  will	start  another
       shell  process  for certain things. That	shell will then	be independent
       and e.g.	any changes it makes to	variables won't	be visible in the main
       shell.

       This includes things like:

	  # A list of commands in `()` parentheses
	  (foo;	bar) | baz

	  # Both sides of a pipe
	  foo |	while read -r bar; do
	      #	This variable will not be visible outside of the while loop.
	      VAR=VAL
	      #	This background	process	will not be, either
	      baz &
	  done

       ()  subshells are often confused	with {}	grouping, which	does not use a
       subshell. When you just need to group, you can use begin; end in	fish:

	  (foo;	bar) | baz
	  # when it should really have been:
	  { foo; bar } | baz
	  # becomes
	  begin; foo; bar; end | baz

       The pipe	will simply be run in the same process,	so  while  read	 loops
       can set variables outside:

	  foo |	while read bar
	      set -g VAR VAL
	      baz &
	  end

	  echo $VAR # will print VAL
	  jobs # will show "baz"

       Subshells  are  also  frequently	 confused  with	command	substitutions,
       which bash writes as `command` or $(command) and	fish writes  as	 (com-
       mand). Bash also	uses subshells to implement them.

       The  isolation  can usually be achieved by just scoping variables (with
       set -l),	but if you really do need to run your code in a	new shell  en-
       vironment  you can always use fish -c 'your code	here' to do so explic-
       itly.

   Builtins and	other commands
       By now it has become apparent that fish puts much more of  a  focus  on
       its  builtins and external commands rather than its syntax. So here are
       some helpful builtins and their rough equivalent	in bash:

       o string	- this replaces	most of	the string transformation (${i%foo} et
	 al) and can also be used instead of grep and sed and such.

       o math -	this replaces $((i + 1)) arithmetic and	can also do floats and
	 some simple functions (sine and friends).

       o argparse - this can handle a script's option parsing, for which  bash
	 would probably	use getopt (zsh	provides zparseopts).

       o count	can  be	used to	count things and therefore replaces $# and can
	 be used instead of wc.

       o status	provides information about the shell status, e.g. if it's  in-
	 teractive  or	what  the  current linenumber is. This replaces	$- and
	 $BASH_LINENO and other	variables.

       o seq(1)	can be used as a replacement for {1..10} range	expansion.  If
	 your OS doesn't ship a	seq fish includes a replacement	function.

   Tutorial
   Why fish?
       Fish  is	a fully-equipped command line shell (like bash or zsh) that is
       smart and user-friendly.	Fish supports powerful	features  like	syntax
       highlighting, autosuggestions, and tab completions that just work, with
       nothing to learn	or configure.

       If you want to make your	command	line more productive, more useful, and
       more  fun,  without learning a bunch of arcane syntax and configuration
       options,	then fish might	be just	what you're looking for!

   Getting started
       Once installed, just type in fish into your current  shell  to  try  it
       out!

       You  will  be  greeted by the standard fish prompt, which means you are
       all set up and can start	using fish:

	  > fish
	  Welcome to fish, the friendly	interactive shell
	  Type help for	instructions on	how to use fish
	  you@hostname ~>

       This prompt that	you see	above is the fish  default  prompt:  it	 shows
       your  username,	hostname,  and	working	 directory.   -	to change this
       prompt see how to change	your prompt - to switch	 to  fish  permanently
       see switch your default shell to	fish.

       From now	on, we'll pretend your prompt is just a	> to save space.

   Learning fish
       This  tutorial assumes a	basic understanding of command line shells and
       Unix commands, and that you have	a working copy of fish.

       If you have a strong understanding of other shells, and	want  to  know
       what  fish  does	 differently, search for the magic phrase unlike other
       shells, which is	used to	call out important differences.

       Or, if you want a quick overview	over the differences to	 other	shells
       like Bash, see Fish For Bash Users.

   Running Commands
       Fish  runs  commands like other shells: you type	a command, followed by
       its arguments. Spaces are separators:

	  > echo hello world
	  hello	world

       This runs the command echo with the arguments hello and world. In  this
       case  that's  the  same	as one argument	hello world, but in many cases
       it's not. If you	need to	pass an	argument that includes	a  space,  you
       can escape with a backslash, or quote it	using single or	double quotes:

	  > mkdir My\ Files
	  # Makes a directory called "My Files", with a	space in the name
	  > cp ~/Some\ File 'My	Files'
	  # Copies a file called "Some File" in	the home directory to "My Files"
	  > ls "My Files"
	  Some File

   Getting Help
       Run  help  to  open fish's help in a web	browser, and man with the page
       (like fish-language) to open it in a man	page. You  can	also  ask  for
       help  with  a  specific command,	for example, help set to open in a web
       browser,	or man set to see it in	the terminal.

	  > man	set
	  set -	handle shell variables
	    Synopsis...

   Syntax Highlighting
       You'll quickly notice that fish performs	 syntax	 highlighting  as  you
       type. Invalid commands are colored red by default:

	  > /bin/mkd

       A command may be	invalid	because	it does	not exist, or refers to	a file
       that you	cannot execute.	When the command becomes valid,	it is shown in
       a different color:

	  > /bin/mkdir

       Valid file paths	are underlined as you type them:

	  > cat	~/somefi

       This  tells you that there exists a file	that starts with somefi, which
       is useful feedback as you type.

       These colors, and many more, can	be changed by running fish_config,  or
       by modifying color variables directly.

   Wildcards
       Fish supports the familiar wildcard *. To list all JPEG files:

	  > ls *.jpg
	  lena.jpg
	  meena.jpg
	  santa	maria.jpg

       You can include multiple	wildcards:

	  > ls l*.p*
	  lena.png
	  lesson.pdf

       Especially  powerful is the recursive wildcard ** which searches	direc-
       tories recursively:

	  > ls /var/**.log
	  /var/log/system.log
	  /var/run/sntp.log

       If that directory traversal is taking a long time,  you	can  Control+C
       out of it.

       For more, see Wildcards.

   Pipes and Redirections
       You can pipe between commands with the usual vertical bar:

	  > echo hello world | wc
		1	2      12

       stdin  and stdout can be	redirected via the familiar < and >. stderr is
       redirected with a 2>.

	  > grep fish <	/etc/shells > ~/output.txt 2> ~/errors.txt

       To redirect stdout and stderr into one file, you	need to	first redirect
       stdout, and then	stderr into stdout:

	  > make > make_output.txt 2>&1

       For more, see Input and output redirections and Pipes.

   Autosuggestions
       As  you	type fish will suggest commands	to the right of	the cursor, in
       gray. For example:

	  > /bin/hostname

       It knows	about paths and	options:

	  > grep --ignore-case

       And history too.	Type a command once, and you can re-summon it by  just
       typing a	few letters:

	  > rsync -avze	ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo

       To  accept the autosuggestion, hit ^a (right arrow) or Control+F.	To ac-
       cept a single word of the autosuggestion, Alt+^a (right arrow).  If  the
       autosuggestion is not what you want, just ignore	it.

   Tab Completions
       A rich set of tab completions work "out of the box".

       Press  Tab  and fish will attempt to complete the command, argument, or
       path:

	  > /priTab => /private/

       If there's more than one	possibility, it	will list them:

	  > ~/stuff/sTab
	  ~/stuff/script.sh  (Executable, 4.8kB)  ~/stuff/sources/  (Directory)

       Hit tab again to	cycle through the possibilities.

       fish can	also complete many commands, like git branches:

	  > git	merge prTab => git merge prompt_designer
	  > git	checkout bTab
	  builtin_list_io_merge	(Branch) builtin_set_color (Branch) busted_events (Tag)

       Try hitting tab and see what fish can do!

   Variables
       Like other shells, a dollar sign	followed by a  variable	 name  is  re-
       placed with the value of	that variable:

	  > echo My home directory is $HOME
	  My home directory is /home/tutorial

       This  is	 known as variable substitution, and it	also happens in	double
       quotes, but not single quotes:

	  > echo "My current directory is $PWD"
	  My current directory is /home/tutorial
	  > echo 'My current directory is $PWD'
	  My current directory is $PWD

       Unlike other shells, fish has no	dedicated  VARIABLE=VALUE  syntax  for
       setting variables. Instead it has an ordinary command: set, which takes
       a variable name,	and then its value.

	  > set	name 'Mister Noodle'
	  > echo $name
	  Mister Noodle

       (Notice the quotes: without them, Mister	and  Noodle  would  have  been
       separate	 arguments,  and $name would have been made into a list	of two
       elements.)

       Unlike other shells, variables are not further  split  after  substitu-
       tion:

	  > mkdir $name
	  > ls
	  Mister Noodle

       In bash,	this would have	created	two directories	"Mister" and "Noodle".
       In fish,	it created only	one: the variable had the value	 "Mister  Noo-
       dle", so	that is	the argument that was passed to	mkdir, spaces and all.
       Other shells use	the term "arrays", rather than lists.

       You can erase (or "delete") a variable with -e or --erase

	  > set	-e MyVariable
	  > env	| grep MyVariable
	  (no output)

       For more, see Variable expansion.

   Exports (Shell Variables)
       Sometimes you need to have a variable available to an external command,
       often  as a setting. For	example	many programs like git or man read the
       $PAGER variable to figure out your preferred pager  (the	 program  that
       lets you	scroll text). Other variables used like	this include $BROWSER,
       $LANG (to configure your	language) and $PATH.  You'll  note  these  are
       written in ALLCAPS, but that's just a convention.

       To  give	 a variable to an external command, it needs to	be "exported".
       Unlike other shells, fish does not have an export command.  Instead,  a
       variable	is exported via	an option to set, either --export or just -x.

	  > set	-x MyVariable SomeValue
	  > env	| grep MyVariable
	  MyVariable=SomeValue

       It can also be unexported with --unexport or -u.

       This  works  the	 other way around as well! If fish is started by some-
       thing else, it inherits that parents exported  variables.  So  if  your
       terminal	emulator starts	fish, and it exports $LANG set to en_US.UTF-8,
       fish will receive that setting. And whatever started your terminal emu-
       lator  also  gave it some variables that	it will	then pass on unless it
       specifically decides not	to. This is how	fish usually receives the val-
       ues for things like $LANG, $PATH	and $TERM, without you having to spec-
       ify them	again.

       Exported	variables can be local or global or universal -	"exported"  is
       not  a  scope!  Usually	you'd  make them global	via set	-gx MyVariable
       SomeValue.

       For more, see Exporting variables.

   Lists
       The set command above used quotes to ensure that	Mister Noodle was  one
       argument.  If  it  had  been two	arguments, then	name would have	been a
       list of length 2.  In fact, all variables in  fish  are	really	lists,
       that can	contain	any number of values, or none at all.

       Some  variables,	like $PWD, only	have one value.	By convention, we talk
       about that variable's value, but	we really mean its  first  (and	 only)
       value.

       Other  variables,  like	$PATH,	really do have multiple	values.	During
       variable	expansion, the variable	expands	to become multiple arguments:

	  > echo $PATH
	  /usr/bin /bin	/usr/sbin /sbin	/usr/local/bin

       Variables whose name ends in "PATH" are automatically split  on	colons
       to  become lists. They are joined using colons when exported to subcom-
       mands. This is for compatibility	with other tools, which	 expect	 $PATH
       to  use	colons.	 You  can also explicitly add this quirk to a variable
       with set	--path,	or remove it with set --unpath.

       Lists cannot contain other lists: there is no recursion.	 A variable is
       a list of strings, full stop.

       Get the length of a list	with count:

	  > count $PATH
	  5

       You  can	 append	 (or prepend) to a list	by setting the list to itself,
       with some additional arguments. Here we append /usr/local/bin to	$PATH:

	  > set	PATH $PATH /usr/local/bin

       You can access  individual  elements  with  square  brackets.  Indexing
       starts at 1 from	the beginning, and -1 from the end:

	  > echo $PATH
	  /usr/bin /bin	/usr/sbin /sbin	/usr/local/bin
	  > echo $PATH[1]
	  /usr/bin
	  > echo $PATH[-1]
	  /usr/local/bin

       You can also access ranges of elements, known as	"slices":

	  > echo $PATH[1..2]
	  /usr/bin /bin
	  > echo $PATH[-1..2]
	  /usr/local/bin /sbin /usr/sbin /bin

       You can iterate over a list (or a slice)	with a for loop:

	  > for	val in $PATH
	      echo "entry: $val"
	    end
	  entry: /usr/bin/
	  entry: /bin
	  entry: /usr/sbin
	  entry: /sbin
	  entry: /usr/local/bin

       Lists  adjacent	to  other  lists  or strings are expanded as cartesian
       products	unless quoted (see Variable expansion):

	  > set	a 1 2 3
	  > set	1 a b c
	  > echo $a$1
	  1a 2a	3a 1b 2b 3b 1c 2c 3c
	  > echo $a" banana"
	  1 banana 2 banana 3 banana
	  > echo "$a banana"
	  1 2 3	banana

       This is similar to Brace	expansion.

       For more, see Lists.

   Command Substitutions
       Command substitutions use the output of one command as an  argument  to
       another.	 Unlike	 other shells, fish does not use backticks `` for com-
       mand substitutions. Instead, it uses parentheses:

	  > echo In (pwd), running (uname)
	  In /home/tutorial, running FreeBSD

       A common	idiom is to capture the	output of a command in a variable:

	  > set	os (uname)
	  > echo $os
	  Linux

       Command substitutions are not expanded within quotes. Instead, you  can
       temporarily  close the quotes, add the command substitution, and	reopen
       them, all in the	same argument:

	  > touch "testing_"(date +%s)".txt"
	  > ls *.txt
	  testing_1360099791.txt

       Unlike other shells, fish does not split	command	substitutions  on  any
       whitespace  (like  spaces or tabs), only	newlines. This can be an issue
       with commands like pkg-config that print	what is	meant to  be  multiple
       arguments  on  a	 single	 line.	To  split it on	spaces too, use	string
       split.

	  > printf '%s\n' (pkg-config --libs gio-2.0)
	  -lgio-2.0 -lgobject-2.0 -lglib-2.0
	  > printf '%s\n' (pkg-config --libs gio-2.0 | string split -n " ")
	  -lgio-2.0
	  -lgobject-2.0
	  -lglib-2.0

       If you need a command substitutions output as one argument, without any
       splits, use string collect:

	  > echo "first	line
	  second line" > myfile
	  > set	myfile (cat myfile | string collect)
	  > printf '|%s|' $myfile
	  |first line
	  second line|

       For more, see Command substitution.

   Separating Commands (Semicolon)
       Like  other  shells,  fish  allows multiple commands either on separate
       lines or	the same line.

       To write	them on	the same line, use the semicolon (";").	That means the
       following two examples are equivalent:

	  echo fish; echo chips

	  # or
	  echo fish
	  echo chips

   Exit	Status
       When  a command exits, it returns a status code as a non-negative inte-
       ger.

       Unlike other shells, fish stores	the exit status	of the last command in
       $status instead of $?.

	  > false
	  > echo $status
	  1

       This  indicates	how the	command	fared -	0 usually means	success, while
       the others signify kinds	of failure. For	instance  fish's  set  --query
       returns	the  number  of	 variables  it	queried	that weren't set - set
       --query PATH usually returns 0, set --query arglbargl boogagoogoo  usu-
       ally returns 2.

       There  is also a	$pipestatus list variable for the exit statuses	[1] of
       processes in a pipe.

       For more, see The status	variable.

       [1]  or "stati" if you prefer, or "statA<<s" if	you've	time-travelled
	    from ancient Rome or work as a latin teacher

   Combiners (And, Or, Not)
       fish  supports  the  familiar  &&  and || to combine commands, and ! to
       negate them:

	  > ./configure	&& make	&& sudo	make install

       Here, make is only executed if ./configure succeeds  (returns  0),  and
       sudo  make  install  is only executed if	both ./configure and make suc-
       ceed.

       fish also supports and, or, and not. The	first two  are	job  modifiers
       and have	lower precedence. Example usage:

	  > cp file1 file1_bak && cp file2 file2_bak; and echo "Backup successful"; or echo "Backup failed"
	  Backup failed

       As  mentioned in	the section on the semicolon, this can also be written
       in multiple lines, like so:

	  cp file1 file1_bak &&	cp file2 file2_bak
	  and echo "Backup successful"
	  or echo "Backup failed"

   Conditionals	(If, Else, Switch)
       Use if and else to conditionally	execute	code, based on the exit	status
       of a command.

	  if grep fish /etc/shells
	      echo Found fish
	  else if grep bash /etc/shells
	      echo Found bash
	  else
	      echo Got nothing
	  end

       To  compare strings or numbers or check file properties (whether	a file
       exists or is writeable and such), use test, like

	  if test "$fish" = "flounder"
	      echo FLOUNDER
	  end

	  # or

	  if test "$number" -gt	5
	      echo $number is greater than five
	  else
	      echo $number is five or less
	  end

	  # or

	  # This test is true if the path /etc/hosts exists
	  # - it could be a file or directory or symlink (or possibly something	else).
	  if test -e /etc/hosts
	      echo We most likely have a hosts file
	  else
	      echo We do not have a hosts file
	  end

       Combiners can also be used to make more complex conditions, like

	  if grep fish /etc/shells; and	command	-sq fish
	      echo fish	is installed and configured
	  end

       For even	more complex conditions, use begin and end to group  parts  of
       them.

       There is	also a switch command:

	  switch (uname)
	  case Linux
	      echo Hi Tux!
	  case Darwin
	      echo Hi Hexley!
	  case FreeBSD NetBSD DragonFly
	      echo Hi Beastie!
	  case '*'
	      echo Hi, stranger!
	  end

       As  you	see, case does not fall	through, and can accept	multiple argu-
       ments or	(quoted) wildcards.

       For more, see Conditions.

   Functions
       A fish function is a list of commands, which may	optionally take	 argu-
       ments. Unlike other shells, arguments are not passed in "numbered vari-
       ables" like $1, but instead in a	single list $argv. To create  a	 func-
       tion, use the function builtin:

	  > function say_hello
	       echo Hello $argv
	    end
	  > say_hello
	  Hello
	  > say_hello everybody!
	  Hello	everybody!

       Unlike  other shells, fish does not have	aliases	or special prompt syn-
       tax. Functions take their place.	[2]

       You can list the	names of all  functions	 with  the  functions  builtin
       (note the plural!). fish	starts out with	a number of functions:

	  > functions
	  N_, abbr, alias, bg, cd, cdh,	contains_seq, delete-or-exit, dirh, dirs, disown, down-or-search, edit_command_buffer, export, fg, fish_add_path, fish_breakpoint_prompt, fish_clipboard_copy, fish_clipboard_paste, fish_config, fish_default_key_bindings, fish_default_mode_prompt, fish_git_prompt,	fish_hg_prompt,	fish_hybrid_key_bindings, fish_indent, fish_is_root_user, fish_job_summary, fish_key_reader, fish_md5, fish_mode_prompt, fish_npm_helper, fish_opt, fish_print_git_action, fish_print_hg_root, fish_prompt, fish_sigtrap_handler, fish_svn_prompt, fish_title, fish_update_completions,	fish_vcs_prompt, fish_vi_cursor, fish_vi_key_bindings, funced, funcsave, grep, help, history, hostname,	isatty,	kill, la, ll, ls, man, nextd, nextd-or-forward-word, open, popd, prevd,	prevd-or-backward-word,	prompt_hostname, prompt_pwd, psub, pushd, realpath, seq, setenv, suspend, trap,	type, umask, up-or-search, vared, wait

       You  can	 see  the source for any function by passing its name to func-
       tions:

	  > functions ls
	  function ls --description 'List contents of directory'
	      command ls -G $argv
	  end

       For more, see Functions.

       [2]  There is a function	called alias, but it's just a shortcut to make
	    functions.

   Loops
       While loops:

	  > while true
	      echo "Loop forever"
	  end
	  Loop forever
	  Loop forever
	  Loop forever
	  ... #	yes, this really will loop forever. Unless you abort it	with ctrl-c.

       For  loops  can	be used	to iterate over	a list.	For example, a list of
       files:

	  > for	file in	*.txt
	      cp $file $file.bak
	  end

       Iterating over a	list of	numbers	can be done with seq:

	  > for	x in (seq 5)
	      touch file_$x.txt
	  end

       For more, see Loops and blocks.

   Prompt
       Unlike other shells, there is no	prompt variable	like PS1.  To  display
       your prompt, fish executes the fish_prompt function and uses its	output
       as  the	prompt.	 And  if   it	exists,	  fish	 also	executes   the
       fish_right_prompt function and uses its output as the right prompt.

       You can define your own prompt from the command line:

	  > function fish_prompt; echo "New Prompt % ";	end
	  New Prompt % _

       Then, if	you are	happy with it, you can save it to disk by typing func-
       save  fish_prompt.  This	 saves	the  prompt  in	  ~/.config/fish/func-
       tions/fish_prompt.fish. (Or, if you want, you can create	that file man-
       ually from the start.)

       Multiple	lines are OK. Colors can be  set  via  set_color,  passing  it
       named ANSI colors, or hex RGB values:

	  function fish_prompt
	      set_color	purple
	      date "+%m/%d/%y"
	      set_color	F00
	      echo (pwd) '>' (set_color	normal)
	  end

       This prompt would look like:

	  02/06/13
	  /home/tutorial > _

       You  can	 choose	among some sample prompts by running fish_config for a
       web UI or fish_config prompt for	a simpler version inside  your	termi-
       nal.

   $PATH
       $PATH  is  an environment variable containing the directories that fish
       searches	for commands. Unlike other shells, $PATH  is  a	 list,	not  a
       colon-delimited string.

       Fish takes care to set $PATH to a default, but typically	it is just in-
       herited from fish's parent process and is set to	 a  value  that	 makes
       sense for the system - see Exports.

       To prepend /usr/local/bin and /usr/sbin to $PATH, you can write:

	  > set	PATH /usr/local/bin /usr/sbin $PATH

       To remove /usr/local/bin	from $PATH, you	can write:

	  > set	PATH (string match -v /usr/local/bin $PATH)

       For  compatibility  with	other shells and external commands, $PATH is a
       path variable, and so will be joined with colons	(not spaces) when  you
       quote it:

	  > echo "$PATH"
	  /usr/local/sbin:/usr/local/bin:/usr/bin

       and  it	will be	exported like that, and	when fish starts it splits the
       $PATH it	receives into a	list on	colon.

       You can do so directly in config.fish,  like  you  might	 do  in	 other
       shells with .profile. See this example.

       A faster	way is to use the fish_add_path	function, which	adds given di-
       rectories to the	path if	they aren't already included. It does this  by
       modifying  the  $fish_user_paths	universal variable, which is automati-
       cally prepended to $PATH. For  example,	to  permanently	 add  /usr/lo-
       cal/bin to your $PATH, you could	write:

	  > fish_add_path /usr/local/bin

       The  advantage  is  that	 you don't have	to go mucking around in	files:
       just run	this once at the command line, and it will affect the  current
       session	and  all  future  instances too. You can also add this line to
       config.fish, as it only adds the	component if necessary.

       Or you can modify $fish_user_paths yourself, but	you should be  careful
       not  to	append	to  it unconditionally in config.fish, or it will grow
       longer and longer.

   Startup (Where's .bashrc?)
       Fish starts by executing	commands  in  ~/.config/fish/config.fish.  You
       can create it if	it does	not exist.

       It  is  possible	 to  directly  create  functions and variables in con-
       fig.fish	file, using the	commands shown above. For example:

	  > cat	~/.config/fish/config.fish

	  set -x PATH $PATH /sbin/

	  function ll
	      ls -lh $argv
	  end

       However,	it is more common and efficient	to use	autoloading  functions
       and universal variables.

       If you want to organize your configuration, fish	also reads commands in
       .fish files in ~/.config/fish/conf.d/. See Configuration	Files for  the
       details.

   Autoloading Functions
       When  fish encounters a command,	it attempts to autoload	a function for
       that command, by	looking	for a file with	the name of  that  command  in
       ~/.config/fish/functions/.

       For  example, if	you wanted to have a function ll, you would add	a text
       file ll.fish to ~/.config/fish/functions:

	  > cat	~/.config/fish/functions/ll.fish
	  function ll
	      ls -lh $argv
	  end

       This is the preferred way to define your	prompt as well:

	  > cat	~/.config/fish/functions/fish_prompt.fish
	  function fish_prompt
	      echo (pwd) "> "
	  end

       See the documentation for funced	and funcsave for ways to create	 these
       files automatically, and	$fish_function_path to control their location.

   Universal Variables
       A universal variable is a variable whose	value is shared	across all in-
       stances of fish,	now and	in the future a	even after a reboot.  You  can
       make a variable universal with set -U:

	  > set	-U EDITOR vim

       Now in another shell:

	  > echo $EDITOR
	  vim

   Switching to	fish?
       If you wish to use fish (or any other shell) as your default shell, you
       need to enter your new shell's executable in two	places.

       Add the shell to	/etc/shells with:

	  > echo /usr/local/bin/fish | sudo tee	-a /etc/shells

       Change your default shell with:

	  > chsh -s /usr/local/bin/fish

       This assumes you	installed fish to /usr/local/bin, which	is the default
       location	 when  you've compiled it yourself. If you installed it	with a
       package manager,	the usual location is /usr/bin/fish, but package  man-
       agers typically already add it to /etc/shells. Just substitute the cor-
       rect location.

       (To  change  it	back  to  another  shell,  just	 substitute   /usr/lo-
       cal/bin/fish  with  /bin/bash,  /bin/tcsh or /bin/zsh as	appropriate in
       the steps above.)

   Ready for more?
       If you want to learn more about fish, there is lots of  detailed	 docu-
       mentation,  the	official gitter	channel, an official mailing list, and
       the github page.

   Writing your	own completions
       To specify a completion,	use the	complete command. complete takes as  a
       parameter  the name of the command to specify a completion for. For ex-
       ample, to add a completion for the program myprog, one would start  the
       completion command with complete	-c myprog ...

       To  provide  a  list  of	 possible  completions	for myprog, use	the -a
       switch. If myprog accepts the arguments start and  stop,	 this  can  be
       specified as complete -c	myprog -a 'start stop'.	The argument to	the -a
       switch is always	a single string. At completion time, it	will  be  tok-
       enized on spaces	and tabs, and variable expansion, command substitution
       and other forms of parameter expansion will take	place.

       fish has	a special syntax to support specifying switches	accepted by  a
       command.	 The switches -s, -l and -o are	used to	specify	a short	switch
       (single character, such as -l),	a  gnu	style  long  switch  (such  as
       --color)	and an old-style long switch (like -shuffle), respectively. If
       the command 'myprog' has	an option '-o' which can also  be  written  as
       --output,  and  which  can  take	an additional value of either 'yes' or
       'no', this can be specified by writing:

	  complete -c myprog -s	o -l output -a "yes no"

       There are also special switches for specifying that a  switch  requires
       an argument, to disable filename	completion, to create completions that
       are only	available in some combinations,	etc..  For a complete descrip-
       tion  of	the various switches accepted by the complete command, see the
       documentation for the complete builtin, or write	complete --help	inside
       the fish	shell.

       As a more comprehensive example,	here's a commented excerpt of the com-
       pletions	for systemd's timedatectl:

	  # All	subcommands that timedatectl knows - this is useful for	later.
	  set -l commands status set-time set-timezone list-timezones set-local-rtc set-ntp

	  # Disable file completions for the entire command
	  # because it does not	take files anywhere
	  # Note that this can be undone by using "-F".
	  #
	  # File completions also need to be disabled
	  # if you want	to have	more control over what files are offered
	  # (e.g. just directories, or just files ending in ".mp3").
	  complete -c timedatectl -f

	  # This line offers the subcommands
	  # -"status",
	  # -"set-timezone",
	  # -"set-time"
	  # -"list-timezones"
	  # if no subcommand has been given so far.
	  #
	  # The	`-n`/`--condition` option takes	script as a string, which it executes.
	  # If it returns true,	the completion is offered.
	  # Here the condition is the `__fish_seen_subcommands_from` helper function.
	  # If returns true if any of the given	commands is used on the	commandline,
	  # as determined by a simple heuristic.
	  # For	more complex uses, you can write your own function.
	  # See	e.g. the git completions for an	example.
	  #
	  complete -c timedatectl -n "not __fish_seen_subcommand_from $commands" \
	      -a "status set-time set-timezone list-timezones"

	  # If the "set-timezone" subcommand is	used,
	  # offer the output of	`timedatectl list-timezones` as	completions.
	  # Each line of output	is used	as a separate candidate,
	  # and	anything after a tab is	taken as the description.
	  # It's often useful to transform command output with `string`	into that form.
	  complete -c timedatectl -n "__fish_seen_subcommand_from set-timezone"	\
	      -a "(timedatectl list-timezones)"

	  # Completion candidates can also be described	via `-d`,
	  # which is useful if the description is constant.
	  # Try	to keep	these short, because that means	the user gets to see more at once.
	  complete -c timedatectl -n "not __fish_seen_subcommand_from $commands" \
	      -a "set-local-rtc" -d "Maintain RTC in local time"

	  # We can also	limit options to certain subcommands by	using conditions.
	  complete -c timedatectl -n "__fish_seen_subcommand_from set-local-rtc" \
	      -l adjust-system-clock -d	'Synchronize system clock from the RTC'

	  # These are simple options that can be used everywhere.
	  complete -c timedatectl -s h -l help -d 'Print a short help text and exit'
	  complete -c timedatectl -l version -d	'Print a short version string and exit'
	  complete -c timedatectl -l no-pager -d 'Do not pipe output into a pager'

       For examples of how to write your own complex  completions,  study  the
       completions  in /usr/share/fish/completions. (The exact path depends on
       your chosen installation	prefix and may be slightly different)

   Useful functions for	writing	completions
       fish ships with several functions that are  very	 useful	 when  writing
       command	specific completions. Most of these functions name begins with
       the string __fish_. Such	functions are internal to fish and their  name
       and  interface  may change in future fish versions. Still, some of them
       may be very useful when writing completions. A few of  these  functions
       are described here. Be aware that they may be removed or	changed	in fu-
       ture versions of	fish.

       Functions beginning with	the string __fish_print_ print a newline sepa-
       rated  list  of strings.	For example, __fish_print_filesystems prints a
       list of all known file systems. Functions  beginning  with  __fish_com-
       plete_  print out a newline separated list of completions with descrip-
       tions. The description is separated from	the completion by a tab	 char-
       acter.

       o __fish_complete_directories  STRING DESCRIPTION performs path comple-
	 tion on STRING, allowing only directories, and	giving	them  the  de-
	 scription DESCRIPTION.

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

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

       o __fish_complete_pids prints a list of all processes IDs with the com-
	 mand name as description.

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

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

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

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

       o __fish_print_interfaces  prints  a  list  of all known	network	inter-
	 faces.

       o __fish_print_packages prints a	list of	all installed  packages.  This
	 function currently handles Debian, rpm	and Gentoo packages.

   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_com-
       plete_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:

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

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

       o A directory for third-party software vendors to ship their  own  com-
	 pletions  for	their software,	usually	/usr/share/fish/vendor_comple-
	 tions.d;

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

       o Completions  automatically generated from the operating system's man-
	 ual, usually stored in	~/.local/share/fish/generated_completions.

       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  comple-
       tions  with  your program, install them to the "vendor" completions di-
       rectory.	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.

   Design
       This is a description of	the design principles that have	been  used  to
       design fish. The	fish design has	three high level goals.	These are:

       1. Everything  that can be done in other	shell languages	should be pos-
	  sible	to do in fish, though fish may rely on	external  commands  in
	  doing	so.

       2. Fish	should be user friendly, but not at the	expense	of expressive-
	  ness.	Most tradeoffs between power and ease of use  can  be  avoided
	  with careful design.

       3. Whenever possible without breaking the above goals, fish should fol-
	  low the Posix	syntax.

       To achieve these	high-level goals, the fish design relies on  a	number
       of more specific	design principles. These are presented below, together
       with a rationale	and a few examples for each.

   The law of orthogonality
       The shell language should have a	small set of orthogonal	features.  Any
       situation where two features are	related	but not	identical, one of them
       should be removed, and the other	should be made	powerful  and  general
       enough to handle	all common use cases of	either feature.

       Rationale:  Related  features  make the language	larger,	which makes it
       harder to learn.	It also	increases the size of the source code,	making
       the program harder to maintain and update.

       Examples:

       o Here documents	are too	similar	to using echo inside of	a pipeline.

       o Subshells, command substitution and process substitution are strongly
	 related. fish only supports command substitution, the others  can  be
	 achieved either using a block or the psub shellscript function.

       o Having	both aliases and functions is confusing, especially since both
	 of them have limitations and problems.	fish functions	have  none  of
	 the drawbacks of either syntax.

       o The many Posix	quoting	styles are silly, especially $.

   The law of responsiveness
       The shell should	attempt	to remain responsive to	the user at all	times,
       even in the face	of contended or	unresponsive filesystems. It  is  only
       acceptable  to  block  in  response to a	user initiated action, such as
       running a command.

       Rationale: Bad performance increases user-facing	complexity, because it
       trains  users  to recognize and route around slow use cases. It is also
       incredibly frustrating.

       Examples:

       o Features like syntax highlighting and	autosuggestions	 must  perform
	 all of	their disk I/O asynchronously.

       o Startup  should  minimize  forks  and	disk  I/O, so that fish	can be
	 started even if the system is under load.

   Configurability is the root of all evil
       Every configuration option in a program is a place where	the program is
       too  stupid  to	figure	out for	itself what the	user really wants, and
       should be considered a failure of both the program and  the  programmer
       who implemented it.

       Rationale: Different configuration options are a	nightmare to maintain,
       since the number	of potential bugs  caused  by  specific	 configuration
       combinations  quickly becomes an	issue. Configuration options often im-
       ply assumptions about the code which  change  when  reimplementing  the
       code, causing issues with backwards compatibility. But mostly, configu-
       ration options should be	avoided	since they simply should not exist, as
       the  program  should  be	smart enough to	do what	is best, or at least a
       good enough approximation of it.

       Examples:

       o Fish allows the user to set various syntax highlighting colors.  This
	 is needed because fish	does not know what colors the terminal uses by
	 default, which	might make some	things unreadable. The proper solution
	 would	be  for	 text color preferences	to be defined centrally	by the
	 user for all programs,	and for	the terminal emulator  to  send	 these
	 color properties to fish.

       o Fish does not allow you to set	the number of history entries, differ-
	 ent language substyles	or any number of other common shell configura-
	 tion options.

       A special note on the evils of configurability is the long list of very
       useful features found in	some shells, that are not  turned  on  by  de-
       fault.  Both  zsh and bash support command-specific completions,	but no
       such completions	are shipped with bash by default, and they are	turned
       off  by	default	in zsh.	Other features that zsh	supports that are dis-
       abled by	default	include	tab-completion	of  strings  containing	 wild-
       cards, a	sane completion	pager and a history file.

   The law of user focus
       When  designing	a program, one should first think about	how to make an
       intuitive and powerful program. Implementation issues  should  only  be
       considered once a user interface	has been designed.

       Rationale:  This	design rule is different than the others, since	it de-
       scribes how one should go about designing new features,	not  what  the
       features	 should	be. The	problem	with focusing on what can be done, and
       what is easy to do, is that too much of the implementation is  exposed.
       This  means  that  the user must	know a great deal about	the underlying
       system to be able to guess how the shell	works, it also means that  the
       language	will often be rather low-level.

       Examples:

       o There	should	only  be one type of input to the shell, lists of com-
	 mands.	Loops, conditionals and	variable assignments are all performed
	 through regular commands.

       o The  differences  between built-in commands and shellscript functions
	 should	be made	as small as possible. Built-ins	and shellscript	 func-
	 tions	should	have  exactly  the same	types of argument expansion as
	 other commands, should	be possible to use in any position in a	 pipe-
	 line, and should support any I/O redirection.

       o Instead  of forking when performing command substitution to provide a
	 fake variable scope, all fish commands	are performed  from  the  same
	 process, and fish instead supports true scoping.

       o All blocks end	with the end built-in.

   The law of discoverability
       A  program  should be designed to make its features as easy as possible
       to discover for the user.

       Rationale: A program whose features are discoverable turns a  new  user
       into an expert in a shorter span	of time, since the user	will become an
       expert on the program simply by using it.

       The main	benefit	of a graphical program over a command-line-based  pro-
       gram  is	 discoverability. In a graphical program, one can discover all
       the common features by simply looking at	the user interface and	guess-
       ing  what the different buttons,	menus and other	widgets	do. The	tradi-
       tional way to discover features in  command-line	 programs  is  through
       manual  pages. This requires both that the user starts to use a differ-
       ent program, and	then they remember the new information until the  next
       time they use the same program.

       Examples:

       o Everything should be tab-completable, and every tab completion	should
	 have a	description.

       o Every syntax error and	error in a built-in command should contain  an
	 error	message	 describing  what went wrong and a relevant help page.
	 Whenever possible, errors should be flagged red by the	 syntax	 high-
	 lighter.

       o The  help  manual  should  be easy to read, easily available from the
	 shell,	complete and contain many examples

       o The language should be	uniform, so that once the user understands the
	 command/argument  syntax,  they  will know the	whole language,	and be
	 able to use tab-completion to discover	new features.

   Release notes
   fish	3.3.1 (released	July 6,	2021)
       This release of fish fixes the following	problems  identified  in  fish
       3.3.0:

       o The prompt and	command	line are redrawn correctly in response to uni-
	 versal	variable changes (#8088).

       o A superfluous error that was produced when setting the	PATH or	CDPATH
	 environment  variables	 to include colon-delimited components that do
	 not exist was removed (#8095).

       o The Vi	mode indicator in the  prompt  is  repainted  correctly	 after
	 Ctrl-C	cancels	the current command (#8103).

       o fish builds correctly on platforms that do not	have a spawn.h header,
	 such as old versions of OS X (#8097).

       A number	of improvements	to the documentation, and  fixes  for  comple-
       tions, are included as well.

       If  you	are upgrading from version 3.2.2 or before, please also	review
       the release notes for 3.3.0 (included below).

					----

   fish	3.3.0 (released	June 28, 2021)
   Notable improvements	and fixes
       o fish_config gained a prompt subcommand	to show	and pick from the sam-
	 ple  prompts  directly	 in  the terminal, instead of having to	open a
	 webbrowser. For example fish_config prompt choose default  loads  the
	 default prompt	in the current session (#7958).

       o The  documentation has	been reorganized to be easier to understand (-
	 #7773).

   Deprecations	and removed features
       o The $fish_history value "default" is no longer	special. It used to be
	 treated the same as "fish" (#7650).

       o Redirection  to standard error	with the ^ character has been disabled
	 by default. It	can be turned back on using the	stderr-nocaret feature
	 flag, but will	eventually be disabled completely (#7105).

       o Specifying  an	 initial  tab  to  fish_config	now  only  works  with
	 fish_config browse (e.g. fish_config browse variables), otherwise  it
	 would interfere with the new prompt subcommand	(see below) (#7958).

   Scripting improvements
       o math  gained new functions log2 (like the documentation claimed), max
	 and min (#7856). math functions can be	used without  the  parentheses
	 (eg  math sin 2 + 6), and functions have the lowest precedence	in the
	 order of operations (#7877).

       o Shebang (#!) lines are	no longer required within shell	 scripts,  im-
	 proving  support  for scripts with concatenated binary	contents. If a
	 file fails to execute and passes a (rudimentary) binary safety	check,
	 fish will re-invoke it	using /bin/sh (#7802).

       o Exit  codes  are better aligned with bash. A failed execution now re-
	 ports $status of 127 if the file is not found,	and 126	if it  is  not
	 executable.

       o echo  no  longer writes its output one	byte at	a time,	improving per-
	 formance and allowing use with	Linux's	special	API files (/proc, /sys
	 and such) (#7836).

       o fish  should  now better handle cd on filesystems with	broken stat(3)
	 responses (#7577).

       o Builtins now properly report a	$status	of 1 upon unsuccessful	writes
	 (#7857).

       o string	match with unmatched capture groups and	without	the --all flag
	 now sets an empty variable instead of a variable containing the empty
	 string.  It  also correctly imports the first match if	multiple argu-
	 ments are provided, matching the documentation. (#7938).

       o fish produces more specific errors when a command in a	 command  sub-
	 stitution  wasn't  found or is	not allowed. This now prints something
	 like "Unknown command"	instead	of  "Unknown  error  while  evaluating
	 command substitution".

       o fish_indent  allows  inline variable assignments (FOO=BAR command) to
	 use line continuation,	instead	of joining them	into one line (#7955).

       o fish gained a --no-config option to disable configuration files. This
	 applies to user-specific and the systemwide config.fish (typically in
	 /etc/fish/config.fish),  and  configuration  snippets	(typically  in
	 conf.d	 directories).	It also	disables universal variables, history,
	 and loading of	functions from system or user  configuration  directo-
	 ries (#7921, #1256).

       o When  universal  variables are	unavailable for	some reason, setting a
	 universal variable now	sets a global variable instead (#7921).

       o $last_pid now contains	the process ID of  the	last  process  in  the
	 pipeline,  allowing  it  to be	used in	scripts	(#5036,	#5832, #7721).
	 Previously, this value	contained the process group ID,	but in scripts
	 this was the same as the running fish's process ID.

       o process-exit  event handlers now receive the same value as $status in
	 all cases, instead of receiving -1 when the exit was due to a signal.

       o process-exit event handlers for PID 0 also received JOB_EXIT  events;
	 this has been fixed.

       o job-exit  event handlers may now be created with any of the PIDs from
	 the job. The handler is passed	the last PID in	the job	as its	second
	 argument, instead of the process group.

       o Trying	 to set	an empty variable name with set	no longer works	(these
	 variables could not be	used in	expansions anyway).

       o fish_add_path handles an undefined  PATH  environment	variable  cor-
	 rectly	(#8082).

   Interactive improvements
       o Commands  entered  before  the	 previous command finishes will	now be
	 properly syntax highlighted.

       o fish now automatically	creates	config.fish and	the configuration  di-
	 rectories  in	$XDG_CONFIG_HOME/fish  (by  default ~/.config/fish) if
	 they do not already exist (#7402).

       o $SHLVL	is no longer incremented in non-interactive shells. This means
	 it won't be set to values larger than 1 just because your environment
	 happens to run	some scripts in	$SHELL in its startup path (#7864).

       o fish no longer	rings the bell when flashing  the  command  line.  The
	 flashing  should  already  be enough notification and the bell	can be
	 annoying (#7875).

       o fish --help is	more helpful if	the documentation isn't	 installed  (-
	 #7824).

       o funced	 won't include an entry	on where a function is defined,	thanks
	 to the	new functions --no-details option (#7879).

       o A new variable, fish_killring,	containing entries from	the  killring,
	 is now	available (#7445).

       o fish  --private  prints  a  note  on  private mode on startup even if
	 $fish_greeting	is an empty list (#7974).

       o fish no longer	attempts to lock history or universal  variable	 files
	 on remote filesystems,	including NFS and Samba	mounts.	In rare	cases,
	 updates to these files	may be dropped if separate fish	instances mod-
	 ify them simultaneously. (#7968).

       o wait  and  on-process-exit work correctly with	jobs that have already
	 exited	(#7210).

       o __fish_print_help (used for --help output for	fish's	builtins)  now
	 respects  the	LESS environment variable, and if not set, uses	better
	 default pager settings	(#7997).

       o Errors	from alias are now printed to standard error,  matching	 other
	 builtins and functions	(#7925).

       o ls  output is colorized on OpenBSD if colorls utility is installed (-
	 #8035)

       o The default pager color looks better in terminals  with  light	 back-
	 grounds (#3412).

       o Further robustness improvements to the	bash history import (#7874).

       o fish now tries	to find	a Unicode-aware	locale for encoding (LC_CTYPE)
	 if started without any	locale information, improving the  display  of
	 emoji	and  other non-ASCII text on misconfigured systems (#8031). To
	 allow a C locale, set the variable fish_allow_singlebyte_locale to 1.

       o The Web-based configuration and documentation now feature a dark mode
	 if the	browser	requests it (#8043).

       o Color	variables  can	now also be given like --background red	and -b
	 red, not just --background=red	(#8053).

       o exit run within fish_prompt now exits properly	(#8033).

       o When attempting to execute the	unsupported POSIX-style	brace  command
	 group ({ ... }) fish will suggest its equivalent begin; ...; end com-
	 mands (#6415).

   New or improved bindings
       o Pasting in Vi mode puts text in the right place  in  normal  mode  (-
	 #7847).

       o Vi mode's u is	bound to undo instead of history-search-backward, fol-
	 lowing	GNU readline's behavior. Similarly, Control-R is bound to redo
	 instead of history-search-backward, following Vim (#7908).

       o s in Vi visual	mode now does the same thing as	c (#8039).

       o The binding for "*y now uses fish_clipboard_copy, allowing it to sup-
	 port more than	just xsel.

       o The Control-Space binding can be correctly customised (#7922).

       o exit works correctly in bindings (#7967).

       o The F1	binding, which opens the manual	page for the current  command,
	 now  works  around  a bug in certain less versions that fail to clear
	 the screen (#7863).

       o The binding for Alt-S now toggles whether  sudo  is  prepended,  even
	 when it took the commandline from history instead of only adding it.

       o The  new  functions fish_commandline_prepend and fish_commandline_ap-
	 pend allow toggling the presence of a prefix/suffix  on  the  current
	 commandline. (#7905).

       o backward-kill-path-component Control-W) no longer erases parts	of two
	 tokens	when the cursor	is positioned immediately after	/. (#6258).

   Improved prompts
       o The default Vi	mode prompt now	uses foreground	instead	of  background
	 colors, making	it less	obtrusive (#7880).

       o Performance  of  the "informative" git	prompt is improved somewhat (-
	 #7871). This is still slower than the non-informative version by  its
	 very nature. In particular it is IO-bound, so it will be very slow on
	 slow disks or network mounts.

       o The sample prompts were updated. Some duplicated  prompts,  like  the
	 various classic variants, or less useful ones,	like the "justadollar"
	 prompt	were removed, some prompts were	cleaned	up, and	in some	 cases
	 renamed.  A new "simple" and "disco" prompt were added	(#7884,	#7897,
	 #7930). The new prompts will only take	effect when selected  and  ex-
	 isting	installed prompts will remain unchanged.

       o A  new	 prompt_login  helper function to describe the kind of "login"
	 (user,	host and chroot	status)	for use	in prompts. This replaces  the
	 old "debian chroot" prompt and	has been added to the default and ter-
	 lar prompts (#7932).

       o The Web-based configuration's prompt picker now  shows	 and  installs
	 right prompts (#7930).

       o The  git prompt now has the same symbol order in normal and "informa-
	 tive" mode, and it's customizable via $__fish_git_prompt_status_order
	 (#7926).

   Completions
       o Added completions for:

	 o firewall-cmd	(#7900)

	 o sv (#8069)

       o Improvements to plenty	of completions!

       o Commands  that	 wrap cd (using	complete --wraps cd) get the same com-
	 pletions as cd	(#4693).

       o The --force-files option to complete works for	 bare  arguments,  not
	 just options (#7920).

       o Completion descriptions for functions don't include the function def-
	 inition, making them more concise (#7911).

       o The kill completions no longer	error on MSYS2 (#8046).

       o Completion scripts are	now loaded when	calling	a command via a	 rela-
	 tive path (like ./git)	(#6001,	#7992).

       o When  there  are  multiple  completion	candidates, fish inserts their
	 shared	prefix.	This prefix was	computed in  a	case-insensitive  way,
	 resulting  in	wrong  case in the completion pager. This was fixed by
	 only inserting	prefixes with matching case (#7744).

   Improved terminal support
       o fish no longer	tries to detect	a missing  new	line  during  startup,
	 preventing  an	 erroneous ^a from appearing if the terminal is resized
	 at the	wrong time, which can happen  in  tiling  window  managers  (-
	 #7893).

       o fish  behaves better when it disagrees	with the terminal on the width
	 of characters.	In particular, staircase effects  with	right  prompts
	 should	be gone	in most	cases (#8011).

       o If  the prompt	takes up the entire line, the last character should no
	 longer	be chopped off in certain terminals (#8002).

       o fish's	reflow handling	has been disabled  by  default	for  kitty  (-
	 #7961).

       o The  default  prompt  no longer produces errors when used with	a dumb
	 terminal (#7904).

       o Terminal size variables are updated for  window  size	change	signal
	 handlers (SIGWINCH).

       o Pasting  within  a  multi-line	command	using a	terminal that supports
	 bracketed paste works correctly, instead of  producing	 an  error  (-
	 #7782).

       o set_color  produces an	error when used	with invalid arguments,	rather
	 than empty output which interacts badly with Cartesian	product	expan-
	 sion.

   For distributors
       o fish  runs  correctly	on  platforms  without	the O_CLOEXEC flag for
	 open(2) (#8023).

					----

   fish	3.2.2 (released	April 7, 2021)
       This release of fish fixes a number of additional issues	identified  in
       the fish	3.2 series:

       o The  command-not-found	 handler  used suggestions from	pacman on Arch
	 Linux,	but this caused	major slowdowns	on some	systems	and  has  been
	 disabled (#7841).

       o fish  will  no	longer hang on exit if another process is in the fore-
	 ground	on macOS (#7901).

       o Certain programs (such	as lazygit) could create situations where fish
	 would	not receive keystrokes correctly, but it is now	more robust in
	 these situations (#7853).

       o Arguments longer than 1024 characters no longer trigger excessive CPU
	 usage on macOS	(#7837).

       o fish  builds  correctly  on macOS when	using new versions of Xcode (-
	 #7838).

       o Completions for aura (#7865) and tshark (#7858) should	no longer pro-
	 duce errors.

       o Background  jobs  no longer interfere with syntax highlighting	(a re-
	 gression introduced in	fish 3.2.1, #7842).

       If you are upgrading from version 3.1.2 or before, please  also	review
       the release notes for 3.2.1 and 3.2.0 (included below).

					----

   fish	3.2.1 (released	March 18, 2021)
       This  release  of  fish fixes the following problems identified in fish
       3.2.0:

       o Commands in key bindings are run with fish's internal terminal	modes,
	 instead of the	terminal modes typically used for commands. This fixes
	 a bug introduced in 3.2.0, where text would  unexpectedly  appear  on
	 the terminal, especially when pasting (#7770).

       o Prompts  which	use the	internal __fish_print_pipestatus function will
	 display correctly rather than carrying	 certain  modifiers  (such  as
	 bold) further than intended (#7771).

       o Redirections to internal file descriptors is allowed again, reversing
	 the changes in	3.2.0. This fixes a problem with Midnight Commander (-
	 #7769).

       o Universal  variables should be	fully reliable regardless of operating
	 system	again (#7774).

       o fish_git_prompt no longer causes screen flickering in certain	termi-
	 nals (#7775).

       o fish_add_path manipulates the fish_user_paths variable	correctly when
	 moving	multiple paths (#7776).

       o Pasting with a	multi-line command  no	longer	causes	a  __fish_tok-
	 enizer_state error (#7782).

       o psub  inside  event  handlers	cleans	up temporary files properly (-
	 #7792).

       o Event handlers	declared with --on-job-exit $fish_pid  no  longer  run
	 constantly  (#7721),  although	 these functions should	use --on-event
	 fish_exit instead.

       o Changing terminal modes inside	config.fish works (#7783).

       o set_color --print-colors no longer prints all colors in bold (#7805)

       o Completing commands starting with a - no longer prints	 an  error  (-
	 #7809).

       o Running  fish_command_not_found  directly no longer produces an error
	 on macOS or other OSes	which do not have a handler available (#7777).

       o The new type builtin now has the (deprecated) --quiet long form of -q
	 (#7766).

       It also includes	some small enhancements:

       o help  and fish_config work correctly when fish	is running in a	Chrome
	 OS Crostini Linux VM (#7789).

       o The history file can be made a	symbolic link without it  being	 over-
	 written  (#7754),  matching  a	 similar improvement for the universal
	 variable file in 3.2.0.

       o An unhelpful error ("access: No error"), seen on Cygwin, is no	longer
	 produced (#7785).

       o Improvements  to  the	rsync completions (#7763), some	completion de-
	 scriptions (#7788), and completions that use IP address (#7787).

       o Improvements to the appearance	of fish_config (#7811).

       If you are upgrading from version 3.1.2 or before, please  also	review
       the release notes for 3.2.0 (included below).

					----

   fish	3.2.0 (released	March 1, 2021)
   Notable improvements	and fixes
       o Undo and redo support for the command-line editor and pager search (-
	 #1367). By default, undo is bound to Control+Z, and redo to Alt+/.

       o Builtins can now output before	all data is read. For example,	string
	 replace  no  longer  has  to read all of stdin	before it can begin to
	 output.  This makes it	usable also for	pipes where the	previous  com-
	 mand hasn't finished yet, like:

	    # Show all dmesg lines related to "usb"
	    dmesg -w | string match '*usb*'

       o Prompts  will	now be truncated instead of replaced with "> " if they
	 are wider than	the terminal (#904).  For example:

	    ~/dev/build/fish-shell-git/src/fish-shell/build (makepkg)>

	 will turn into:

	    a|h-shell/build (makepkg)>

	 It is still possible to react to  the	COLUMNS	 variable  inside  the
	 prompt	to implement smarter behavior.

       o fish  completes  ambiguous  completions  after	pressing Tab even when
	 they have a common prefix, without the	user having to press Tab again
	 (#6924).

       o fish  is less aggressive about	resetting terminal modes, such as flow
	 control, after	every command.	Although flow control remains  off  by
	 default,  enterprising	 users	can  now  enable  it with stty (#2315,
	 #7704).

       o A new "fish_add_path" helper function to add paths to	$PATH  without
	 producing  duplicates,	 to be used interactively or in	config.fish (-
	 #6960,	#7028).	 For example:

	    fish_add_path /opt/mycoolthing/bin

	 will add /opt/mycoolthing/bin to  the	beginning  of  $fish_user_path
	 without  creating  duplicates,	 so  it	can be called safely from con-
	 fig.fish or interactively, and	the path will just be there, once.

       o Better	errors with "test" (#6030):

	    > test 1 = 2 and echo true or false
	    test: Expected a combining operator	like '-a' at index 4
	    1 =	2 and echo true	or echo	false
		  ^

	 This includes numbering the index from	1  instead  of	0,  like  fish
	 lists.

       o A new theme for the documentation and Web-based configuration (#6500,
	 #7371,	#7523),	matching the design on fishshell.com.

       o fish --no-execute will	no longer complain about unknown  commands  or
	 non-matching wildcards, as these could	be defined differently at run-
	 time (especially for functions). This makes it	 usable	 as  a	static
	 syntax	checker	(#977).

       o string	 match	--regex	 now  integrates named PCRE2 capture groups as
	 fish variables, allowing variables to be  set	directly  from	string
	 match	(#7459).  To  support  this functionality, string is now a re-
	 served	word and can no	longer be wrapped in a function.

       o Globs and other expansions are	limited	to  512,288  results  (#7226).
	 Because  operating systems limit the number of	arguments to commands,
	 larger	values are unlikely to work anyway, and	this  helps  to	 avoid
	 hangs.

       o A new "fish for bash users" documentation page	gives a	quick overview
	 of the	scripting differences between bash and fish (#2382),  and  the
	 completion  tutorial has also been moved out into its own document (-
	 #6709).

   Syntax changes and new commands
       o Range limits in index range expansions	like $x[$start..$end]  may  be
	 omitted:  $start and $end default to 1	and -1 (the last item) respec-
	 tively	(#6574):

	    echo $var[1..]
	    echo $var[..-1]
	    echo $var[..]

	 All print the full list $var.

       o When globbing,	a segment which	is exactly ** may now match  zero  di-
	 rectories.  For example **/foo	may match foo in the current directory
	 (#7222).

   Scripting improvements
       o The type, _ (gettext),	. (source) and : (no-op) functions are now im-
	 plemented builtins for	performance purposes (#7342, #7036, #6854).

       o set  and  backgrounded	 jobs no longer	overwrite $pipestatus (#6820),
	 improving its use in command substitutions (#6998).

       o Computed ("electric") variables such as status	are now	only global in
	 scope,	so set -Uq status returns false	(#7032).

       o The  output  for  set	--show has been	shortened, only	mentioning the
	 scopes	in which a variable exists (#6944).  In	addition, it now shows
	 if a variable is a path variable.

       o A  new	 variable,  fish_kill_signal, is set to	the signal that	termi-
	 nated the last	foreground job,	or 0 if	the  job  exited  normally  (-
	 #6824,	#6822).

       o A  new	 subcommand,  string  pad, allows extending strings to a given
	 width (#7340, #7102).

       o string	sub has	a new --end option to specify the end index of a  sub-
	 string	(#6765,	#5974).

       o string	 split	has a new --fields option to specify fields to output,
	 similar to cut	-f (#6770).

       o string	trim now also trims vertical tabs by default (#6795).

       o string	replace	no longer prints an error if a capturing group	wasn't
	 matched, instead treating it as empty (#7343).

       o string	subcommands now	quit early when	used with --quiet (#7495).

       o string	 repeat	 now handles multiple arguments, repeating each	one (-
	 #5988).

       o printf	no longer prints an error if not given an argument (not	even a
	 format	string).

       o The  true  and	false builtins ignore any arguments, like other	shells
	 (#7030).

       o fish_indent now removes unnecessary quotes in	simple	cases  (#6722)
	 and  gained a --check option to just check if a file is indented cor-
	 rectly	(#7251).

       o fish_indent indents continuation lines	that follow a line ending in a
	 backslash, |, && or ||.

       o pushd	only  adds a directory to the stack if changing	to it was suc-
	 cessful (#6947).

       o A new fish_job_summary	function is called whenever a  background  job
	 stops	or  ends,  or  any job terminates from a signal	(#6959,	#2727,
	 #4319).  The default behaviour	can now	be  customized	by  redefining
	 it.

       o status	gained new dirname and basename	convenience subcommands	to get
	 just the directory to the running script or the name of it,  to  sim-
	 plify	common	tasks  such  as	running	(dirname (status filename)) (-
	 #7076,	#1818).

       o Broken	pipelines are now handled more smoothly;  in  particular,  bad
	 redirection  mid-pipeline  results  in	 the job continuing to run but
	 with the broken file descriptor replaced with a closed	file  descrip-
	 tor. This allows better error recovery	and is more in line with other
	 shells' behaviour (#7038).

       o jobs --quiet PID no longer prints "no suitable	job" if	 the  job  for
	 PID does not exist (eg	because	it has finished) (#6809, #6812).

       o jobs now shows	continued child	processes correctly (#6818)

       o disown	 should	 no longer create zombie processes when	job control is
	 off, such as in config.fish (#7183).

       o command, jobs and type	builtins support --query as the	long  form  of
	 -q,  matching other builtins.	The long form --quiet is deprecated (-
	 #7276).

       o argparse no longer requires a short flag letter for long-only options
	 (#7585)  and only prints a backtrace with invalid options to argparse
	 itself	(#6703).

       o argparse now passes the validation variables (e.g.  $_flag_value)  as
	 local-exported	 variables, avoiding the need for --no-scope-shadowing
	 in validation functions.

       o complete takes	the first argument as the name of the command  if  the
	 --command/-c option is	not used, so complete git is treated like com-
	 plete --command git, and it can show the loaded completions for  spe-
	 cific commands	with complete COMMANDNAME (#7321).

       o set_color -b (without an argument) no longer prints an	error message,
	 matching other	invalid	invocations of this command (#7154).

       o exec no longer	produces a syntax error	when  the  command  cannot  be
	 found (#6098).

       o set --erase and abbr --erase can now erase multiple things in one go,
	 matching functions --erase (#7377).

       o abbr --erase no longer	prints errors when used	with no	 arguments  or
	 on an unset abbreviation (#7376, #7732).

       o test -t, for testing whether file descriptors are connected to	a ter-
	 minal,	works for file descriptors 0, 1, and 2 (#4766).	 It can	 still
	 return	incorrect results in other cases (#1228).

       o Trying	to execute scripts with	Windows	line endings (CRLF) produces a
	 sensible error	(#2783).

       o Trying	to execute commands with arguments that	exceed	the  operating
	 system	limit now produces a specific error (#6800).

       o An  alias  that  delegates  to	a command with the same	name no	longer
	 triggers an error about recursive completion (#7389).

       o math now has a	--base option to output	the result in  hexadecimal  or
	 octal (#7496) and produces more specific error	messages (#7508).

       o math  learned	bitwise	 functions bitand, bitor and bitxor, used like
	 math "bitand(0xFE, 5)"	(#7281).

       o math learned tau for those who	don't like typing "2 * pi".

       o Failed	redirections will now set $status (#7540).

       o fish sets exit	status in a more consistent manner after  errors,  in-
	 cluding invalid expansions like $foo[.

       o Using	read  --silent	while fish is in private mode was adding these
	 potentially-sensitive entries to the history; this has	been fixed  (-
	 #7230).

       o read  can now read interactively from other files, and	can be used to
	 read from the terminal	via read </dev/tty (if	the  operating	system
	 provides /dev/tty) (#7358).

       o A  new	 fish_status_to_signal function	for transforming exit statuses
	 to signal names has been added	(#7597,	#7595).

       o The fallback realpath builtin supports	the  -s/--no-symlinks  option,
	 like GNU realpath (#7574).

       o functions and type now	explain	when a function	was defined via	source
	 instead of just saying	Defined	in -.

       o Significant performance  improvements	when  globbing,	 appending  to
	 variables or in math.

       o echo no longer	interprets options at the beginning of an argument (eg
	 echo "-n foo")	(#7614).

       o fish now finds	user configuration even	if the HOME environment	 vari-
	 able is not set (#7620).

       o fish  no longer crashes when started from a Windows-style working di-
	 rectory (eg F:\path) (#7636).

       o fish -c now reads the remaining arguments into	$argv (#2314).

       o The pwd command supports the long options --logical  and  --physical,
	 matching other	implementations	(#6787).

       o fish  --profile now only starts profiling after fish is ready to exe-
	 cute commands (all configuration is completed). There is a new	--pro-
	 file-startup  option that only	profiles the startup and configuration
	 process (#7648).

       o Builtins return a maximum exit	status of 255, rather than potentially
	 overflowing.  In  particular,	this  affects  exit, return, functions
	 --query, and set --query (#7698, #7702).

       o It is no longer an error to run builtin with closed stdin. For	 exam-
	 ple count <&- now prints 0, instead of	failing.

       o Blocks,  functions, and builtins no longer permit redirecting to file
	 descriptors other than	0 (standard input), 1 (standard	output)	and  2
	 (standard  error).  For example, echo hello >&5 is now	an error. This
	 prevents corruption of	internal state (#3303).

   Interactive improvements
       o fish will now always attempt to become	process	group leader in	inter-
	 active	mode (#7060). This helps avoid hangs in	certain	circumstances,
	 and allows tmux's current directory introspection to work (#5699).

       o The interactive reader	now allows ending a line in a  logical	opera-
	 tors  (&&  and	 ||)  instead  of complaining about a missing command.
	 (This was  already  syntactically  valid,  but	 interactive  sessions
	 didn't	know about it yet).

       o The prompt is reprinted after a background job	exits (#1018).

       o fish no longer	inserts	a space	after a	completion ending in .,	, or -
	 is accepted, improving	completions for	 tools	that  provide  dynamic
	 completions (#6928).

       o If  a filename	is invalid when	first pressing Tab, but	becomes	valid,
	 it will be completed properly on the next attempt (#6863).

       o help string match/replace/<subcommand>	will show the help for	string
	 subcommands (#6786).

       o fish_key_reader  sets	the  exit status to 0 when used	with --help or
	 --version (#6964).

       o fish_key_reader and fish_indent send output from --version  to	 stan-
	 dard output, matching other fish binaries (#6964).

       o A new variable	$status_generation is incremented only when the	previ-
	 ous command produces an exit status (#6815). This can	be  used,  for
	 example,  to  check  whether  a failure status	is a holdover due to a
	 background job, or actually produced by the last run command.

       o fish_greeting is now a	function that reads a  variable	 of  the  same
	 name,	and defaults to	setting	it globally.  This removes a universal
	 variable by default and helps with updating the  greeting.   However,
	 to  disable  the  greeting  it	is now necessary to explicitly specify
	 universal scope (set -U fish_greeting)	 or  to	 disable  it  in  con-
	 fig.fish (#7265).

       o Events	are properly emitted after a job is cancelled (#2356).

       o fish_preexec  and  fish_postexec  events  are no longer triggered for
	 empty commands	(#4829,	#7085).

       o Functions triggered by	the fish_exit event are	correctly run when the
	 terminal is closed or the shell receives SIGHUP (#7014).

       o The  fish_prompt event	no longer fires	when read is used. If you need
	 a function to run any time read is invoked by a script, use  the  new
	 fish_read event instead (#7039).

       o A  new	 fish_posterror	 event is emitted when attempting to execute a
	 command with syntax errors (#6880, #6816).

       o The debugging system has now fully switched  from  the	 old  numbered
	 level to the new named	category system	introduced in 3.1. A number of
	 new debugging categories have been  added,  including	config,	 path,
	 reader	and screen (#6511). See	the output of fish --print-debug-cate-
	 gories	for the	full list.

       o The warning about read-only filesystems  has  been  moved  to	a  new
	 "warning-path"	 debug category	and can	be disabled by setting a debug
	 category of -warning-path (#6630):

	    fish --debug=-warning-path

       o The enabled debug categories are now  printed	on  shell  startup  (-
	 #7007).

       o The  -o short option to fish, for --debug-output, works correctly in-
	 stead of producing an invalid option error (#7254).

       o fish's	debugging can now also be enabled via FISH_DEBUG and  FISH_DE-
	 BUG_OUTPUT  environment variables.  This helps	with debugging when no
	 commandline options can be passed, like when fish is called in	a she-
	 bang (#7359).

       o Abbreviations are now expanded	after all command terminators (eg ; or
	 |), not just space, as	in fish	2.7.1 and before  (#6970),  and	 after
	 closing a command substitution	(#6658).

       o The history file is now created with user-private permissions,	match-
	 ing other shells (#6926). The directory containing the	 history  file
	 was  already  private,	so there should	not have been any private data
	 revealed.

       o The output of time is now  properly  aligned  in  all	cases  (#6726,
	 #6714)	and no longer depends on locale	(#6757).

       o The  command-not-found	 handling  has been simplified.	 When it can't
	 find a	command, fish now just executes	a  function  called  fish_com-
	 mand_not_found	 instead  of  firing an	event, making it easier	to re-
	 place	 and	reason	  about.     Previously-defined	   __fish_com-
	 mand_not_found_handler	 functions  with an appropriate	event listener
	 will still work (#7293).

       o Control-C handling has	been reimplemented in  C++  and	 is  therefore
	 quicker  (#5259),  no longer occasionally prints an "unknown command"
	 error (#7145) or overwrites multiline prompts (#3537).

       o Control-C no longer kills background jobs for which  job  control  is
	 disabled, matching POSIX semantics (#6828, #6861).

       o Autosuggestions  work	properly  after	 Control-C cancels the current
	 commmand line (#6937).

       o History search	is now case-insensitive	unless the search string  con-
	 tains an uppercase character (#7273).

       o fish_update_completions  gained  a  new --keep	option,	which improves
	 speed by skipping completions that already exist (#6775, #6796).

       o Aliases containing an embedded	backslash appear properly in the  out-
	 put of	alias (#6910).

       o open  no  longer  hangs  indefinitely on certain systems, as a	bug in
	 xdg-open has been worked around (#7215).

       o Long command lines no longer add a blank line after execution (#6826)
	 and behave better with	Backspace (#6951).

       o functions  -t	works  like  the long option --handlers-type, as docu-
	 mented, instead of producing an error (#6985).

       o History search	now flashes when it found no more results (#7362)

       o fish now creates the path in the environment variable XDG_RUNTIME_DIR
	 if  it	 does  not  exist, before using	it for runtime data storage (-
	 #7335).

       o set_color --print-colors now also respects the	bold, dim,  underline,
	 reverse, italic and background	modifiers, to better show their	effect
	 (#7314).

       o The fish Web configuration tool (fish_config) shows prompts correctly
	 on  Termux for	Android	(#7298)	and detects Windows Services for Linux
	 2 properly (#7027). It	no longer shows	the history variable as	it may
	 be  too  large	 (one can use the History tab instead).	It also	starts
	 the browser in	another	thread,	avoiding hangs in some	circumstances,
	 especially  with  Firefox's Developer Edition (#7158).	Finally, a bug
	 in the	Source Code Pro	font may cause browsers	to hang, so this  font
	 is no longer chosen by	default	(#7714).

       o funcsave  gained  a new --directory option to specify the location of
	 the saved function (#7041).

       o help works properly on	MSYS2 (#7113) and only uses cmd.exe if running
	 on WSL	(#6797).

       o Resuming  a  piped  job by its	number,	like fg	%1, works correctly (-
	 #7406). Resumed jobs show the correct title in	the terminal  emulator
	 (#7444).

       o Commands  run	from key bindings now use the same TTY modes as	normal
	 commands (#7483).

       o Autosuggestions from history are now case-sensitive (#3978).

       o $status from completion scripts is no longer passed outside the  com-
	 pletion,  which  keeps	 the  status display in	the prompt as the last
	 command's status (#7555).

       o Updated localisations for pt_BR (#7480).

       o fish_trace output now starts with -> (like  fish  --profile),	making
	 the depth more	visible	(#7538).

       o Resizing the terminal window no longer	produces a corrupted prompt (-
	 #6532,	#7404).

       o functions produces an error rather than crashing on  certain  invalid
	 arguments (#7515).

       o A  crash in completions with inline variable assignment (eg A=	b) has
	 been fixed (#7344).

       o fish_private_mode may now be changed dynamically using	 set  (#7589),
	 and  history is kept in memory	in private mode	(but not stored	perma-
	 nently) (#7590).

       o Commands with leading spaces  may  be	retrieved  from	 history  with
	 up-arrow until	a new command is run, matching zsh's HIST_IGNORE_SPACE
	 (#1383).

       o Importing bash	history	or reporting errors with recursive globs  (**)
	 no longer hangs (#7407, #7497).

       o bind  now shows \x7f for the del key instead of a literal DEL charac-
	 ter (#7631)

       o Paths containing variables or tilde expansion are only	suggested when
	 they are still	valid (#7582).

       o Syntax	 highlighting  can now color a command as invalid even if exe-
	 cuted quickly (#5912).

       o Redirection targets are no longer highlighted as error	if  they  con-
	 tain  variables  which	will likely be defined by the current command-
	 line (#6654).

       o fish is now more resilient  against  broken  terminal	modes  (#7133,
	 #4873).

       o fish  handles	being  in  control  of	the TTY	without	owning its own
	 process group better, avoiding	some hangs in  special	configurations
	 (#7388).

       o Keywords   can	  now	be   colored   differently   by	  setting  the
	 fish_color_keyword variable (fish_color_command is used  as  a	 fall-
	 back) (#7678).

       o Just  like  fish_indent, the interactive reader will indent continua-
	 tion lines that follow	a line ending in a backslash, |, && or	||  (-
	 #7694).

       o Commands with a trailing escaped space	are saved in history correctly
	 (#7661).

       o fish_prompt no	longer mangles Unicode characters in  the  private-use
	 range U+F600-U+F700. (#7723).

       o The  universal	 variable file,	fish_variables,	can be made a symbolic
	 link without it being overwritten (#7466).

       o fish is now more resilient against mktemp failing (#7482).

   New or improved bindings
       o As mentioned above, new special input functions  undo	(Control+_  or
	 Control+Z) and	redo (Alt-/) can be used to revert changes to the com-
	 mand line or the pager	search field (#6570).

       o Control-Z is now available for	binding	(#7152).

       o Additionally, using the cancel	special	input function (bound  to  Es-
	 cape  by  default)  right after fish picked an	unambiguous completion
	 will undo that	(#7433).

       o fish_clipboard_paste (Control+V)  trims  indentation  from  multiline
	 commands, because fish	already	indents	(#7662).

       o Vi  mode bindings now support dh, dl, c0, cf, ct, cF, cT, ch, cl, y0,
	 ci, ca, yi, ya, di, da, d;, d,, o, O and Control+left/right  keys  to
	 navigate by word (#6648, #6755, #6769,	#7442, #7516).

       o Vi mode bindings support ~ (tilde) to toggle the case of the selected
	 character (#6908).

       o Functions up-or-search	and down-or-search (Up	and  Down)  can	 cross
	 empty	lines,	and  don't  activate  search mode if the search	fails,
	 which makes them easier to use	to move	between	lines in  some	situa-
	 tions.

       o If  history  search  fails  to	 find a	match, the cursor is no	longer
	 moved.	This is	useful when accidentally starting a history search  on
	 a multi-line commandline.

       o The  special  input function beginning-of-history (Page Up) now moves
	 to the	oldest search instead of the youngest -	that's	end-of-history
	 (Page Down).

       o A  new	special	input function forward-single-char moves one character
	 to the	right, and if an autosuggestion	is available, only take	a sin-
	 gle character from it (#7217, #4984).

       o Special  input	 functions  can	 now  be  joined with or as a modifier
	 (adding to and), though only some commands  set  an  exit  status  (-
	 #7217).  This	includes suppress-autosuggestion to reflect whether an
	 autosuggestion	was suppressed (#1419)

       o A new function	__fish_preview_current_file, bound to Alt+O, opens the
	 current file at the cursor in a pager (#6838, #6855).

       o edit_command_buffer  (Alt-E  and Alt-V) passes	the cursor position to
	 the external editor if	the editor is recognized (#6138, #6954).

       o __fish_prepend_sudo (Alt-S) now toggles a  sudo  prefix  (#7012)  and
	 avoids	shifting the cursor (#6542).

       o __fish_prepend_sudo  (Alt-S) now uses the previous commandline	if the
	 current one is	empty, to simplify rerunning the previous command with
	 sudo (#7079).

       o __fish_toggle_comment_commandline (Alt-#) now uncomments and presents
	 the last comment from history if the commandline is empty (#7137).

       o __fish_whatis_current_token (Alt-W) prints descriptions for functions
	 and builtins (#7191, #2083).

       o The  definition  of  "word"  and "bigword" for	movements was refined,
	 fixing	(eg) vi	mode's behavior	with e on the second-to-last char, and
	 bigword's   behavior	with   single-character	 words	and  non-blank
	 non-graphical characters (#7353, #7354, #4025,	#7328, #7325)

       o fish's	clipboard bindings now	also  support  Windows	Subsystem  for
	 Linux	via  PowerShell	 and clip.exe (#7455, #7458) and will properly
	 copy newlines in multi-line commands.

       o Using the *-jump special input	functions before typing	anything  else
	 no longer crashes fish.

       o Completing  variable  overrides  (foo=bar)  could  replace the	entire
	 thing with just the completion	in some	circumstances. This  has  been
	 fixed (#7398).

   Improved prompts
       o The  default  and  example  prompts print the correct exit status for
	 commands prefixed with	not (#6566).

       o git prompts include all untracked files in the	repository,  not  just
	 those in the current directory	(#6086).

       o The  git prompts correctly show stash states (#6876, #7136) and clean
	 states	(#7471).

       o The Mercurial prompt correctly	shows untracked	status (#6906),	and by
	 default  only	shows the branch for performance reasons.  A new vari-
	 able $fish_prompt_hg_show_informative_status can  be  set  to	enable
	 more information.

       o The  fish_vcs_prompt  passes its arguments to the various VCS prompts
	 that it calls (#7033).

       o The Subversion	prompt was broken in a number of ways in 3.1.0 and has
	 been restored (#6715, #7278).

       o A new helper function fish_is_root_user simplifies checking for supe-
	 ruser privilege (#7031, #7123).

       o New colorschemes - ayu	Light, ayu Dark	and ayu	Mirage (#7596).

       o Bugs related to multiline prompts, including  repainting  (#5860)  or
	 navigating  directory	history	 (#3550) leading to graphical glitches
	 have been fixed.

       o The nim prompt	now handles vi mode better (#6802)

   Improved terminal support
       o A  new	 variable,  fish_vi_force_cursor,  can	 be   set   to	 force
	 fish_vi_cursor	 to  attempt changing the cursor shape in vi mode, re-
	 gardless of terminal (#6968). The fish_vi_cursor option --force-iterm
	 has been deprecated.

       o diff will now colourize output, if supported (#7308).

       o Autosuggestions  appear  when	the  cursor passes the right prompt (-
	 #6948)	or wraps to the	next line (#7213).

       o The cursor shape in Vi	mode changes properly in Windows  Terminal  (-
	 #6999,	#6478).

       o The  spurious warning about terminal size in small terminals has been
	 removed (#6980).

       o Dynamic titles	are now	enabled	in Alacritty (#7073) and emacs'	 vterm
	 (#7122).

       o Current  working  directory  updates  are enabled in foot (#7099) and
	 WezTerm (#7649).

       o The width computation for certain emoji agrees	better with  terminals
	 (especially flags). (#7237).

       o Long command lines are	wrapped	in all cases, instead of sometimes be-
	 ing put on a new line (#5118).

       o The pager is properly rendered	with long command  lines  selected  (-
	 #2557).

       o Sessions  with	 right	prompts	 can be	resized	correctly in terminals
	 that handle reflow, like GNOME	Terminal (and other  VTE-based	termi-
	 nals),	upcoming Konsole releases and Alacritty. This detection	can be
	 overridden with the new fish_handle_reflow variable (#7491).

       o fish now sets terminal	modes sooner, which stops output from  appear-
	 ing before the	greeting and prompt are	ready (#7489).

       o Better	 detection  of new Konsole versions for	true color support and
	 cursor	shape changing.

       o fish no longer	attempts to modify the terminal	size  via  TIOCSWINSZ,
	 improving compatibility with Kitty (#6994).

   Completions
       o Added completions for

	 o 7z, 7za and 7zr (#7220)

	 o alias (#7035)

	 o alternatives	(#7616)

	 o apk (#7108)

	 o asciidoctor (#7000)

	 o avifdec and avifenc (#7674)

	 o bluetoothctl	(#7438)

	 o cjxl	and djxl (#7673)

	 o cmark (#7000)

	 o create_ap (#7096)

	 o deno	(#7138)

	 o dhclient (#6684)

	 o Postgres-related commands dropdb, createdb, pg_restore, pg_dump and
	   pg_dumpall (#6620)

	 o dotnet (#7558)

	 o downgrade (#6751)

	 o gapplication, gdbus,	gio and	gresource (#7300)

	 o gh (#7112)

	 o gitk

	 o groups (#6889)

	 o hashcat (#7746)

	 o hikari (#7083)

	 o icdiff (#7503)

	 o imv (#6675)

	 o john	(#7746)

	 o julia (#7468)

	 o k3d (#7202)

	 o ldapsearch (#7578)

	 o lightdm and dm-tool (#7624)

	 o losetup (#7621)

	 o micro (#7339)

	 o mpc (#7169)

	 o Metasploit's	msfconsole, msfdb and msfvenom (#6930)

	 o mtr (#7638)

	 o mysql (#6819)

	 o ncat, nc.openbsd, nc.traditional and	nmap (#6873)

	 o openssl (#6845)

	 o prime-run (#7241)

	 o ps2pdf{12,13,14,wr} (#6673)

	 o pyenv (#6551)

	 o rst2html,  rst2html4,  rst2html5,  rst2latex,   rst2man,   rst2odt,
	   rst2pseudoxml, rst2s5, rst2xetex, rst2xml and rstpep2html (#7019)

	 o spago (#7381)

	 o sphinx-apidoc,  sphinx-autogen,  sphinx-build and sphinx-quickstart
	   (#7000)

	 o strace (#6656)

	 o systemd's bootctl, coredumpctl,  hostnamectl	 (#7428),  homectl  (-
	   #7435), networkctl (#7668) and userdbctl (#7667)

	 o tcpdump (#6690)

	 o tig

	 o traceroute and tracepath (#6803)

	 o windscribe (#6788)

	 o wireshark, tshark, and dumpcap

	 o xbps-* (#7239)

	 o xxhsum, xxh32sum, xxh64sum and xxh128sum (#7103)

	 o yadm	(#7100)

	 o zopfli and zopflipng	(#6872)

       o Lots of improvements to completions, including:

	 o git	completions  can complete the right and	left parts of a	commit
	   range like from..to or left...right.

	 o Completion scripts for custom Git subcommands like git-xyz are  now
	   loaded with Git completions.	The completions	can now	be defined di-
	   rectly on the subcommand (using complete git-xyz),  and  completion
	   for git xyz will work. (#7075, #7652, #4358)

	 o make	completions no longer second-guess make's file detection, fix-
	   ing target completion in some cases (#7535).

	 o Command completions now correctly print the description even	if the
	   command was fully matched (like in ls<TAB>).

	 o set completions no longer hide variables starting with __, they are
	   sorted last instead.

       o Improvements to the manual page completion generator  (#7086,	#6879,
	 #7187).

       o Significant  performance  improvements	to completion of the available
	 commands (#7153), especially on macOS Big Sur where there was a  sig-
	 nificant regression (#7365, #7511).

       o Suffix	 completion  using  __fish_complete_suffix uses	the same fuzzy
	 matching logic	as normal file completion, and completes any file  but
	 sorts files with matching suffix first	(#7040,	#7547).	Previously, it
	 only completed	files with matching suffix.

   For distributors
       o fish has a new	interactive test driver	based on pexpect, removing the
	 optional  dependency  on expect (and adding an	optional dependency on
	 pexpect) (#5451, #6825).

       o The CHANGELOG was moved to restructured text, allowing	it to  be  in-
	 cluded	in the documentation (#7057).

       o fish  handles	ncurses	 installed  in a non-standard prefix better (-
	 #6600,	#7219),	and uses variadic tparm	on NetBSD curses (#6626).

       o The Web-based configuration tool no longer uses an  obsolete  Angular
	 version (#7147).

       o The fish project has adopted the Contributor Covenant code of conduct
	 (#7151).

   Deprecations	and removed features
       o The fish_color_match variable is no  longer  used.  (Previously  this
	 controlled the	color of matching quotes and parens when using read).

       o fish 3.2.0 will be the	last release in	which the redirection to stan-
	 dard error with the ^ character is enabled.  The stderr-nocaret  fea-
	 ture flag will	be changed to "on" in future releases.

       o string	 is  now a reserved word and cannot be used for	function names
	 (see above).

       o fish_vi_cursor's  option  --force-iterm  has  been  deprecated	  (see
	 above).

       o command,  jobs	and type long-form option --quiet is deprecated	in fa-
	 vor of	--query	(see above).

       o The fish_command_not_found event is no	longer emitted,	instead	 there
	 is a function of that name.  By default it will call a	previously-de-
	 fined __fish_command_not_found_handler. To emit  the  event  manually
	 use emit fish_command_not_found.

       o The  fish_prompt event	no longer fires	when read is used. If you need
	 a function to run any time read is invoked by a script, use  the  new
	 fish_read event instead (#7039).

       o To disable the	greeting message permanently it	is no longer enough to
	 just run set fish_greeting interactively as it	is no  longer  implic-
	 itly  a universal variable. Use set -U	fish_greeting or disable it in
	 config.fish with set -g fish_greeting.

       o The long-deprecated and non-functional	-m/--read-mode options to read
	 were  removed	in 3.1b1. Using	the short form,	or a never-implemented
	 -B option, no longer crashes fish (#7659).

       o With the addition of new categories for debug options,	the  old  num-
	 bered debugging levels	have been removed.

   For distributors and	developers
       o fish  source  tarballs	 are  now distributed using the	XZ compression
	 method	(#5460).

       o The fish source tarball contains an  example  FreeDesktop  entry  and
	 icon.

       o The CMake variable MAC_CODESIGN_ID can	now be set to "off" to disable
	 code-signing (#6952, #6792).

       o Building on on	macOS earlier than 10.13.6 succeeds, instead of	 fail-
	 ing on	code-signing (#6791).

       o The  pkg-config file now uses variables to ensure paths used are por-
	 table across prefixes.

       o The default values for	the  extra_completionsdir,  extra_functionsdir
	 and extra_confdir options now use the installation prefix rather than
	 /usr/local (#6778).

       o A new CMake  variable	FISH_USE_SYSTEM_PCRE2  controls	 whether  fish
	 builds	with the system-installed PCRE2, or the	version	it bundles. By
	 default it prefers the	system library if available, unless Mac	 code-
	 signing is enabled (#6952).

       o Running  the full interactive test suite now requires Python 3.5+ and
	 the pexpect package (#6825); the expect  package  is  no  longer  re-
	 quired.

       o Support for Python 2 in fish's	tools (fish_config and the manual page
	 completion generator) is no longer guaranteed.	Please use Python  3.5
	 or later (#6537).

       o The  Web-based	 configuration tool is compatible with Python 3.10  (-
	 #7600)	and no longer requires Python's	distutils package (#7514).

       o fish 3.2 is the last release to support Red Hat  Enterprise  Linux  &
	 CentOS	version	6.

					----

   fish	3.1.2 (released	April 29, 2020)
       This release of fish fixes a major issue	discovered in fish 3.1.1:

       o Commands  such	 as  fzf and enhancd, when used	with eval, would hang.
	 eval buffered output too aggressively,	which has been fixed (#6955).

       If you are upgrading from version 3.0.0 or before, please  also	review
       the release notes for 3.1.1, 3.1.0 and 3.1b1 (included below).

					----

   fish	3.1.1 (released	April 27, 2020)
       This  release of	fish fixes a number of major issues discovered in fish
       3.1.0.

       o Commands which	involve	. ( ...	| psub)	now work correctly, as	a  bug
	 in the	function --on-job-exit option has been fixed (#6613).

       o Conflicts between upstream packages for ripgrep and bat, and the fish
	 packages, have	been resolved (#5822).

       o Starting fish in a directory without read access, such	as via su,  no
	 longer	crashes	(#6597).

       o Glob  ordering	 changes  which	were introduced	in 3.1.0 have been re-
	 verted, returning the order of	globs to the previous state (#6593).

       o Redirections using the	deprecated caret syntax	to a  file  descriptor
	 (eg ^&2) work correctly (#6591).

       o Redirections  that  append  to	a file descriptor (eg 2>>&1) work cor-
	 rectly	(#6614).

       o Building fish on macOS	(#6602)	or with	new versions  of  GCC  (#6604,
	 #6609)	is now successful.

       o time  is  now	correctly listed in the	output of builtin -n, and time
	 --help	works correctly	(#6598).

       o Exported universal variables now update properly (#6612).

       o status	current-command	gives the expected output when	used  with  an
	 environment  override	-  that	is, F=B	status current-command returns
	 status	instead	of F=B (#6635).

       o test no longer	crashes	when used with anana or	ainfa  arguments,  er-
	 roring	out instead (#6655).

       o Copying  from	the  end of the	command	line no	longer crashes fish (-
	 #6680).

       o read no longer	removes	multiple separators when splitting a  variable
	 into  a  list,	restoring the previous behaviour from fish 3.0 and be-
	 fore (#6650).

       o Functions using --on-job-exit	and  --on-process-exit	work  reliably
	 again (#6679).

       o Functions  using  --on-signal	INT  work reliably in interactive ses-
	 sions,	as they	did in fish 2.7	and  before  (#6649).  These  handlers
	 have  never  worked in	non-interactive	sessions, and making them work
	 is an ongoing process.

       o Functions using --on-variable work reliably with variables which  are
	 set  implicitly  (rather than with set), such as afish_bind_modea and
	 aPWDa (#6653).

       o 256 colors are	properly enabled under certain	conditions  that  were
	 incorrectly detected in fish 3.1.0 ($TERM begins with xterm, does not
	 include a256colora, and $TERM_PROGRAM is not set) (#6701).

       o The Mercurial (hg) prompt no longer produces an error when  the  cur-
	 rent working directory	is removed (#6699). Also, for performance rea-
	 sons it shows only basic information by default; to restore  the  de-
	 tailed	status,	set $fish_prompt_hg_show_informative_status.

       o The  VCS prompt, fish_vcs_prompt, no longer displays Subversion (svn)
	 status	by default, due	to the potential slowness of this operation (-
	 #6681).

       o Pasting of commands has been sped up (#6713).

       o Using	extended  Unicode  characters, such as emoji, in a non-Unicode
	 capable locale	(such as the C or POSIX	locale)	no longer renders  all
	 output	blank (#6736).

       o help prefers to use xdg-open, avoiding	the use	of open	on Debian sys-
	 tems where this command is actually openvt (#6739).

       o Command lines starting	with a space, which are	not saved in  history,
	 now  do  not  get  autosuggestions. This fixes	an issue with Midnight
	 Commander integration (#6763),	but may	be changed in  a  future  ver-
	 sion.

       o Copying  to  the  clipboard no	longer inserts a newline at the	end of
	 the content, matching fish 2.7	and earlier (#6927).

       o fzf in	complex	pipes no longer	hangs. More  generally,	 code  run  as
	 part  of  command  substitutions or eval will no longer have separate
	 process groups. (#6624, #6806).

       This release also includes:

       o several changes to improve macOS compatibility	with code signing  and
	 notarization;

       o several improvements to completions; and

       o several content and formatting	improvements to	the documentation.

       If  you	are upgrading from version 3.0.0 or before, please also	review
       the release notes for 3.1.0 and 3.1b1 (included below).

   Errata for fish 3.1
       A new builtin, time, was	introduced in  the  fish  3.1  releases.  This
       builtin is a reserved word (like	test, function,	and others) because of
       the way it is implemented, and functions	can no longer be  named	 time.
       This was	not clear in the fish 3.1b1 changelog.

					----

   fish	3.1.0 (released	February 12, 2020)
       Compared	to the beta release of fish 3.1b1, fish	version	3.1.0:

       o Fixes	a  regression  where spaces after a brace were removed despite
	 brace expansion not occurring (#6564).

       o Fixes a number	of problems in compiling and testing on	Cygwin (#6549)
	 and  Solaris-derived  systems	such  as Illumos (#6553, #6554,	#6555,
	 #6556,	and #6558).

       o Fixes the process for building	macOS packages.

       o Fixes a regression where excessive error messages are printed if Uni-
	 code characters are emitted in	non-Unicode-capable locales (#6584).

       o Contains some improvements to the documentation and a small number of
	 completions.

       If you are upgrading from version 3.0.0 or before, please  also	review
       the release notes for 3.1b1 (included below).

					----

   fish	3.1b1 (released	January	26, 2020)
   Notable improvements	and fixes
       o A  new	 $pipestatus  variable contains	a list of exit statuses	of the
	 previous job, for each	of the separate	 commands  in  a  pipeline  (-
	 #5632).

       o fish  no longer buffers pipes to the last function in a pipeline, im-
	 proving many cases where pipes	appeared to block or hang (#1396).

       o An overhaul of	error messages for builtin commands, including	a  re-
	 moval	of  the	overwhelming usage summary, more readable stack	traces
	 (#3404, #5434), and stack traces for test (aka	[) (#5771).

       o fishas	debugging arguments  have  been	 significantly	improved.  The
	 --debug-level	option	has been removed, and a	new --debug option re-
	 places	it. This option	 accepts  various  categories,	which  may  be
	 listed	 via fish --print-debug-categories (#5879). A new --debug-out-
	 put option allows for redirection of debug output.

       o string	has a new collect subcommand for use in	command	substitutions,
	 producing  a single output instead of splitting on new	lines (similar
	 to "$(cmd)" in	other shells) (#159).

       o The fish manual, tutorial and FAQ are now available in	man format  as
	 fish-doc, fish-tutorial and fish-faq respectively (#5521).

       o Like  other  shells, cd now always looks for its argument in the cur-
	 rent directory	as a last resort, even if the CDPATH variable does not
	 include it or a.a (#4484).

       o fish now correctly handles CDPATH entries that	start with ..  (#6220)
	 or contain ./ (#5887).

       o The fish_trace	variable may be	set to trace execution (#3427).	  This
	 performs a similar role as set	-x in other shells.

       o fish  uses  the  temporary directory determined by the	system,	rather
	 than relying on /tmp (#3845).

       o The fish Web configuration tool (fish_config) prints a	list  of  com-
	 mands it is executing,	to help	understanding and debugging (#5584).

       o Major	performance  improvements when pasting (#5866),	executing lots
	 of commands (#5905), importing	history	from bash  (#6295),  and  when
	 completing variables that might match $history	(#6288).

   Syntax changes and new commands
       o A  new	 builtin  command, time, which allows timing of	fish functions
	 and builtins as well as external commands (#117).

       o Brace expansion now only takes	place if the braces include a a,a or a
	 variable  expansion,  meaning	common	commands  such	as  git	 reset
	 HEAD@{0} do not require escaping (#5869).

       o New redirections &> and &| may	be used	to redirect  or	 pipe  stdout,
	 and also redirect stderr to stdout (#6192).

       o switch	 now allows arguments that expand to nothing, like empty vari-
	 ables (#5677).

       o The VAR=val cmd syntax	can now	be used	to run a command in a modified
	 environment (#6287).

       o and  is  no  longer recognised	as a command, so that nonsensical con-
	 structs like and and and produce a syntax error (#6089).

       o mathas	exponent operator,a^a, was  previously	left-associative,  but
	 now  uses the more commonly-used right-associative behaviour (#6280).
	 This means that math '3^0.5^2'	was previously calculated asa(30.5)2a,
	 but is	now calculated as a3(0.52)a.

       o In  fish 3.0, the variable used with for loops	inside command substi-
	 tutions could leak into enclosing scopes; this	was an inadvertent be-
	 haviour change	and has	been reverted (#6480).

   Scripting improvements
       o string	split0 now returns 0 if	it split something (#5701).

       o In  the interest of consistency, builtin -q and command -q can	now be
	 used to query if a builtin or command exists (#5631).

       o math now accepts --scale=max for the maximum scale (#5579).

       o builtin $var now works	correctly, allowing a variable as the  builtin
	 name (#5639).

       o cd  understands  the -- argument to make it possible to change	to di-
	 rectories starting with a hyphen (#6071).

       o complete --do-complete	now also does fuzzy matches (#5467).

       o complete --do-complete	can be used inside completions,	allowing  lim-
	 ited recursion	(#3474).

       o count now also	counts lines fed on standard input (#5744).

       o eval produces an exit status of 0 when	given no arguments, like other
	 shells	(#5692).

       o printf	prints what it can when	input hasnat been fully	converted to a
	 number, but still prints an error (#5532).

       o complete -C foo now works as expected,	rather than requiring complete
	 -Cfoo.

       o complete has a	new --force-files option, to  re-enable	 file  comple-
	 tions.	 This  allows  sudo -E and pacman -Qo to complete correctly (-
	 #5646).

       o argparse now defaults to showing the current function	name  (instead
	 of argparse) in its errors, making --name often superfluous (#5835).

       o argparse  has	a new --ignore-unknown option to keep unrecognized op-
	 tions,	allowing multiple argparse passes to parse options (#5367).

       o argparse correctly handles flag value validation of options that only
	 have short names (#5864).

       o read -S (short	option of --shell) is recognised correctly (#5660).

       o read understands --list, which	acts like --array in reading all argu-
	 ments into a list inside a single variable, but is  better  named  (-
	 #5846).

       o read  has  a new option, --tokenize, which splits a string into vari-
	 ables according to the	shellas	tokenization rules, considering	 quot-
	 ing, escaping,	and so on (#3823).

       o read  interacts  more correctly with the deprecated $IFS variable, in
	 particular removing multiple separators  when	splitting  a  variable
	 into a	list (#6406), matching other shells.

       o fish_indent  now handles semicolons better, including leaving them in
	 place for ; and and ; or instead of breaking the line (#5859).

       o fish_indent --write now supports multiple file	 arguments,  indenting
	 them in turn.

       o The default read limit	has been increased to 100MiB (#5267).

       o math  now  also understands x for multiplication, provided it is fol-
	 lowed by whitespace (#5906).

       o math reports the right	error when incorrect  syntax  is  used	inside
	 parentheses  (#6063),	and  warns when	unsupported logical operations
	 are used (#6096).

       o functions --erase now also prevents fish from autoloading a  function
	 for the first time (#5951).

       o jobs  --last  returns	0  to  indicate	success	when a job is found (-
	 #6104).

       o commandline -p	and commandline	-j now split on	&& and || in  addition
	 to ; and & (#6214).

       o A  bug	 where string split would drop empty strings if	the output was
	 only empty strings has	been fixed (#5987).

       o eval no long creates a	new local variable scope,  but	affects	 vari-
	 ables	in the scope it	is called from (#4443).	source still creates a
	 new local scope.

       o abbr has a new	--query	option to check	for the	existence of an	abbre-
	 viation.

       o Local	values	for  fish_complete_path	and fish_function_path are now
	 ignored; only their global values are respected.

       o Syntax	error reports now display a marker in the correct position  (-
	 #5812).

       o Empty universal variables may now be exported (#5992).

       o Exported  universal  variables	are no longer imported into the	global
	 scope,	preventing shadowing. This makes  it  easier  to  change  such
	 variables for all fish	sessions and avoids breakage when the value is
	 a list	of multiple elements (#5258).

       o A bug where for could use invalid variable names has  been  fixed  (-
	 #5800).

       o A  bug	 where	local variables	would not be exported to functions has
	 been fixed (#6153).

       o The null command (:) now always exits successfully, rather than pass-
	 ing through the previous exit status (#6022).

       o The output of functions FUNCTION matches the declaration of the func-
	 tion, correctly including comments or blank lines (#5285),  and  cor-
	 rectly	includes any --wraps flags (#1625).

       o type  supports	 a new option, --short,	which suppress function	expan-
	 sion (#6403).

       o type --path with a function argument will now output the path to  the
	 file containing the definition	of that	function, if it	exists.

       o type --force-path with	an argument that cannot	be found now correctly
	 outputs nothing, as documented	(#6411).

       o The $hostname variable	is no longer truncated	to  32	characters  (-
	 #5758).

       o Line numbers in function backtraces are calculated correctly (#6350).

       o A  new	 fish_cancel  event  is	 emitted when the command line is can-
	 celled, which is useful for terminal integration (#5973).

   Interactive improvements
       o New Base16 color options are available	through	the Web-based configu-
	 ration	(#6504).

       o fish  only  parses  /etc/paths	on macOS in login shells, matching the
	 bash implementation (#5637) and avoiding changes to path ordering  in
	 child shells (#5456). It now ignores blank lines like the bash	imple-
	 mentation (#5809).

       o The locale is now reloaded when the LOCPATH variable  is  changed  (-
	 #5815).

       o read  no  longer  keeps  a history, making it suitable	for operations
	 that shouldnat	end up there, like password entry (#5904).

       o dirh outputs its stack	in the correct order (#5477), and  behaves  as
	 documented when universal variables are used for its stack (#5797).

       o funced	 and  the  edit-commandline-in-buffer bindings did not work in
	 fish 3.0 when the $EDITOR variable contained spaces;  this  has  been
	 corrected (#5625).

       o Builtins now pipe their help output to	a pager	automatically (#6227).

       o set_color now colors the --print-colors output	in the matching	colors
	 if it is going	to a terminal.

       o fish now underlines every valid entered path instead of just the last
	 one (#5872).

       o When  syntax  highlighting  a string with an unclosed quote, only the
	 quote itself will be shown as an error, instead of  the  whole	 argu-
	 ment.

       o Syntax	 highlighting  works  correctly	 with variables	as commands (-
	 #5658)	and redirections to close file descriptors (#6092).

       o help works properly on	Windows	Subsytem for Linux (#5759, #6338).

       o A bug where disown could crash	the shell has been fixed (#5720).

       o fish will not autosuggest files ending	with ~	unless	there  are  no
	 other candidates, as these are	generally backup files (#985).

       o Escape	in the pager works correctly (#5818).

       o Key  bindings	that  call fg no longer	leave the terminal in a	broken
	 state (#2114).

       o Brackets (#5831) and filenames	containing  $  (#6060)	are  completed
	 with appropriate escaping.

       o The  output of	complete and functions is now colorized	in interactive
	 terminals.

       o The Web-based	configuration  handles	aliases	 that  include	single
	 quotes	correctly (#6120), and launches	correctly under	Termux (#6248)
	 and OpenBSD (#6522).

       o function now correctly	validates parameters for  --argument-names  as
	 valid	variable  names	(#6147)	and correctly parses options following
	 --argument-names, as in a--argument-names foo --description  bara  (-
	 #6186).

       o History  newly	 imported from bash includes command lines using && or
	 ||.

       o The automatic generation of completions from manual pages  is	better
	 described in job and process listings,	and no longer produces a warn-
	 ing when exiting fish (#6269).

       o In private mode, setting $fish_greeting to  an	 empty	string	before
	 starting  the	private	session	will prevent the warning about history
	 not being saved from being printed (#6299).

       o In the	interactive editor,  a	line  break  (Enter)  inside  unclosed
	 brackets  will	 insert	 a new line, rather than executing the command
	 and producing an error	(#6316).

       o Ctrl-C	always repaints	the prompt (#6394).

       o When run interactively	from another program (such  as	Python),  fish
	 will correctly	start a	new process group, like	other shells (#5909).

       o Job  identifiers (for example,	for background jobs) are assigned more
	 logically (#6053).

       o A bug where history would appear truncated if an  empty  command  was
	 executed was fixed (#6032).

   New or improved bindings
       o Pasting  strips leading spaces	to avoid pasted	commands being omitted
	 from the history (#4327).

       o Shift-Left and	Shift-Right now	default	to moving backwards  and  for-
	 wards by one bigword (words separated by whitespace) (#1505).

       o The default escape delay (to differentiate between the	escape key and
	 an alt-combination) has been reduced to 30ms, down from 300ms for the
	 default mode and 100ms	for Vi mode (#3904).

       o The  forward-bigword binding now interacts correctly with autosugges-
	 tions (#5336).

       o The fish_clipboard_* functions	support	Wayland	by using  wl-clipboard
	 (#5450).

       o The  nextd  and prevd functions no longer print aHit end of historya,
	 instead using a bell. They correctly store working  directories  con-
	 taining symbolic links	(#6395).

       o If  a	fish_mode_prompt function exists, Vi mode will only execute it
	 on mode-switch	instead	of the entire prompt. This should make it much
	 more responsive with slow prompts (#5783).

       o The  path-component  bindings	(like Ctrl-w) now also stop at a:a and
	 a@a, because those are	used to	denote user and	host in	commands  such
	 as ssh	(#5841).

       o The  NULL character can now be	bound via bind -k nul. Terminals often
	 generate this character via control-space. (#3189).

       o A new readline	command	expand-abbr can	be used	to  trigger  abbrevia-
	 tion expansion	(#5762).

       o A  new	 readline  command, delete-or-exit, removes a character	to the
	 right of the cursor or	exits the shell	if the command line  is	 empty
	 (moving this functionality out	of the delete-or-exit function).

       o The  self-insert  readline  command  will  now	insert the binding se-
	 quence, if not	empty.

       o A new binding to prepend sudo,	bound to Alt-S by default (#6140).

       o The Alt-W binding to describe a command should	now work  better  with
	 multiline prompts (#6110)

       o The  Alt-H  binding  to open a	commandas man page now tries to	ignore
	 sudo (#6122).

       o A new pair of	bind  functions,  history-prefix-search-backward  (and
	 forward), was introduced (#6143).

       o Vi  mode  now	supports  R  to	 enter replace mode (#6342), and d0 to
	 delete	the current line (#6292).

       o In Vi mode, hitting Enter in replace-one mode no  longer  erases  the
	 prompt	(#6298).

       o Selections in Vi mode are inclusive, matching the actual behaviour of
	 Vi (#5770).

   Improved prompts
       o The Git prompt	in informative mode now	shows the number of stashes if
	 enabled.

       o The  Git  prompt  now	has an option ($__fish_git_prompt_use_informa-
	 tive_chars) to	use the	(more modern) informative  characters  without
	 enabling informative mode.

       o The  default  prompt now also features	VCS integration	and will color
	 the host if running via SSH (#6375).

       o The default and example prompts print the pipe	status if  an  earlier
	 command in the	pipe fails.

       o The  default and example prompts try to resolve exit statuses to sig-
	 nal names when	appropriate.

   Improved terminal output
       o New fish_pager_color_ options have been added to  control  more  ele-
	 ments of the pageras colors (#5524).

       o Better	 detection and support for using fish from various system con-
	 soles,	where limited colors and special characters are	 supported  (-
	 #5552).

       o fish  now  tries  to guess if the system supports Unicode 9 (and dis-
	 plays emoji as	wide), eliminating the need to	set  $fish_emoji_width
	 in most cases (#5722).

       o Improvements  to  the display of wide characters, particularly	Korean
	 characters and	emoji (#5583, #5729).

       o The Vi	mode cursor is correctly redrawn when  regaining  focus	 under
	 terminals that	report focus (eg tmux) (#4788).

       o Variables     that	control	   background	 colors	   (such    as
	 fish_pager_color_search_match)	can now	use --reverse.

   Completions
       o Added completions for

	 o aws

	 o bat (#6052)

	 o bosh	(#5700)

	 o btrfs

	 o camcontrol

	 o cf (#5700)

	 o chronyc (#6496)

	 o code	(#6205)

	 o cryptsetup (#6488)

	 o csc and csi (#6016)

	 o cwebp (#6034)

	 o cygpath and cygstart	(#6239)

	 o epkginfo (#5829)

	 o ffmpeg, ffplay, and ffprobe (#5922)

	 o fsharpc and fsharpi (#6016)

	 o fzf (#6178)

	 o g++ (#6217)

	 o gpg1	(#6139)

	 o gpg2	(#6062)

	 o grub-mkrescue (#6182)

	 o hledger (#6043)

	 o hwinfo (#6496)

	 o irb (#6260)

	 o iw (#6232)

	 o kak

	 o keepassxc-cli (#6505)

	 o keybase (#6410)

	 o loginctl (#6501)

	 o lz4,	lz4c and lz4cat	(#6364)

	 o mariner (#5718)

	 o nethack (#6240)

	 o patool (#6083)

	 o phpunit (#6197)

	 o plutil (#6301)

	 o pzstd (#6364)

	 o qubes-gpg-client (#6067)

	 o resolvectl (#6501)

	 o rg

	 o rustup

	 o sfdx	(#6149)

	 o speedtest and speedtest-cli (#5840)

	 o src (#6026)

	 o tokei (#6085)

	 o tsc (#6016)

	 o unlz4 (#6364)

	 o unzstd (#6364)

	 o vbc (#6016)

	 o zpaq	(#6245)

	 o zstd, zstdcat, zstdgrep, zstdless and zstdmt	(#6364)

       o Lots of improvements to completions.

       o Selecting short options which also have a long	name from the  comple-
	 tion pager is possible	(#5634).

       o Tab completion	will no	longer add trailing spaces if they already ex-
	 ist (#6107).

       o Completion of subcommands to builtins like and	or not now works  cor-
	 rectly	(#6249).

       o Completion  of	arguments to short options works correctly when	multi-
	 ple short options are used together (#332).

       o Activating completion in the middle of	an invalid completion does not
	 move the cursor any more, making it easier to fix a mistake (#4124).

       o Completion in empty commandlines now lists all	available commands.

       o Functions  listed  as	completions could previously leak parts	of the
	 function as other completions;	this has been fixed.

   Deprecations	and removed features
       o The vcs-prompt	functions have been promoted  to  names	 without  dou-
	 ble-underscore,   so	__fish_git_prompt   is	 now  fish_git_prompt,
	 __fish_vcs_prompt is now  fish_vcs_prompt,  __fish_hg_prompt  is  now
	 fish_hg_prompt	and __fish_svn_prompt is now fish_svn_prompt. Shims at
	 the old names have been added,	and the	variables have kept their  old
	 names (#5586).

       o string	replace	has an additional round	of escaping in the replacement
	 expression, so	escaping backslashes requires many escapes (eg	string
	 replace   -ra	 '([ab])'   '\\\\\\\$1'	  a).  The  new	 feature  flag
	 regex-easyesc can be used to disable this, so that  the  same	effect
	 can  be achieved with string replace -ra '([ab])' '\\\\$1' a (#5556).
	 As a reminder,	the intention behind feature flags is that  this  will
	 eventually become the default and then	only option, so	scripts	should
	 be updated.

       o The fish_vi_mode function, deprecated in fish 2.3, has	been  removed.
	 Use fish_vi_key_bindings instead (#6372).

   For distributors and	developers
       o fish 3.0 introduced a CMake-based build system. In fish 3.1, both the
	 Autotools-based build and legacy Xcode	build  system  have  been  re-
	 moved,	 leaving only the CMake	build system. All distributors and de-
	 velopers must install CMake.

       o fish now depends on the common	tee external  command,	for  the  psub
	 process substitution function.

       o The  documentation  is	 now  built with Sphinx. The old Doxygen-based
	 documentation system has been removed.	Developers,  and  distributors
	 who wish to rebuild the documentation,	must install Sphinx.

       o The  INTERNAL_WCWIDTH	build option has been removed, as fish now al-
	 ways uses an internal wcwidth function. It has	a number of configura-
	 tion options that make	it more	suitable for general use (#5777).

       o mandoc	 can  now be used to format the	output from --help if nroff is
	 not installed,	reducing the number of external	dependencies  on  sys-
	 tems with mandoc installed (#5489).

       o Some  bugs preventing building	on Solaris-derived systems such	as Il-
	 lumos were fixed (#5458, #5461, #5611).

       o Completions for npm, bower and	yarn no	longer require the jq  utility
	 for  full  functionality, but will use	Python instead if it is	avail-
	 able.

       o The paths for completions, functions and configuration	snippets  have
	 been  extended. On systems that define	XDG_DATA_DIRS, each of the di-
	 rectories  in	this  variable	are  searched  in  the	subdirectories
	 fish/vendor_completions.d,   fish/vendor_functions.d,	and  fish/ven-
	 dor_conf.d respectively. On systems that do not define	this  variable
	 in  the  environment, the vendor directories are searched for in both
	 the installation prefix and the default aextraa directory, which  now
	 defaults to /usr/local	(#5029).

					----

   fish	3.0.2 (released	February 19, 2019)
       This release of fish fixes an issue discovered in fish 3.0.1.

   Fixes and improvements
       o The PWD environment variable is now ignored if	it does	not resolve to
	 the true working directory, fixing  strange  behaviour	 in  terminals
	 started by editors and	IDEs (#5647).

       If  you	are upgrading from version 2.7.1 or before, please also	review
       the release notes for 3.0.1, 3.0.0 and 3.0b1 (included below).

   fish	3.0.1 (released	February 11, 2019)
       This release of fish fixes a number of major issues discovered in  fish
       3.0.0.

   Fixes and improvements
       o exec  does  not complain about	running	foreground jobs	when called (-
	 #5449).

       o while loops now evaluate to the last executed	command	 in  the  loop
	 body  (or  zero  if  the body was empty), matching POSIX semantics (-
	 #4982).

       o read --silent no longer echoes	to the tty when	run from a  non-inter-
	 active	script (#5519).

       o On macOS, path	entries	with spaces in /etc/paths and /etc/paths.d now
	 correctly set path entries with spaces.  Likewise,  MANPATH  is  cor-
	 rectly	set from /etc/manpaths and /etc/manpaths.d (#5481).

       o fish starts correctly under Cygwin/MSYS2 (#5426).

       o The pager-toggle-search binding (Ctrl-S by default) will now activate
	 the search field, even	when the pager is not focused.

       o The error when	a command is not found is now printed a	 single	 time,
	 instead of once per argument (#5588).

       o Fixes	and  improvements  to  the git completions, including printing
	 correct paths with older git versions,	fuzzy matching again, reducing
	 unnecessary  offers  of  root paths (starting with :/)	(#5578,	#5574,
	 #5476), and ignoring shell aliases, so	enterprising users can set  up
	 the   wrapping	  command   (via   set	 -g  __fish_git_alias_$command
	 $whatitwraps) (#5412).

       o Significant performance improvements to core shell functions  (#5447)
	 and to	the kill completions (#5541).

       o Starting  in  symbolically-linked working directories works correctly
	 (#5525).

       o The default fish_title	function no longer contains  extra  spaces  (-
	 #5517).

       o The  nim prompt now works correctly when chosen in the	Web-based con-
	 figuration (#5490).

       o string	now prints help	to stdout, like	other builtins (#5495).

       o Killing the terminal while fish is in vi normal mode will  no	longer
	 send it spinning and eating CPU. (#5528)

       o A number of crashes have been fixed (#5550, #5548, #5479, #5453).

       o Improvements to the documentation and certain completions.

   Known issues
       There  is one significant known issue that was not corrected before the
       release:

       o fish does not run correctly under Windows Services for	 Linux	before
	 Windows  10  version  1809/17763, and the message warning of this may
	 not be	displayed (#5619).

       If you are upgrading from version 2.7.1 or before, please  also	review
       the release notes for 3.0.0 and 3.0b1 (included below).

					----

   fish	3.0.0 (released	December 28, 2018)
       fish  3	is  a  major  release,	which introduces some breaking changes
       alongside improved functionality. Although most existing	 scripts  will
       continue	to work, they should be	reviewed against the list contained in
       the 3.0b1 release notes below.

       Compared	to the beta release of fish 3.0b1, fish	version	3.0.0:

       o builds	correctly against musl libc (#5407)

       o handles huge numeric arguments	to test	correctly (#5414)

       o removes the history colouring introduced in 3.0b1, which did not  al-
	 ways work correctly

       There is	one significant	known issue which was not able to be corrected
       before the release:

       o fish 3.0.0 builds on Cygwin (#5423), but does not  run	 correctly  (-
	 #5426)	 and  will  result  in a hanging terminal when started.	Cygwin
	 users are encouraged to continue using	2.7.1 until  a	release	 which
	 corrects this is available.

       If  you	are upgrading from version 2.7.1 or before, please also	review
       the release notes for 3.0b1 (included below).

					----

   fish	3.0b1 (released	December 11, 2018)
       fish 3 is a major  release,  which  introduces  some  breaking  changes
       alongside  improved  functionality. Although most existing scripts will
       continue	to work, they should be	reviewed against the list below.

   Notable non-backward	compatible changes
       o Process and job expansion has largely been removed. % will no	longer
	 perform these expansions, except for %self for	the PID	of the current
	 shell.	Additionally, job management commands (disown,	wait,  bg,  fg
	 and kill) will	expand job specifiers starting with % (#4230, #1202).

       o set  x[1]  x[2] a b, to set multiple elements of an array at once, is
	 no longer valid syntax	(#4236).

       o A literal {} now expands to itself, rather than nothing.  This	 makes
	 working with find -exec easier	(#1109,	#4632).

       o Literally  accessing a	zero-index is now illegal syntax and is	caught
	 by the	parser (#4862).	(fish indices start at 1)

       o Successive commas in brace expansions are handled in less  surprising
	 manner.  For example, {,,,} expands to	four empty strings rather than
	 an empty string, a comma and an empty string again (#3002, #4632).

       o for loop control variables are	no longer local	to the	for  block  (-
	 #1935).

       o Variables  set	 in  if	and while conditions are available outside the
	 block (#4820).

       o Local exported	(set -lx) vars are now visible to functions (#1091).

       o The new math builtin (see below) does	not  support  logical  expres-
	 sions;	test should be used instead (#4777).

       o Range expansion will now behave sensibly when given a single positive
	 and negative index ($foo[5..-1] or $foo[-1..5]), clamping to the last
	 valid index without changing direction	if the list has	fewer elements
	 than expected.

       o read now uses -s as short for --silent	(A  la bash); --shellas	abbre-
	 viation (formerly -s) is now -S instead (#4490).

       o cd  no	 longer	 resolves symlinks. fish now maintains a virtual path,
	 matching other	shells (#3350).

       o source	now requires an	explicit - as the filename to  read  from  the
	 terminal (#2633).

       o Arguments to end are now errors, instead of being silently ignored.

       o The  names  argparse,	read, set, status, test	and [ are now reserved
	 and not allowed as function names. This prevents  users  unintention-
	 ally breaking stuff (#3000).

       o The fish_user_abbreviations variable is no longer used; abbreviations
	 will be migrated to the new storage format automatically.

       o The FISH_READ_BYTE_LIMIT variable is now  called  fish_byte_limit  (-
	 #4414).

       o Environment  variables	 are  no longer	split into arrays based	on the
	 record	separator character on startup.	 Instead,  variables  are  not
	 split,	 unless	 their name ends in PATH, in which case	they are split
	 on colons (#436).

       o The history builtinas --with-time option has been removed;  this  has
	 been deprecated in favor of --show-time since 2.7.0 (#4403).

       o The  internal	variables __fish_datadir and __fish_sysconfdir are now
	 known as __fish_data_dir and __fish_sysconf_dir respectively.

   Deprecations
       With the	release	of fish	3, a number of features	have been  marked  for
       removal	in  the	 future.  All users are	encouraged to explore alterna-
       tives.  A small number of these features	are currently  behind  feature
       flags,  which are turned	on at present but may be turned	off by default
       in the future.

       A new feature flags mechanism is	added  for  staging  deprecations  and
       breaking	 changes.  Feature  flags may be specified at launch with fish
       --features ... or by setting the	universal fish_features	 variable.  (-
       #4940)

       o The  use  of the IFS variable for read	is deprecated; IFS will	be ig-
	 nored in the future (#4156). Use the read --delimiter option instead.

       o The function --on-process-exit	switch will be removed	in  future  (-
	 #4700).   Use	 the  fish_exit	 event	instead:  function  --on-event
	 fish_exit.

       o $_ is deprecated and will removed in the future  (#813).  Use	status
	 current-command in a command substitution instead.

       o ^  as a redirection deprecated	and will be removed in the future.  (-
	 #4394). Use  2>  to  redirect	stderr.	 This  is  controlled  by  the
	 stderr-nocaret	feature	flag.

       o ?  as	a glob (wildcard) is deprecated	and will be removed in the fu-
	 ture (#4520). This is controlled by the qmark-noglob feature flag.

   Notable fixes and improvements
   Syntax changes and new commands
       o fish now supports && (like and), || (like or),	and ! (like not),  for
	 better	migration from POSIX-compliant shells (#4620).

       o Variables may be used as commands (#154).

       o fish  may be started in private mode via fish --private. Private mode
	 fish sessions do not have access to the history file and any commands
	 evaluated  in	private	 mode are not persisted	for future sessions. A
	 session variable $fish_private_mode can be queried to detect  private
	 mode  and  adjust  the	behavior of scripts accordingly	to respect the
	 useras	wish for privacy.

       o A new wait command for	waiting	on backgrounded	processes (#4498).

       o math is now a builtin rather than a wrapper around bc (#3157).	Float-
	 ing  point computations is now	used by	default, and can be controlled
	 with the new --scale option (#4478).

       o Setting $PATH no longer warns on non-existent	directories,  allowing
	 for  a	single $PATH to	be shared across machines (eg via dotfiles) (-
	 #2969).

       o while sets $status to a non-zero value	if the loop is not executed (-
	 #4982).

       o Command  substitution output is now limited to	10 MB by default, con-
	 trolled by the	fish_read_limit	variable  (#3822).  Notably,  this  is
	 larger	than most operating systemsa argument size limit, so trying to
	 pass argument lists this size to external commands has	never worked.

       o The machine hostname, where available,	is now exposed as  the	$host-
	 name  reserved	 variable. This	removes	the dependency on the hostname
	 executable (#4422).

       o Bare	bind   invocations    in    config.fish	   now	  work.	   The
	 fish_user_key_bindings	 function  is  no  longer  necessary, but will
	 still be executed if it exists	(#5191).

       o $fish_pid and $last_pid are available as replacements for  %self  and
	 %last.

   New features	in commands
       o alias	has a new --save option	to save	the generated function immedi-
	 ately (#4878).

       o bind has a new	--silent option	to ignore bind requests	for named keys
	 not available under the current terminal (#4188, #4431).

       o complete has a	new --keep-order option	to show	the provided or	dynam-
	 ically-generated argument list	in the same order as specified,	rather
	 than alphabetically (#361).

       o exec prompts for confirmation if background jobs are running.

       o funced	has a new --save option	to automatically save the edited func-
	 tion after successfully editing (#4668).

       o functions has a new --handlers	option to show functions registered as
	 event handlers	(#4694).

       o history  search supports globs	for wildcard searching (#3136) and has
	 a new --reverse option	to show	entries	from oldest to newest (#4375).

       o jobs has a new	--quiet	option to silence the output.

       o read has a new	--delimiter option for splitting input into arrays  (-
	 #4256).

       o read writes directly to stdout	if called without arguments (#4407).

       o read  can  now	 read individual lines into separate variables without
	 consuming the input in	its entirety via the new /--line option.

       o set has new --append and --prepend options (#1326).

       o string	match with an empty pattern and	 --entire  in  glob  mode  now
	 matches everything instead of nothing (#4971).

       o string	 split	supports  a  new  --no-empty  option  to exclude empty
	 strings from the result (#4779).

       o string	has new	subcommands split0 and join0 for working with  NUL-de-
	 limited output.

       o string	no longer stops	processing text	after NUL characters (#4605)

       o string	 escape	has a new --style regex	option for escaping strings to
	 be matched literally in string	regex operations.

       o test now supports floating point values in numeric comparisons.

   Interactive improvements
       o A pipe	at the end of a	line now allows	the job	 to  continue  on  the
	 next line (#1285).

       o Italics  and dim support out of the box on macOS for Terminal.app and
	 iTerm (#4436).

       o cd tab	completions no longer descend  into  the  deepest  unambiguous
	 path (#4649).

       o Pager	navigation  has	 been  improved. Most notably, moving down now
	 wraps around, moving up from the commandline now jumps	 to  the  last
	 element  and  moving  right and left now reverse each other even when
	 wrapping around (#4680).

       o Typing	normal characters while	the  completion	 pager	is  active  no
	 longer	 shows	the search field. Instead it enters them into the com-
	 mand line, and	ends paging (#2249).

       o A new input binding pager-toggle-search toggles the search  field  in
	 the  completions  pager  on  and  off.	 By  default, this is bound to
	 Ctrl-S.

       o Searching in the pager	now does a full	fuzzy search (#5213).

       o The pager will	now show the full command instead  of  just  its  last
	 line if the number of completions is large (#4702).

       o Abbreviations can be tab-completed (#3233).

       o Tildes	in file	names are now properly escaped in completions (#2274).

       o Wrapping  completions (from complete --wraps or function --wraps) can
	 now inject arguments. For example, complete gco --wraps  'git	check-
	 out' now works	properly (#1976).  The alias function has been updated
	 to respect this behavior.

       o Path completions now support  expansions,  meaning  expressions  like
	 python	~/<TAB>	now provides file suggestions just like	any other rel-
	 ative or absolute path. (This includes	support	for other  expansions,
	 too.)

       o Autosuggestions  try  to  avoid arguments that	are already present in
	 the command line.

       o Notifications about crashed processes are now always shown,  even  in
	 command substitutions (#4962).

       o The  screen is	no longer reset	after a	BEL, fixing graphical glitches
	 (#3693).

       o vi-mode now supports a;a and a,a motions. This	introduces  new	 {for-
	 ward,backward}-jump-till and repeat-jump{,-reverse} bind functions (-
	 #5140).

       o The *y	vi-mode	binding	now works (#5100).

       o True color is now enabled in neovim by	default	(#2792).

       o Terminal size variables  ($COLUMNS/$LINES)  are  now  updated	before
	 fish_prompt is	called,	allowing the prompt to react (#904).

       o Multi-line  prompts  no longer	repeat when the	terminal is resized (-
	 #2320).

       o xclip support has been	added to the clipboard integration (#5020).

       o The Alt-P keybinding paginates	the last command if the	 command  line
	 is empty.

       o $cmd_duration is no longer reset when no command is executed (#5011).

       o Deleting  a one-character word	no longer erases the next word as well
	 (#4747).

       o Token history search (Alt-Up) omits duplicate entries (#4795).

       o The fish_escape_delay_ms timeout, allowing the	use of the escape  key
	 both on its own and as	part of	a control sequence, was	applied	to all
	 control characters; this has been reduced to just the escape key.

       o Completing a function shows the description properly (#5206).

       o Added completions for

	 o ansible,  including	ansible-galaxy,	 ansible-playbook  and	 ansi-
	   ble-vault (#4697)

	 o bb-power (#4800)

	 o bd (#4472)

	 o bower

	 o clang and clang++ (#4174)

	 o conda (#4837)

	 o configure (for autoconf-generated files only)

	 o curl

	 o doas	(#5196)

	 o ebuild (#4911)

	 o emaint (#4758)

	 o eopkg (#4600)

	 o exercism (#4495)

	 o hjson

	 o hugo	(#4529)

	 o j (from autojump #4344)

	 o jbake (#4814)

	 o jhipster (#4472)

	 o kitty

	 o kldload

	 o kldunload

	 o makensis (#5242)

	 o meson

	 o mkdocs (#4906)

	 o ngrok (#4642)

	 o OpenBSDas pkg_add, pkg_delete, pkg_info, pfctl, rcctl, signify, and
	   vmctl (#4584)

	 o openocd

	 o optipng

	 o opkg	(#5168)

	 o pandoc (#2937)

	 o port	(#4737)

	 o powerpill (#4800)

	 o pstack (#5135)

	 o serve (#5026)

	 o ttx

	 o unzip

	 o virsh (#5113)

	 o xclip (#5126)

	 o xsv

	 o zfs and zpool (#4608)

       o Lots of improvements to completions (especially darcs	(#5112),  git,
	 hg and	sudo).

       o Completions  for  yarn	 and npm now require the all-the-package-names
	 NPM package for full functionality.

       o Completions for bower and yarn	now require the	jq  utility  for  full
	 functionality.

       o Improved French translations.

   Other fixes and improvements
       o Significant  performance  improvements	to abbr	(#4048), setting vari-
	 ables (#4200, #4341),	executing  functions,  globs  (#4579),	string
	 reading from standard input (#4610), and slicing history (in particu-
	 lar, $history[1] for the last executed	command).

       o Fishas	internal wcwidth function has been updated to deal with	 newer
	 Unicode,  and	the width of some characters can be configured via the
	 fish_ambiguous_width (#5149) and fish_emoji_width (#2652)  variables.
	 Alternatively,	 a  new	build-time option INTERNAL_WCWIDTH can be used
	 to use	the systemas wcwidth instead (#4816).

       o functions correctly supports -d as the	short form  of	--description.
	 (#5105)

       o /etc/paths  is	 now parsed like macOSa	bash path_helper, fixing $PATH
	 order (#4336, #4852) on macOS.

       o Using a read-only variable in a for loop produces  an	error,	rather
	 than silently producing incorrect results (#4342).

       o The  universal	 variables filename no longer contains the hostname or
	 MAC address. It is now	at the fixed location  .config/fish/fish_vari-
	 ables (#1912).

       o Exported  variables  in  the global or	universal scope	no longer have
	 their exported	status affected	by local variables (#2611).

       o Major rework of terminal and job handling to eliminate	 bugs  (#3805,
	 #3952,	#4178, #4235, #4238, #4540, #4929, #5210).

       o Improvements to the manual page completion generator (#2937, #4313).

       o suspend --force now works correctly (#4672).

       o Pressing  Ctrl-C  while running a script now reliably terminates fish
	 (#5253).

   For distributors and	developers
       o fish ships with a new build system based on CMake. CMake 3.2  is  the
	 minimum  required  version. Although the autotools-based Makefile and
	 the Xcode project are still shipped with this release,	they  will  be
	 removed  in  the near future. All distributors	and developers are en-
	 couraged to migrate to	the CMake build.

       o Build scripts for most	platforms no longer require  bash,  using  the
	 standard sh instead.

       o The hostname command is no longer required for	fish to	operate.

       a

   fish	2.7.1 (released	December 23, 2017)
       This  release  of fish fixes an issue where iTerm 2 on macOS would dis-
       play a warning about paste bracketing being left	on when	starting a new
       fish session (#4521).

       If  you	are upgrading from version 2.6.0 or before, please also	review
       the release notes for 2.7.0 and 2.7b1 (included below).

       a

   fish	2.7.0 (released	November 23, 2017)
       There are no major changes between 2.7b1	and 2.7.0. If you are  upgrad-
       ing  from version 2.6.0 or before, please also review the release notes
       for 2.7b1 (included below).

       Xcode builds and	macOS packages could not be produced with  2.7b1,  but
       this is fixed in	2.7.0.

       a

   fish	2.7b1 (released	October	31, 2017)
   Notable improvements
       o A  new	cdh (change directory using recent history) command provides a
	 more friendly alternative to prevd/nextd and pushd/popd (#2847).

       o A new argparse	command	is available to	allow fish script to parse ar-
	 guments  with	the  same  behavior as builtin commands. This also in-
	 cludes	the fish_opt helper command. (#4190).

       o Invalid array indexes are now silently	ignored	(#826, #4127).

       o Improvements to the debugging facility, including a  prompt  specific
	 to  the  debugger (fish_breakpoint_prompt) and	a status is-breakpoint
	 subcommand (#1310).

       o string	supports new lower and upper  subcommands,  for	 altering  the
	 case  of strings (#4080). The case changing is	not locale-aware yet.-
	 string	escape has a new --style=xxx flag where	 xxx  can  be  script,
	 var,  or  url	(#4150),  and  can be reversed with string unescape (-
	 #3543).

       o History can now be split into sessions	with  the  fish_history	 vari-
	 able, or not saved to disk at all (#102).

       o Read  history	is  now	controlled by the fish_history variable	rather
	 than the --mode-name flag (#1504).

       o command now supports an --all flag to report all directories with the
	 command. which	is no longer a runtime dependency (#2778).

       o fish  can  run	 commands before starting an interactive session using
	 the new --init-command/-C options (#4164).

       o set has a new --show option to	show lots of information  about	 vari-
	 ables (#4265).

   Other significant changes
       o The COLUMNS and LINES environment variables are now correctly set the
	 first time fish_prompt	is run (#4141).

       o completeas --no-files option works as intended	(#112).

       o echo -h now correctly echoes -h in line with other shells (#4120).

       o The export compatibility function now returns zero on success,	rather
	 than always returning 1 (#4435).

       o Stop  converting empty	elements in MANPATH to a.a (#4158). The	behav-
	 ior being changed was introduced in fish 2.6.0.

       o count -h and count --help now return 1	rather	than  produce  command
	 help output (#4189).

       o An  attempt  to  read	which stops because too	much data is available
	 still defines the variables given as parameters (#4180).

       o A regression in fish 2.4.0 which prevented pushd +1 from working  has
	 been fixed (#4091).

       o A regression in fish 2.6.0 where multiple read	commands in non-inter-
	 active	scripts	were broken has	been fixed (#4206).

       o A  regression	in  fish  2.6.0	 involving  universal  variables  with
	 side-effects  at  startup  such as set	-U fish_escape_delay_ms	10 has
	 been fixed (#4196).

       o Added completions for:

	 o as (#4130)

	 o cdh (#2847)

	 o dhcpd (#4115)

	 o ezjail-admin	(#4324)

	 o Fabricas fab	(#4153)

	 o grub-file (#4119)

	 o grub-install	(#4119)

	 o jest	(#4142)

	 o kdeconnect-cli

	 o magneto (#4043, #4108)

	 o mdadm (#4198)

	 o passwd (#4209)

	 o pip and pipenv (#4448)

	 o s3cmd (#4332)

	 o sbt (#4347)

	 o snap	(#4215)

	 o Sublime Text	3as subl (#4277)

       o Lots of improvements to completions.

       o Updated Chinese and French translations.

       o Improved completions for:

	 o apt

	 o cd (#4061)

	 o composer (#4295)

	 o eopkg

	 o flatpak (#4456)

	 o git (#4117, #4147, #4329, #4368)

	 o gphoto2

	 o killall (#4052)

	 o ln

	 o npm (#4241)

	 o ssh (#4377)

	 o tail

	 o xdg-mime (#4333)

	 o zypper (#4325)

   fish	2.6.0 (released	June 3,	2017)
       Since the beta release of fish 2.6b1, fish  version  2.6.0  contains  a
       number  of  minor  fixes,  new completions for magneto (#4043), and im-
       provements to the documentation.

   Known issues
       o Apple macOS Sierra 10.12.5 introduced a problem  with	launching  web
	 browsers from other programs using AppleScript. This affects the fish
	 Web configuration (fish_config); users	on these platforms  will  need
	 to  manually  open  the address displayed in the terminal, such as by
	 copying and pasting it	into a browser.	This  problem  will  be	 fixed
	 with macOS 10.12.6.

       If  you	are upgrading from version 2.5.0 or before, please also	review
       the release notes for 2.6b1 (included below).

					----

   fish	2.6b1 (released	May 14,	2017)
   Notable fixes and improvements
       o Jobs running in the background	can now	be removed from	 the  list  of
	 jobs with the new disown builtin, which behaves like the same command
	 in other shells (#2810).

       o Command substitutions now have	access to the terminal,	like in	 other
	 shells. This allows tools like	fzf to work properly (#1362, #3922).

       o In  cases  where the operating	system does not	report the size	of the
	 terminal, the COLUMNS and LINES environment variables	are  used;  if
	 they are unset, a default of 80x24 is assumed.

       o New French (#3772 & #3788) and	improved German	(#3834)	translations.

       o fish no longer	depends	on the which external command.

   Other significant changes
       o Performance  improvements in launching	processes, including major re-
	 ductions in signal blocking. Although this has	been  heavily  tested,
	 it  may  cause	 problems  in some circumstances; set the FISH_NO_SIG-
	 NAL_BLOCK variable to 0 in your fish configuration file to return  to
	 the old behaviour (#2007).

       o Performance  improvements  in	prompts	and functions that set lots of
	 colours (#3793).

       o The Delete key	no longer deletes backwards (a regression in 2.5.0).

       o functions supports a new --details option, which identifies where the
	 function  was	loaded	from (#3295), and a --details --verbose	option
	 which includes	the function description (#597).

       o read will read	up to 10 MiB by	default, leaving the  target  variable
	 empty	and  exiting with status 122 if	the line is too	long.  You can
	 set a different limit with the	FISH_READ_BYTE_LIMIT variable.

       o read supports a new --silent option to	hide the characters  typed  (-
	 #838),	 for when reading sensitive data from the terminal.  read also
	 now accepts simple strings for	the prompt (rather than	scripts)  with
	 the new -P and	--prompt-str options (#802).

       o export	 and  setenv  now  understand colon-separated PATH, CDPATH and
	 MANPATH variables.

       o setenv	is no longer a simple alias for	set  -gx  and  will  complain,
	 just like the csh version, if given more than one value (#4103).

       o bind supports a new --list-modes option (#3872).

       o bg will check all of its arguments before backgrounding any jobs; any
	 invalid arguments will	cause a	failure, but non-existent (eg recently
	 exited) jobs are ignored (#3909).

       o funced	 warns	if  the	function being edited has not been modified (-
	 #3961).

       o printf	correctly outputs along	longa integers (#3352).

       o status	supports a new current-function	subcommand to print  the  cur-
	 rent function name (#1743).

       o string	 supports  a new repeat	subcommand (#3864).  string match sup-
	 ports a new --entire option to	emit the entire	line matched by	a pat-
	 tern  (#3957).	 string	replace	supports a new --filter	option to only
	 emit lines which underwent a replacement (#3348).

       o test supports the -k option to	test for sticky	bits (#733).

       o umask understands symbolic modes (#738).

       o Empty components in the CDPATH, MANPATH and PATH  variables  are  now
	 converted to a.a (#2106, #3914).

       o New versions of ncurses (6.0 and up) wipe terminal scrollback buffers
	 with certain commands;	the C-l	binding	tries to avoid this (#2855).

       o Some systemsa su implementations do  not  set	the  USER  environment
	 variable; it is now reset for root users (#3916).

       o Under	terminals which	support	it, bracketed paste is enabled,	escap-
	 ing problematic characters for	security and convience	(#3871).   In-
	 side  single quotes ('), single quotes	and backslashes	in pasted text
	 are escaped (#967). The fish_clipboard_paste function (bound  to  C-v
	 by default) is	still the recommended pasting method where possible as
	 it includes this functionality	and more.

       o Processes in pipelines	are no longer signalled	as soon	as one command
	 in  the  pipeline has completed (#1926). This behaviour matches other
	 shells	mre closely.

       o All functions requiring Python	work with whichever version of	Python
	 is  installed	(#3970). Python	3 is preferred,	but Python 2.6 remains
	 the minimum version required.

       o The color of the cancellation character  can  be  controlled  by  the
	 fish_color_cancel variable (#3963).

       o Added completions for:

       o caddy (#4008)

       o castnow (#3744)

       o climate (#3760)

       o flatpak

       o gradle	(#3859)

       o gsettings (#4001)

       o helm (#3829)

       o i3-msg	(#3787)

       o ipset (#3924)

       o jq (#3804)

       o light (#3752)

       o minikube (#3778)

       o mocha (#3828)

       o mkdosfs (#4017)

       o pv (#3773)

       o setsid	(#3791)

       o terraform (#3960)

       o usermod (#3775)

       o xinput

       o yarn (#3816)

       o Improved  completions	for  adb  (#3853),  apt	 (#3771), bzr (#3769),
	 dconf,	git (including #3743), grep (#3789), go	(#3789), help (#3789),
	 hg (#3975), htop (#3789), killall (#3996), lua, man (#3762), mount (-
	 #3764 & #3841), obnam	(#3924),  perl	(#3856),  portmaster  (#3950),
	 python	 (#3840),  ssh (#3781),	scp (#3781), systemctl (#3757) and ud-
	 isks (#3764).

					----

   fish	2.5.0 (released	February 3, 2017)
       There are no major changes between 2.5b1	and 2.5.0. If you are  upgrad-
       ing  from version 2.4.0 or before, please also review the release notes
       for 2.5b1 (included below).

   Notable fixes and improvements
       o The Home, End,	Insert,	Delete,	Page Up	and Page  Down	keys  work  in
	 Vi-style key bindings (#3731).

					----

   fish	2.5b1 (released	January	14, 2017)
   Platform Changes
       Starting	 with  version 2.5, fish requires a more up-to-date version of
       C++, specifically C++11 (from 2011). This affects some older platforms:

   Linux
       For users building from source, GCCas g++ 4.8 or	later, or LLVMas clang
       3.3  or	later,	are known to work. Older platforms may require a newer
       compiler	installed.

       Unfortunately, because of the complexity	of the toolchain, binary pack-
       ages  are no longer published by	the fish-shell developers for the fol-
       lowing platforms:

       o Red Hat Enterprise Linux and CentOS 5 & 6 for 64-bit builds

       o Ubuntu	12.04 (EoLTS April 2017)

       o Debian	7 (EoLTS May 2018)

       Installing newer	version	of fish	on these systems will require building
       from source.

   OS X	SnowLeopard
       Starting	with version 2.5, fish requires	a C++11	standard library on OS
       X 10.6 (aSnowLeoparda). If this library is not installed, you will  see
       this error: dyld: Library not loaded: /usr/lib/libc++.1.dylib

       MacPorts	 is  the  easiest way to obtain	this library. After installing
       the SnowLeopard MacPorts	release	from the install page, run:

	  sudo port -v install libcxx

       Now fish	should launch successfully. (Please open an issue if  it  does
       not.)

       This  is	 only  necessary  on 10.6. OS X	10.7 and later include the re-
       quired library by default.

   Other significant changes
       o Attempting to exit with running processes in the background  produces
	 a warning, then signals them to terminate if a	second attempt to exit
	 is made. This brings the behaviour for	running	 background  processes
	 into line with	stopped	processes. (#3497)

       o random	can now	have start, stop and step values specified, or the new
	 choice	subcommand can be used to pick an  argument  from  a  list  (-
	 #3619).

       o A  new	 key  bindings preset, fish_hybrid_key_bindings, including all
	 the  Emacs-style  and	 Vi-style   bindings,	which	behaves	  like
	 fish_vi_key_bindings in fish 2.3.0 (#3556).

       o function  now	returns	 an  error  when  called with invalid options,
	 rather	than defining the function anyway (#3574). This	was a  regres-
	 sion present in fish 2.3 and 2.4.0.

       o fish no longer	prints a warning when it identifies a running instance
	 of an old version (2.1.0 and earlier).	Changes	to universal variables
	 may not propagate between these old versions and 2.5b1.

       o Improved  compatiblity	 with Android (#3585), MSYS/mingw (#2360), and
	 Solaris (#3456, #3340).

       o Like other shells, the	test builting now returns an error for numeric
	 operations on invalid integers	(#3346,	#3581).

       o complete  no  longer recognises --authoritative and --unauthoritative
	 options, and they are marked as obsolete.

       o status	accepts	subcommands, and should	be used	like status  is-inter-
	 active.  The old options continue to be supported for the foreseeable
	 future	(#3526), although only one subcommand or option	can be	speci-
	 fied at a time.

       o Selection  mode  (used	 with  abegin-selectiona)  no longer selects a
	 character the cursor does not move over (#3684).

       o List indexes are handled better, and a	bit  more  liberally  in  some
	 cases (echo $PATH[1 ..	3] is now valid) (#3579).

       o The  fish_mode_prompt	function  is now simply	a stub around fish_de-
	 fault_mode_prompt, which allows the mode prompt to be	included  more
	 easily	in customised prompt functions (#3641).

   Notable fixes and improvements
       o alias,	 run  without options or arguments, lists all defined aliases,
	 and aliases now include a description in the function signature  that
	 identifies them.

       o complete accepts empty	strings	as descriptions	(#3557).

       o command accepts -q/--quiet in combination with	--search (#3591), pro-
	 viding	a simple way of	checking whether a command exists in scripts.

       o Abbreviations can now be renamed with abbr --rename  OLD_KEY  NEW_KEY
	 (#3610).

       o The command synopses printed by --help	options	work better with copy-
	 ing and pasting (#2673).

       o help launches the browser specified by	the  $fish_help_browser	 vari-
	 able if it is set (#3131).

       o History  merging  could lose items under certain circumstances	and is
	 now fixed (#3496).

       o The $status variable is now set to 123	when a	syntactically  invalid
	 command is entered (#3616).

       o Exiting  fish	now signals all	background processes to	terminate, not
	 just stopped jobs (#3497).

       o A new prompt_hostname function	which prints a hostname	 suitable  for
	 use in	prompts	(#3482).

       o The __fish_man_page function (bound to	Alt-h by default) now tries to
	 recognize subcommands (e.g. git add will now open the	agit-adda  man
	 page) (#3678).

       o A  new	 function  edit_command_buffer	(bound to Alt-e	& Alt-v	by de-
	 fault)	to edit	the command  buffer  in	 an  external  editor  (#1215,
	 #3627).

       o set_color  now	 supports italics (--italics), dim (--dim) and reverse
	 (--reverse) modes (#3650).

       o Filesystems with very slow locking  (eg  incorrectly-configured  NFS)
	 will no longer	slow fish down (#685).

       o Improved  completions	for  apt  (#3695), fusermount (#3642), make (-
	 #3628), netctl-auto (#3378), nmcli (#3648), pygmentize	 (#3378),  and
	 tar (#3719).

       o Added completions for:

       o VBoxHeadless (#3378)

       o VBoxSDL (#3378)

       o base64	(#3378)

       o caffeinate (#3524)

       o dconf (#3638)

       o dig (#3495)

       o dpkg-reconfigure (#3521 & #3522)

       o feh (#3378)

       o launchctl (#3682)

       o lxc (#3554 & #3564),

       o mddiagnose (#3524)

       o mdfind	(#3524)

       o mdimport (#3524)

       o mdls (#3524)

       o mdutil	(#3524)

       o mkvextract (#3492)

       o nvram (#3524)

       o objdump (#3378)

       o sysbench (#3491)

       o tmutil	(#3524)

					----

   fish	2.4.0 (released	November 8, 2016)
       There are no major changes between 2.4b1	and 2.4.0.

   Notable fixes and improvements
       o The documentation is now generated properly and with the correct ver-
	 sion identifier.

       o Automatic cursor changes are now only enabled on the subset of	 XTerm
	 versions  known to support them, resolving a problem where older ver-
	 sions printed garbage to the terminal before and after	 every	prompt
	 (#3499).

       o Improved the title set	in Apple Terminal.app.

       o Added	completions for	defaults and improved completions for diskutil
	 (#3478).

					----

   fish	2.4b1 (released	October	18, 2016)
   Significant changes
       o The clipboard integration has been revamped with  explicit  bindings.
	 The killring commands no longer copy from, or paste to, the X11 clip-
	 board - use the new copy (C-x)	and paste (C-v)	bindings instead.  The
	 clipboard  is	now  available	on  OS	X as well as systems using X11
	 (e.g. Linux). (#3061)

       o history uses subcommands (history delete) rather than	options	 (his-
	 tory  --delete)  for  its  actions (#3367). You can no	longer specify
	 multiple actions via flags (e.g., history --delete --save something).

       o New history options have been added, including	--max=n	to  limit  the
	 number	 of  history entries, --show-time option to show timestamps (-
	 #3175,	#3244),	and --null to null terminate history  entries  in  the
	 search	output.

       o history search	is now case-insensitive	by default (which also affects
	 history delete) (#3236).

       o history delete	now correctly handles multiline	commands (#31).

       o Vi-style bindings no longer include all of  the  default  emacs-style
	 bindings; instead, they share some definitions	(#3068).

       o If  there  is	no locale set in the environment, various known	system
	 configuration files will be checked for a default. If no  locale  can
	 be found, en_US-UTF.8 will be used (#277).

       o A  number followed by a caret (e.g. 5^) is no longer treated as a re-
	 direction (#1873).

       o The $version special variable can be overwritten, so that it  can  be
	 used for other	purposes if required.

   Notable fixes and improvements
       o The  fish_realpath builtin has	been renamed to	realpath and made com-
	 patible with GNU realpath when	run without arguments (#3400).	It  is
	 used  only  for  systems  without  a realpath or grealpath utility (-
	 #3374).

       o Improved color	handling on terminals/consoles with 8-16 colors,  par-
	 ticularly the use of bright named color (#3176, #3260).

       o fish_indent  can  now read from files given as	arguments, rather than
	 just standard input (#3037).

       o Fuzzy tab completions behave in  a  less  surprising  manner  (#3090,
	 #3211).

       o jobs should only print	its header line	once (#3127).

       o Wildcards in redirections are highlighted appropriately (#2789).

       o Suggestions  will  be offered more often, like	after removing charac-
	 ters (#3069).

       o history --merge now correctly interleaves items in chronological  or-
	 der (#2312).

       o Options  for  fish_indent have	been aligned with the other binaries -
	 in particular,	-d now means --debug. The --dump option	has  been  re-
	 named to --dump-parse-tree (#3191).

       o The  display  of  bindings  in	 the  Web-based	configuration has been
	 greatly improved (#3325), as has the rendering	of prompts (#2924).

       o fish should no	longer hang using 100% CPU in the C locale (#3214).

       o A bug in FreeBSD 11 & 12, Dragonfly BSD & illumos prevented fish from
	 working  correctly  on	 these platforms under UTF-8 locales; fish now
	 avoids	the buggy behaviour (#3050).

       o Prompts which show git	repository information (via __fish_git_prompt)
	 are  faster  in  large	 repositories  (#3294) and slow	filesystems (-
	 #3083).

       o fish 2.3.0 reintroduced a problem where the greeting was printed even
	 when using read; this has been	corrected again	(#3261).

       o Vi mode changes the cursor depending on the current mode (#3215).

       o Command  lines	 with escaped space characters at the end tab-complete
	 correctly (#2447).

       o Added completions for:

	 o arcanist (#3256)

	 o connmanctl (#3419)

	 o figlet (#3378)

	 o mdbook (#3378)

	 o ninja (#3415)

	 o p4, the Perforce client (#3314)

	 o pygmentize (#3378)

	 o ranger (#3378)

       o Improved completions for aura (#3297),	abbr  (#3267),	brew  (#3309),
	 chown	(#3380,	 #3383),cygport	 (#3392),  git	(#3274,	 #3226,	#3225,
	 #3094,	#3087, #3035, #3021, #2982,  #3230),  kill  &  pkill  (#3200),
	 screen	(#3271), wget (#3470), and xz (#3378).

       o Distributors,	packagers  and	developers  will notice	that the build
	 process produces more succinct	output by default; use make V=1	to get
	 verbose output	(#3248).

       o Improved  compatibility  with minor platforms including musl (#2988),
	 Cygwin	(#2993), Android (#3441, #3442), Haiku (#3322) and Solaris .

					----

   fish	2.3.1 (released	July 3,	2016)
       This is a functionality and bugfix release. This	release	does not  con-
       tain all	the changes to fish since the last release, but	fixes a	number
       of issues directly affecting users at present and includes a small num-
       ber of new features.

   Significant changes
       o A  new	 fish_key_reader binary	for decoding interactive keypresses (-
	 #2991).

       o fish_mode_prompt has been updated to reflect the changes in  the  way
	 the Vi	input mode is set up (#3067), making this more reliable.

       o fish_config  can now properly be launched from	the OS X app bundle (-
	 #3140).

   Notable fixes and improvements
       o Extra lines were sometimes inserted into  the	output	under  Windows
	 (Cygwin  and  Microsoft Windows Subsystem for Linux) due to TTY time-
	 stamps	not being updated (#2859).

       o The string builtinas match mode now handles the combination  of  -rnv
	 (match, invert	and count) correctly (#3098).

       o Improvements  to  TTY special character handling (#3064), locale han-
	 dling (#3124) and terminal environment	variable handling (#3060).

       o Work towards  handling	 the  terminal	modes  for  external  commands
	 launched from initialisation files (#2980).

       o Ease  the upgrade path	from fish 2.2.0	and before by warning users to
	 restart fish if the string builtin is not available (#3057).

       o type -a now syntax-colorizes function source output.

       o Added completions for alsamixer, godoc, gofmt,	 goimports,  gorename,
	 lscpu,	 mkdir,	modinfo, netctl-auto, poweroff,	termite, udisksctl and
	 xz (#3123).

       o Improved completions for apt (#3097), aura (#3102),git	 (#3114),  npm
	 (#3158), string and suspend (#3154).

					----

   fish	2.3.0 (released	May 20,	2016)
       There are no significant	changes	between	2.3.0 and 2.3b2.

   Other notable fixes and improvements
       o abbr now allows non-letter keys (#2996).

       o Define	a few extra colours on first start (#2987).

       o Multiple documentation	updates.

       o Added completions for rmmod (#3007).

       o Improved completions for git (#2998).

   Known issues
       o Interactive  commands	started	 from fish configuration files or from
	 the -c	option may, under certain circumstances, be started  with  in-
	 correct  terminal  modes  and	fail  to  behave as expected. A	fix is
	 planned but requires further testing (#2619).

					----

   fish	2.3b2 (released	May 5, 2016)
   Significant changes
       o A new fish_realpath builtin and associated function to	allow the  use
	 of  realpath  even  on	those platforms	that donat ship	an appropriate
	 command (#2932).

       o Alt-# toggles the current command line	between	commented  and	uncom-
	 mented	 states,  making  it easy to save a command in history without
	 executing it.

       o The  fish_vi_mode  function  is   now	 deprecated   in   favour   of
	 fish_vi_key_bindings.

   Other notable fixes and improvements
       o Fix  the build	on Cygwin (#2952) and RedHat Enterprise	Linux/CentOS 5
	 (#2955).

       o Avoid confusing the terminal line driver with non-printing characters
	 in fish_title (#2453).

       o Improved  completions	for  busctl,  git  (#2585,  #2879, #2984), and
	 netctl.

					----

   fish	2.3b1 (released	April 19, 2016)
   Significant Changes
       o A new string builtin to handlea| strings! This	builtin	will  measure,
	 split,	 search	 and replace text strings, including using regular ex-
	 pressions. It can also	be used	to turn	lists into plain strings using
	 join.	string	can be used in place of	sed, grep, tr, cut, and	awk in
	 many situations. (#2296)

       o Allow using escape as the Meta	modifier key, by waiting after	seeing
	 an  escape  character	wait  up to 300ms for an additional character.
	 This is consistent with readline (e.g.	bash) and  can	be  configured
	 via  the  fish_escape_delay_ms	 variable. This	allows using escape as
	 the Meta modifier. (#1356)

       o Add new directories for vendor	functions and  configuration  snippets
	 (#2500)

       o A  new	 fish_realpath builtin and associated realpath function	should
	 allow scripts to  resolve  path  names	 via  realpath	regardless  of
	 whether  there	 is an external	command	of that	name; albeit with some
	 limitations. See the associated documentation.

   Backward-incompatible changes
       o Unmatched globs will now cause	an error, except when used  with  for,
	 set or	count (#2719)

       o and  and  or  will now	bind to	the closest if or while, allowing com-
	 pound conditions without begin	and end	(#1428)

       o set -ql now searches up to function scope for variables (#2502)

       o status	-f will	now behave the same when run as	the main script	or us-
	 ing source (#2643)

       o source	 no  longer  puts  the	file name in $argv if no arguments are
	 given (#139)

       o History files are stored under	the XDG_DATA_HOME  hierarchy  (by  de-
	 fault,	 in  ~/.local/share),  and  existing  history will be moved on
	 first use (#744)

   Other notable fixes and improvements
       o Fish no longer	silences errors	in config.fish (#2702)

       o Directory autosuggestions will	now descend  as	 far  as  possible  if
	 there is only one child directory (#2531)

       o Add support for bright	colors (#1464)

       o Allow Ctrl-J (cj) to be bound separately from Ctrl-M (cm) (#217)

       o psub  now has a a-sa/aasuffixa	option to name the temporary file with
	 that suffix

       o Enable	24-bit colors on select	terminals (#2495)

       o Support for SVN status	in the prompt (#2582)

       o Mercurial and SVN support have	been added to the Classic +  Git  (now
	 Classic  +  VCS)  prompt  (via	the new	__fish_vcs_prompt function) (-
	 #2592)

       o export	now handles variables with a a=a in the	value (#2403)

       o New completions for:

	 o alsactl

	 o Archlinuxas asp, makepkg

	 o Atomas apm (#2390)

	 o entr	- the aEvent Notify Test Runnera (#2265)

	 o Fedoraas dnf	(#2638)

	 o OSX diskutil	(#2738)

	 o pkgng (#2395)

	 o pulseaudioas	pacmd and pactl

	 o rustas rustc	and cargo (#2409)

	 o sysctl (#2214)

	 o systemdas machinectl	(#2158), busctl	(#2144), systemd-nspawn,  sys-
	   temd-analyze, localectl, timedatectl

	 o and more

       o Fish  no longer has a function	called sgrep, freeing it for user cus-
	 tomization (#2245)

       o A rewrite of the completions for cd, fixing a few bugs	(#2299,	#2300,
	 #562)

       o Linux VTs now run in a	simplified mode	to avoid issues	(#2311)

       o The vi-bindings now inherit from the emacs bindings

       o Fish will also	execute	fish_user_key_bindings when in vi-mode

       o funced	will now also check $VISUAL (#2268)

       o A new suspend function	(#2269)

       o Subcommand completion now works better	with split /usr	(#2141)

       o The  command-not-found-handler	 can  now  be overridden by defining a
	 function called __fish_command_not_found_handler  in  config.fish  (-
	 #2332)

       o A few fixes to	the Sorin theme

       o PWD   shortening  in  the  prompt  can	 now  be  configured  via  the
	 fish_prompt_pwd_dir_length variable, set to the length	per path  com-
	 ponent	(#2473)

       o fish no longer	requires /etc/fish/config.fish to correctly start, and
	 now ships a skeleton file that	only contains  some  documentation  (-
	 #2799)

					----

   fish	2.2.0 (released	July 12, 2015)
   Significant changes
       o Abbreviations:	the new	abbr command allows for	interactively-expanded
	 abbreviations,	allowing quick access to frequently-used  commands  (-
	 #731).

       o Vi  mode:  run	 fish_vi_mode to switch	fish into the key bindings and
	 prompt	familiar to users of the Vi editor (#65).

       o New inline and	interactive pager, which will be familiar to users  of
	 zsh (#291).

       o Underlying architectural changes: the fishd universal variable	server
	 has been removed as it	was a source of	many bugs and  security	 prob-
	 lems. Notably,	old fish sessions will not be able to communicate uni-
	 versal	variable changes with new fish	sessions.  For	best  results,
	 restart all running instances of fish.

       o The  web-based	 configuration	tool  has been redesigned, featuring a
	 prompt	theme chooser and other	improvements.

       o New German, Brazilian Portuguese, and Chinese translations.

   Backward-incompatible changes
       These are kept to a minimum, but	either change undocumented features or
       are  too	 hard  to use in their existing	forms. These changes may break
       existing	scripts.

       o commandline no	longer interprets functions ain	reversea, instead  be-
	 having	as expected (#1567).

       o The  previously-undocumented CMD_DURATION variable is now set for all
	 commands and contains the execution time of the last command in  mil-
	 liseconds  (#1585).  It  is  no  longer exported to other commands (-
	 #1896).

       o if / else conditional statements now return  values  consistent  with
	 the Single Unix Specification,	like other shells (#1443).

       o A  new	 atop-levela  local scope has been added, allowing local vari-
	 ables declared	on the commandline to be visible  to  subsequent  com-
	 mands.	(#1908)

   Other notable fixes and improvements
       o New  documentation  design  (#1662), which requires a Doxygen version
	 1.8.7 or newer	to build.

       o Fish now defines a default directory for other	 packages  to  provide
	 completions. By default this is /usr/share/fish/vendor-completions.d;
	 on systems with pkgconfig installed this path	is  discoverable  with
	 pkg-config --variable completionsdir fish.

       o A new parser removes many bugs; all existing syntax should keep work-
	 ing.

       o New fish_preexec and fish_postexec events are fired before and	 after
	 job execution respectively (#1549).

       o Unmatched  wildcards  no longer prevent a job from running. Wildcards
	 used interactively will still print an	error, but the job  will  pro-
	 ceed and the wildcard will expand to zero arguments (#1482).

       o The  .	 command  is deprecated	and the	source command is preferred (-
	 #310).

       o bind supports abind modesa, which allows bindings to  be  set	for  a
	 particular named mode,	to support the implementation of Vi mode.

       o A new export alias, which behaves like	other shells (#1833).

       o command  has a	new --search option to print the name of the disk file
	 that would be executed, like other shellsa command -v (#1540).

       o commandline has a new --paging-mode option to support the new pager.

       o complete has a	new --wraps option, which allows a command to  (recur-
	 sively) inherit the completions of a wrapped command (#393), and com-
	 plete -e now correctly	erases completions (#380).

       o Completions are now generated from manual pages  by  default  on  the
	 first run of fish (#997).

       o fish_indent can now produce colorized (--ansi)	and HTML (--html) out-
	 put (#1827).

       o functions  --erase  now  prevents  autoloaded	functions  from	 being
	 reloaded in the current session.

       o history  has  a new --merge option, to	incorporate history from other
	 sessions into the current session (#825).

       o jobs returns 1	if there are no	active jobs (#1484).

       o read has several new options:

       o --array to break input	into an	array (#1540)

       o --null	to break lines on NUL characters rather	than newlines (#1694)

       o --nchars to read a specific number of characters (#1616)

       o --right-prompt	to display a right-hand-side prompt during interactive
	 read (#1698).

       o type  has  a  new -q option to	suppress output	(#1540 and, like other
	 shells, type -a now prints all	matches	for a command (#261).

       o Pressing F1 now shows the manual page	for  the  current  command  (-
	 #1063).

       o fish_title  functions	have  access to	the arguments of the currently
	 running argument as $argv[1] (#1542).

       o The OS	command-not-found handler is used on Arch Linux	(#1925), nixOS
	 (#1852), openSUSE and Fedora (#1280).

       o Alt+.	searches  backwards  in	the token history, mapping to the same
	 behavior as inserting the last	argument of the	previous command, like
	 other shells (#89).

       o The  SHLVL  environment  variable  is	incremented correctly (#1634 &
	 #1693).

       o Added completions for adb (#1165 & #1211), apt	(#2018), aura (#1292),
	 composer  (#1607),  cygport (#1841), dropbox (#1533), elixir (#1167),
	 fossil, heroku	(#1790), iex (#1167), kitchen  (#2000),	 nix  (#1167),
	 node/npm  (#1566), opam (#1615), setfacl (#1752), tmuxinator (#1863),
	 and yast2 (#1739).

       o Improved completions for brew (#1090 &	#1810),	bundler	(#1779), cd (-
	 #1135),  emerge  (#1840),git (#1680, #1834 & #1951), man (#960), mod-
	 probe (#1124),	pacman (#1292),	rpm (#1236),  rsync  (#1872),  scp  (-
	 #1145), ssh (#1234), sshfs (#1268), systemctl (#1462, #1950 & #1972),
	 tmux (#1853), vagrant (#1748),	yum (#1269), and zypper	(#1787).

					----

   fish	2.1.2 (released	Feb 24,	2015)
       fish 2.1.2 contains a workaround	for a  filesystem  bug	in  Mac	 OS  X
       Yosemite. #1859

       Specifically,  after  installing	fish 2.1.1 and then rebooting, aVerify
       Diska in	Disk Utility will report aInvalid number of  hard  links.a  We
       donat have any reports of data loss or other adverse consequences. fish
       2.1.2 avoids triggering the bug,	but does not  repair  an  already  af-
       fected filesystem. To repair the	filesystem, you	can boot into Recovery
       Mode and	use Repair Disk	from Disk Utility. Linux and versions of OS  X
       prior to	Yosemite are believed to be unaffected.

       There are no other changes in this release.

					----

   fish	2.1.1 (released	September 26, 2014)
       Important: if you are upgrading,	stop all running instances of fishd as
       soon as possible	after installing this release; it  will	 be  restarted
       automatically.  On  most	 systems,  there will be no further action re-
       quired. Note that some environments  (where  XDG_RUNTIME_DIR  is	 set),
       such as Fedora 20, will require a restart of all	running	fish processes
       before universal	variables work as intended.

       Distributors are	highly encouraged to call killall fishd,  pkill	 fishd
       or similar in installation scripts, or to warn their users to do	so.

   Security fixes
       o The  fish_config  web	interface  now uses an authentication token to
	 protect requests and only responds to requests	from the local machine
	 with  this token, preventing a	remote code execution attack. (closing
	 CVE-2014-2914). #1438

       o psub and funced are no	longer vulnerable to attacks which allow local
	 privilege  escalation	and  data tampering (closing CVE-2014-2906 and
	 CVE-2014-3856). #1437

       o fishd uses a secure path for its socket, preventing a local privilege
	 escalation attack (closing CVE-2014-2905). #1436

       o __fish_print_packages	is no longer vulnerable	to attacks which would
	 allow	local  privilege  escalation  and  data	  tampering   (closing
	 CVE-2014-3219). #1440

   Other fixes
       o fishd now ignores SIGPIPE, fixing crashes using tools like GNU	Paral-
	 lel and which occurred	more often as a	 result	 of  the  other	 fishd
	 changes. #1084	& #1690

					----

   fish	2.1.0
   Significant Changes
       o Tab completions will fuzzy-match files. #568

	 When  tab-completing  a  file,	fish will first	attempt	prefix matches
	 (foo matches foobar), then substring matches (ooba  matches  foobar),
	 and  lastly subsequence matches (fbr matches foobar). For example, in
	 a directory with files	foo1.txt, foo2.txt, foo3.txta|,	you  can  type
	 only the numeric part and hit tab to fill in the rest.

	 This  feature is implemented for files	and executables. It is not yet
	 implemented for options (like	--foobar),  and	 not  yet  implemented
	 across	path components	(like /u/l/b to	match /usr/local/bin).

       o Redirections now work better across pipelines.	#110, #877

	 In  particular, you can pipe stderr and stdout	together, for example,
	 with cmd ^&1 |	tee log.txt, or	the  more  familiar  cmd  2>&1	|  tee
	 log.txt.

       o A single ``%``	now expands to the last	job backgrounded. #1008

	 Previously,  a	 single	 % would pid-expand to either all backgrounded
	 jobs, or all jobs owned by your user. Now it expands to the last  job
	 backgrounded. If no job is in the background, it will fail to expand.
	 In particular,	fg % can be used to put	the most recent	background job
	 in the	foreground.

   Other Notable Fixes
       o alt-U	and  alt+C  now	 uppercase and capitalize words, respectively.
	 #995

       o VTE based terminals should now	know the working directory. #906

       o The autotools build now works on Mavericks. #968

       o The end-of-line binding (ctrl+E) now accepts autosuggestions. #932

       o Directories in	/etc/paths (used on OS X) are now prepended instead of
	 appended, similar to other shells. #927

       o Option-right-arrow  (used  for	partial	autosuggestion completion) now
	 works on iTerm2. #920

       o Tab completions now work properly within nested subcommands. #913

       o printf	supports \e, the escape	character. #910

       o fish_config history no	longer shows duplicate items. #900

       o $fish_user_paths is now prepended to $PATH instead of appended.  #888

       o Jobs complete when all	processes complete. #876

	 For example, in previous versions of fish, sleep 10 | echo  Done  re-
	 turns	control	 immediately,  because	echo does not read from	stdin.
	 Now it	does not complete until	sleep exits (presumably	after 10  sec-
	 onds).

       o Better	error reporting	for square brackets. #875

       o fish  no  longer  tries  to  add /bin to $PATH	unless PATH is totally
	 empty.	#852

       o History token substitution (alt-up) now works correctly  inside  sub-
	 shells. #833

       o Flow  control is now disabled,	freeing	up ctrl-S and ctrl-Q for other
	 uses. #814

       o sh-style variable setting like	foo=bar	now produces better error mes-
	 sages.	#809

       o Commands with wildcards no longer produce autosuggestions. #785

       o funced	no longer freaks out when supplied with	no arguments. #780

       o fish.app now works correctly in a directory containing	spaces.	#774

       o Tab completion	cycling	no longer occasionally fails to	repaint. #765

       o Comments now work in evalad strings. #684

       o History search	(up-arrow) now shows the item matching the autosugges-
	 tion, if that autosuggestion was truncated. #650

       o Ctrl-T	now transposes characters, as in other shells. #128

					----

   fish	2.0.0
   Significant Changes
       o Command substitutions now modify ``$status`` :issue:`547`. Previously
	 the  exit  status  of command substitutions (like (pwd)) was ignored;
	 however now it	modifies $status. Furthermore,	the  set  command  now
	 only sets $status on failure; it is untouched on success. This	allows
	 for the following pattern:

	    if set python_path (which python)
	       ...
	    end

	 Because set does not modify $status on	success, the if	branch	effec-
	 tively	tests whether which succeeded, and if so, whether the set also
	 succeeded.

       o Improvements  to  PATH	  handling.   There   is   a   new   variable,
	 fish_user_paths, which	can be set universally,	and whose contents are
	 appended to $PATH #527

	 o /etc/paths and /etc/paths.d are now respected on OS X

	 o fish	no longer modifies $PATH to find its own binaries

       o Long lines no longer use ellipsis for line breaks, and	copy and paste
	 should	no longer include a newline even if the	line was broken	#300

       o New syntax for	index ranges (sometimes	known as aslicesa) #212

       o fish now supports an ``else if`` statement #134

       o Process and pid completion now	works on OS X #129

       o fish  is  now relocatable, and	no longer depends on compiled-in paths
	 #125

       o fish  now   supports	a   right   prompt   (RPROMPT)	 through   the
	 fish_right_prompt function #80

       o fish  now  uses  posix_spawn  instead of fork when possible, which is
	 much faster on	BSD and	OS X #11

   Other Notable Fixes
       o Updated VCS completions (darcs, cvs, svn, etc.)

       o Avoid calling getcwd on the main thread, as it	can hang #696

       o Control-D (forward delete) no longer stops at a period	#667

       o Completions for many new commands

       o fish now respects rxvtas unique keybindings #657

       o xsel is no longer built as part of fish. It will still	be invoked  if
	 installed separately #633

       o __fish_filter_mime no longer spews #628

       o The ano-execute option	to fish	no longer falls	over when reaching the
	 end of	a block	#624

       o fish_config knows how to find fish even if itas not in	the $PATH #621

       o A leading space now prevents writing to history, as is	done  in  bash
	 and zsh #615

       o Hitting enter after a backslash only goes to a	new line if it is fol-
	 lowed by whitespace or	the end	of the line #613

       o printf	is now a builtin #611

       o Event handlers	should no longer fire if signals are blocked #608

       o set_color is now a builtin #578

       o man page completions are now located in a  new	 generated_completions
	 directory, instead of your completions	directory #576

       o tab now clears	autosuggestions	#561

       o tab  completion  from within a	pair of	quotes now attempts to aappro-
	 priatea the closing quote #552

       o $EDITOR can now be a list: for	example, set EDITOR gvim -f) #541

       o case bodies are now indented #530

       o The profile switch -p no longer crashes #517

       o You can now control-C out of read #516

       o umask is now functional on OS X #515

       o Avoid calling getpwnam	on the main thread, as it can hang #512

       o Alt-F or Alt-right-arrow (Option-F or option-right-arrow) now accepts
	 one word of an	autosuggestion #435

       o Setting fish as your login shell no longer kills OpenSUSE #367

       o Backslashes  now  join	 lines,	 instead of creating multiple commands
	 #347

       o echo now implements the -e flag to interpret escapes #337

       o When the last token in	the useras input contains capital letters, use
	 its case in preference	to that	of the autosuggestion #335

       o Descriptions now have their own muted color #279

       o Wildcards  beginning  with a .	(for example, ls .*) no	longer match .
	 and ..	#270

       o Recursive wildcards now handle	symlink	loops #268

       o You can now delete history items from the fish_config	web  interface
	 #250

       o The OS	X build	now weak links wcsdup and wcscasecmp #240

       o fish now saves	and restores the process group,	which prevents certain
	 processes from	being erroneously reported as stopped #197

       o funced	now takes an editor option #187

       o Alternating  row  colors  are	available  in	fish   pager   through
	 fish_pager_color_secondary #186

       o Universal  variable  values are now stored based on your MAC address,
	 not your hostname #183

       o The caret ^ now only does a stderr redirection	if  it	is  the	 first
	 character of a	token, making git users	happy #168

       o Autosuggestions will no longer	cause line wrapping #167

       o Better	handling of Unicode combining characters #155

       o fish SIGHUPs processes	more often #138

       o fish no longer	causes sudo to ask for a password every	time

       o fish behaves better under Midnight Commander #121

       o set -e	no longer crashes #100

       o fish  now will	automatically import history from bash,	if there is no
	 fish history #66

       o Backslashed-newlines inside quoted  strings  now  behave  more	 intu-
	 itively #52

       o Tab titles should be shown correctly in iTerm2	#47

       o scp remote path completion now	sometimes works	#42

       o The read builtin no longer shows autosuggestions #29

       o Custom	 key  bindings	can  now be set	via the	fish_user_key_bindings
	 function #21

       o All Python scripts now	run correctly under both Python	2 and Python 3
	 #14

       o The aaccept autosuggestiona key can now be configured #19

       o Autosuggestions will no longer	suggest	invalid	commands #6

					----

   fishfish Beta r2
   Bug Fixes
       o Implicit  cd  is  back,  for paths that start with one	or two dots, a
	 slash,	or a tilde.

       o Overrides of default functions	should	be  fixed.  The	 ainternalized
	 scriptsa feature is disabled for now.

       o Disabled  delayed  suspend.  This is a	strange	job-control feature of
	 BSD systems, including	OS X. Disabling	it  frees  up  Control	Y  for
	 other purposes; in particular,	for yank, which	now works on OS	X.

       o fish_indent  is  fixed.  In particular, the funced and	funcsave func-
	 tions work again.

       o A SIGTERM now ends the	whole execution	stack again (resolving #13).

       o Bumped	the __fish_config_interactive version number  so  the  default
	 fish_color_autosuggestion kicks in.

       o fish_config  better  handles combined term256 and classic colors like
	 a555 yellowa.

   New Features
       o A history builtin, and	associated interactive function	 that  enables
	 deleting  history items. Example usage: * Print all history items be-
	 ginning with echo: history --prefix echo * Print  all	history	 items
	 containing  foo:  history  --contains foo * Interactively delete some
	 items containing foo: history --delete	--contains foo

       Credit to @siteshwar for	implementation.	Thanks @siteshwar!

					----

   fishfish Beta r1
   Scripting
       o No changes! All existing fish	scripts,  config  files,  completions,
	 etc. from trunk should	continue to work.

   New Features
       o Autosuggestions.  Think  URL fields in	browsers. When you type	a com-
	 mand, fish will suggest the rest of the command after the cursor,  in
	 a  muted  gray	 when possible.	You can	accept the suggestion with the
	 right arrow key or Ctrl-F. Suggestions	 come  from  command  history,
	 completions,  and some	custom code for	cd; thereas a lot of potential
	 for improvement here. The suggestions are computed  on	 a  background
	 pthread, so they never	slow down your typing. The autosuggestion fea-
	 ture is incredible. I miss it dearly every time I use anything	else.

       o term256 support where available, specifically modern xterms and OS  X
	 Lion.	You  can  specify  colors the old way (aset_color cyana) or by
	 specifying RGB	hex values (aset_color FF3333a); fish  will  pick  the
	 closest supported color. Some xterms do not advertise term256 support
	 either	in the $TERM or	terminfo max_colors  field,  but  nevertheless
	 support  it.  For that	reason,	fish will default into using it	on any
	 xterm (but it can be disabled with an environment variable).

       o Web-based configuration page. There is	a new function	afish_configa.
	 This  spins  up a simple Python web server and	opens a	browser	window
	 to it.	From this web page, you	can set	your  shell  colors  and  view
	 your functions, variables, and	history; all changes apply immediately
	 to all	running	shells.	Eventually all configuration ought to be  sup-
	 ported	 via  this mechanism (but in addition to, not instead of, com-
	 mand line mechanisms).

       o Man page completions. There is	a  new	function  afish_update_comple-
	 tionsa. This function reads all the man1 files	from your manpath, re-
	 moves the roff	formatting, parses them	to find	the commands  and  op-
	 tions,	 and outputs fish completions into ~/.config/fish/completions.
	 It wonat overwrite existing completion	files  (except	ones  that  it
	 generated itself).

   Programmatic	Changes
       o fish  is  now entirely	in C++.	I have no particular love for C++, but
	 it provides a ready memory-model to replace halloc. Weave made	an ef-
	 fort to keep it to a sane and portable	subset (no C++11, no boost, no
	 going crazy with templates or smart pointers),	but we do use the  STL
	 and a little tr1.

       o halloc	 is entirely gone, replaced by normal C++ ownership semantics.
	 If you	donat know what	halloc is, well, now you have two  reasons  to
	 be happy.

       o All  the  crufty  C  data structures are entirely gone. array_list_t,
	 priority_queue_t, hash_table_t, string_buffer_t have been removed and
	 replaced   by	 STL   equivalents  like  std::vector,	std::map,  and
	 std::wstring. A lot of	the string handling now	uses std::wstring  in-
	 stead of wchar_t *

       o fish  now spawns pthreads for tasks like syntax highlighting that re-
	 quire blocking	I/O.

       o History has been completely rewritten.	History	files now use  an  ex-
	 tensible  YAML-style syntax. History amerginga	(multiple shells writ-
	 ing to	the same history file) now works better. There is now a	 maxi-
	 mum history length of about 250k items	(256 * 1024).

       o The parser has	been ainstanced,a so you can now create	more than one.

       o Total #LoC has	shrunk slightly	even with the new features.

   Performance
       o fish  now  runs syntax	highlighting in	a background thread, so	typing
	 commands is always responsive even on slow filesystems.

       o echo, test, and pwd are now builtins, which eliminates	many forks.

       o The files in share/functions and share/completions now	get ainternal-
	 izeda	into  C	 strings that get compiled in with fish. This substan-
	 tially	reduces	the number of files touched at startup.	A  consequence
	 is  that  you	cannot change these functions without recompiling, but
	 often other functions depend on these astandarda functions, so	chang-
	 ing them is perhaps not a good	idea anyways.

       Here  are  some	system call counts for launching and then exiting fish
       with the	default	configuration, on OS  X.  The  first  column  is  fish
       trunk, the next column is with our changes, and the last	column is bash
       for comparison. This data was collected via dtrace.

       before

       after

       bash

       open

       9

       4

       5

       fork

       28

       14

       0

       stat

       131

       85

       11

       lstat

       670

       0

       0

       read

       332

       80

       4

       write

       172

       149

       0

       The large number	of forks relative to bash are due to  fishas  insanely
       expensive  default  prompt,  which  is  unchanged  in my	version. If we
       switch to a prompt comparable to	bashas (lame) default, the forks  drop
       to 16 with trunk, 4 after our changes.

       The large reduction in lstat() numbers is due to	fish no	longer needing
       to call ttyname() on OS X.

       Weave got some work to do to be as lean as bash,	but weare on the right
       track.

   License
   License for fish
       fish  Copyright	A(C) 2005-2009 Axel Liljencrantz, 2009-2021 fish-shell
       contributors. fish is released under the	GNU  General  Public  License,
       version 2.

       fish includes other code	licensed under the GNU General Public License,
       version 2, including GNU	printf.

       Copyright A(C) 1990-2007	Free Software Foundation,  Inc.	 Printf	 (from
       GNU  Coreutils  6.9)  is	released under the GNU General Public License,
       version 2.

       The GNU General Public License agreement	follows.

       GNU GENERAL PUBLIC LICENSE

       Version 2, June 1991
	  Copyright (C)	1989, 1991 Free	Software Foundation, Inc.  51 Franklin
	  Street, Fifth	Floor, Boston, MA  02110-1301, USA

	  Everyone is permitted	to copy	and distribute verbatim	copies of this
	  license document, but	changing it is not allowed.

       Preamble

       The licenses for	most software are designed to take away	 your  freedom
       to share	and change it.	By contrast, the GNU General Public License is
       intended	to guarantee your freedom to share and change free software  -
       to make sure the	software is free for all its users.  This General Pub-
       lic License applies to most of the Free Software	Foundation's  software
       and to any other	program	whose authors commit to	using it.  (Some other
       Free Software Foundation	software is covered by the GNU Library General
       Public License instead.)	 You can apply it to your programs, too.

       When we speak of	free software, we are referring	to freedom, not	price.
       Our General Public Licenses are designed	to make	sure that you have the
       freedom to distribute copies of free software (and charge for this ser-
       vice if you wish), that you receive source code or can get  it  if  you
       want  it,  that	you can	change the software or use pieces of it	in new
       free programs; and that you know	you can	do these things.

       To protect your rights, we need to make restrictions that forbid	anyone
       to  deny	 you these rights or to	ask you	to surrender the rights. These
       restrictions translate to certain responsibilities for you if you  dis-
       tribute copies of the software, or if you modify	it.

       For example, if you distribute copies of	such a program,	whether	gratis
       or for a	fee, you must give the recipients  all	the  rights  that  you
       have.  You must make sure that they, too, receive or can	get the	source
       code.  And you must show	them these terms so they know their rights.

       We protect your rights with two steps: (1) copyright the	software,  and
       (2)  offer  you	this license which gives you legal permission to copy,
       distribute and/or modify	the software.

       Also, for each author's protection and ours, we want  to	 make  certain
       that everyone understands that there is no warranty for this free soft-
       ware.  If the software is modified by someone else and  passed  on,  we
       want its	recipients to know that	what they have is not the original, so
       that any	problems introduced by others will not reflect on the original
       authors'	reputations.

       Finally,	any free program is threatened constantly by software patents.
       We wish to avoid	the danger that	redistributors of a free program  will
       individually  obtain patent licenses, in	effect making the program pro-
       prietary. To prevent this, we have made it clear	that any  patent  must
       be licensed for everyone's free use or not licensed at all.

       The  precise terms and conditions for copying, distribution and modifi-
       cation follow.

       TERMS AND CONDITIONS FOR	COPYING, DISTRIBUTION AND MODIFICATION

       o This License applies to any program or	other work  which  contains  a
	 notice	 placed	 by  the copyright holder saying it may	be distributed
	 under the terms of this General Public	License.  The  "Program",  be-
	 low,  refers  to  any	such program or	work, and a "work based	on the
	 Program" means	either the Program or any derivative work under	 copy-
	 right law: that is to say, a work containing the Program or a portion
	 of it,	either verbatim	or with	modifications and/or  translated  into
	 another language.  (Hereinafter, translation is included without lim-
	 itation in the	term "modification".) Each licensee  is	 addressed  as
	 "you".
	  Activities other than	copying, distribution and modification are not
	  covered by this License; they	are outside its	 scope.	  The  act  of
	  running  the Program is not restricted, and the output from the Pro-
	  gram is covered only if its contents constitute a work based on  the
	  Program  (independent	 of  having been made by running the Program).
	  Whether that is true depends on what the Program does.

       1. You may copy and distribute verbatim copies of the Program's	source
	  code	as  you	receive	it, in any medium, provided that you conspicu-
	  ously	and appropriately publish on each copy	an  appropriate	 copy-
	  right	notice and disclaimer of warranty; keep	intact all the notices
	  that refer to	this License and to the	absence	of any	warranty;  and
	  give	any  other  recipients	of  the	Program	a copy of this License
	  along	with the Program.
	  You may charge a fee for the physical	act of	transferring  a	 copy,
	  and you may at your option offer warranty protection in exchange for
	  a fee.

       2. You may modify your copy or copies of	the Program or any portion  of
	  it,  thus forming a work based on the	Program, and copy and distrib-
	  ute such modifications or work under the terms of Section  1	above,
	  provided that	you also meet all of these conditions:

	  o You	must cause the modified	files to carry prominent notices stat-
	    ing	that you changed the files and the date	of any change.

	  o You	must cause any work that you distribute	or  publish,  that  in
	    whole  or  in  part	contains or is derived from the	Program	or any
	    part thereof, to be	licensed as a whole at no charge to all	 third
	    parties under the terms of this License.

	  o If the modified program normally reads commands interactively when
	    run, you must cause	it, when started running for such  interactive
	    use	 in the	most ordinary way, to print or display an announcement
	    including an appropriate copyright notice and a notice that	 there
	    is	no  warranty (or else, saying that you provide a warranty) and
	    that users may redistribute	the program  under  these  conditions,
	    and	 telling  the user how to view a copy of this License. (Excep-
	    tion: if the Program itself	is interactive but does	 not  normally
	    print  such	an announcement, your work based on the	Program	is not
	    required to	print an announcement.)

	  These	requirements apply to the modified work	as a whole.  If	 iden-
	  tifiable sections of that work are not derived from the Program, and
	  can be reasonably considered independent and separate	works in them-
	  selves, then this License, and its terms, do not apply to those sec-
	  tions	when you distribute them as separate works.  But when you dis-
	  tribute  the	same sections as part of a whole which is a work based
	  on the Program, the distribution of the whole	must be	on  the	 terms
	  of this License, whose permissions for other licensees extend	to the
	  entire whole,	and thus to each and  every  part  regardless  of  who
	  wrote	it.

	  Thus,	 it  is	not the	intent of this section to claim	rights or con-
	  test your rights to work written entirely by you; rather, the	intent
	  is  to  exercise the right to	control	the distribution of derivative
	  or collective	works based on the Program.

	  In addition, mere aggregation	of another work	not based on the  Pro-
	  gram	with  the  Program  (or	with a work based on the Program) on a
	  volume of a storage or distribution medium does not bring the	 other
	  work under the scope of this License.

       3. You  may copy	and distribute the Program (or a work based on it, un-
	  der Section 2) in object code	or executable form under the terms  of
	  Sections  1 and 2 above provided that	you also do one	of the follow-
	  ing:

	  o Accompany it  with	the  complete  corresponding  machine-readable
	    source code, which must be distributed under the terms of Sections
	    1 and 2 above on a medium customarily  used	 for  software	inter-
	    change; or,

	  o Accompany it with a	written	offer, valid for at least three	years,
	    to give any	third party, for a charge no more than	your  cost  of
	    physically	 performing   source   distribution,  a	 complete  ma-
	    chine-readable copy	of the corresponding source code, to  be  dis-
	    tributed  under  the  terms	 of Sections 1 and 2 above on a	medium
	    customarily	used for software interchange; or,

	  o Accompany it with the information you received as to the offer  to
	    distribute	corresponding  source  code.  (This alternative	is al-
	    lowed only for noncommercial distribution and only if you received
	    the	 program in object code	or executable form with	such an	offer,
	    in accord with Subsection b	above.)

	  The source code for a	work means the preferred form of the work  for
	  making modifications to it.  For an executable work, complete	source
	  code means all the source code for all modules it contains, plus any
	  associated interface definition files, plus the scripts used to con-
	  trol compilation and installation of the executable.	However, as  a
	  special exception, the source	code distributed need not include any-
	  thing	that is	normally distributed (in either	source or binary form)
	  with the major components (compiler, kernel, and so on) of the oper-
	  ating	system on which	the executable runs, unless that component it-
	  self accompanies the executable.

	  If distribution of executable	or object code is made by offering ac-
	  cess to copy from a designated place,	then offering  equivalent  ac-
	  cess to copy the source code from the	same place counts as distribu-
	  tion of the source code, even	though third parties are not compelled
	  to copy the source along with	the object code.

       4. You  may not copy, modify, sublicense, or distribute the Program ex-
	  cept as expressly provided under this	License. Any attempt otherwise
	  to  copy,  modify, sublicense	or distribute the Program is void, and
	  will automatically terminate your rights under  this	License.  How-
	  ever,	 parties  who  have received copies, or	rights,	from you under
	  this License will not	have their licenses terminated so long as such
	  parties remain in full compliance.

       5. You  are  not	 required  to  accept this License, since you have not
	  signed it. However, nothing else grants you permission to modify  or
	  distribute  the  Program or its derivative works.  These actions are
	  prohibited by	law if you do not accept this License.	Therefore,  by
	  modifying or distributing the	Program	(or any	work based on the Pro-
	  gram), you indicate your acceptance of this License to  do  so,  and
	  all  its terms and conditions	for copying, distributing or modifying
	  the Program or works based on	it.

       6. Each time you	redistribute the Program (or any  work	based  on  the
	  Program),  the  recipient  automatically receives a license from the
	  original licensor to copy, distribute	or modify the Program  subject
	  to  these  terms  and	conditions. You	may not	impose any further re-
	  strictions on	the recipients'	exercise of the	rights granted herein.
	  You are not responsible for enforcing	compliance by third parties to
	  this License.

       7. If, as a consequence of a court judgment or allegation of patent in-
	  fringement  or  for any other	reason (not limited to patent issues),
	  conditions are imposed on you	(whether by court order, agreement  or
	  otherwise)  that  contradict the conditions of this License, they do
	  not excuse you from the conditions of	this License.  If  you	cannot
	  distribute  so  as  to satisfy simultaneously	your obligations under
	  this License and any other pertinent obligations, then as  a	conse-
	  quence  you may not distribute the Program at	all. For example, if a
	  patent license would not permit royalty-free redistribution  of  the
	  Program  by  all  those  who	receive	 copies	directly or indirectly
	  through you, then the	only way you could satisfy both	 it  and  this
	  License  would  be to	refrain	entirely from distribution of the Pro-
	  gram.
	  If any portion of this section is held invalid or unenforceable  un-
	  der  any  particular circumstance, the balance of the	section	is in-
	  tended to apply and the section as a whole is	intended to  apply  in
	  other	circumstances.

	  It  is not the purpose of this section to induce you to infringe any
	  patents or other property right claims or to contest validity	of any
	  such claims; this section has	the sole purpose of protecting the in-
	  tegrity of the free software distribution system,  which  is	imple-
	  mented  by public license practices.	Many people have made generous
	  contributions	to the wide range of software distributed through that
	  system  in  reliance on consistent application of that system; it is
	  up to	the author/donor to decide if he or she	is willing to distrib-
	  ute  software	 through any other system and a	licensee cannot	impose
	  that choice.

	  This section is intended to make thoroughly clear what  is  believed
	  to be	a consequence of the rest of this License.

       8. If  the distribution and/or use of the Program is restricted in cer-
	  tain countries either	by patents or by copyrighted  interfaces,  the
	  original  copyright holder who places	the Program under this License
	  may add an explicit geographical distribution	 limitation  excluding
	  those	 countries, so that distribution is permitted only in or among
	  countries not	thus excluded.	In such	case,  this  License  incorpo-
	  rates	the limitation as if written in	the body of this License.

       9. The Free Software Foundation may publish revised and/or new versions
	  of the General Public	License	from time to time.  Such new  versions
	  will	be similar in spirit to	the present version, but may differ in
	  detail to address new	problems or concerns.
	  Each version is given	a distinguishing version number.  If the  Pro-
	  gram	specifies a version number of this License which applies to it
	  and "any later version", you have the	option of following the	 terms
	  and  conditions  either of that version or of	any later version pub-
	  lished by the	Free Software Foundation.  If  the  Program  does  not
	  specify a version number of this License, you	may choose any version
	  ever published by the	Free Software Foundation.

       10.
	  If you wish to incorporate parts of the Program into other free pro-
	  grams	 whose distribution conditions are different, write to the au-
	  thor to ask for permission.  For software which  is  copyrighted  by
	  the Free Software Foundation,	write to the Free Software Foundation;
	  we sometimes make exceptions for this.  Our decision will be	guided
	  by the two goals of preserving the free status of all	derivatives of
	  our free software and	of promoting the sharing and reuse of software
	  generally.
	  NO WARRANTY

       11. BECAUSE  THE	 PROGRAM  IS LICENSED FREE OF CHARGE, THERE IS NO WAR-
	   RANTY FOR THE PROGRAM, TO THE EXTENT	PERMITTED BY  APPLICABLE  LAW.
	   EXCEPT  WHEN	 OTHERWISE  STATED  IN	WRITING	 THE COPYRIGHT HOLDERS
	   AND/OR OTHER	PARTIES	PROVIDE	THE PROGRAM "AS	IS"  WITHOUT  WARRANTY
	   OF  ANY  KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIM-
	   ITED	TO, THE	IMPLIED	WARRANTIES OF MERCHANTABILITY AND FITNESS  FOR
	   A  PARTICULAR  PURPOSE.  THE	ENTIRE RISK AS TO THE QUALITY AND PER-
	   FORMANCE OF THE PROGRAM IS WITH YOU.	 SHOULD	THE PROGRAM PROVE  DE-
	   FECTIVE,  YOU ASSUME	THE COST OF ALL	NECESSARY SERVICING, REPAIR OR
	   CORRECTION.

       12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRIT-
	   ING	WILL  ANY  COPYRIGHT HOLDER, OR	ANY OTHER PARTY	WHO MAY	MODIFY
	   AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED	ABOVE,	BE  LIABLE  TO
	   YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CON-
	   SEQUENTIAL DAMAGES ARISING OUT OF THE USE OR	INABILITY TO  USE  THE
	   PROGRAM  (INCLUDING	BUT  NOT LIMITED TO LOSS OF DATA OR DATA BEING
	   RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES  OR
	   A  FAILURE OF THE PROGRAM TO	OPERATE	WITH ANY OTHER PROGRAMS), EVEN
	   IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF  THE  POSSIBILITY
	   OF SUCH DAMAGES.

   License for PCRE2
       fish  contains  code  from  the [PCRE2](http://www.pcre.org) library to
       support regular expressions. This code, created	by  Philip  Hazel,  is
       distributed  under  the	terms  of  the	BSD  license.  Copyright  A(C)
       1997-2015 University of Cambridge.

       The BSD license follows.

       Redistribution and use in source	and binary forms, with or without mod-
       ification,  are	permitted  provided  that the following	conditions are
       met:

	  o Redistributions of source code must	retain the above copyright no-
	    tice, this list of conditions and the following disclaimer.

	  o Redistributions  in	binary form must reproduce the above copyright
	    notice, this list of conditions and	the  following	disclaimer  in
	    the	documentation and/or other materials provided with the distri-
	    bution.

	  o Neither the	name of	the University of Cambridge nor	the  names  of
	    any	 contributors  may  be used to endorse or promote products de-
	    rived from this software without specific  prior  written  permis-
	    sion.

       THIS SOFTWARE IS	PROVIDED BY THE	COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
       IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT  NOT  LIMITED
       TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC-
       ULAR PURPOSE ARE	DISCLAIMED. IN NO EVENT	SHALL THE COPYRIGHT  OWNER  OR
       CONTRIBUTORS  BE	 LIABLE	FOR ANY	DIRECT,	INDIRECT, INCIDENTAL, SPECIAL,
       EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,	BUT  NOT  LIMITED  TO,
       PROCUREMENT  OF	SUBSTITUTE  GOODS  OR  SERVICES; LOSS OF USE, DATA, OR
       PROFITS;	OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON	ANY THEORY  OF
       LIABILITY,  WHETHER  IN	CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
       NEGLIGENCE OR OTHERWISE)	ARISING	IN ANY WAY OUT	OF  THE	 USE  OF  THIS
       SOFTWARE, EVEN IF ADVISED OF THE	POSSIBILITY OF SUCH DAMAGE.

   License for the Python docs theme
       In	    doc_src/python_docs_theme/,		  taken		  from
       https://pypi.org/project/python-docs-theme/2020.1/.

       PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2

       1. This LICENSE AGREEMENT is between  the  Python  Software  Foundation
       ("PSF"),	 and the Individual or Organization ("Licensee") accessing and
       otherwise using this software ("Python")	in source or binary  form  and
       its associated documentation.

       2.  Subject  to the terms and conditions	of this	License	Agreement, PSF
       hereby grants Licensee a	nonexclusive, royalty-free, world-wide license
       to  reproduce,  analyze,	test, perform and/or display publicly, prepare
       derivative works, distribute, and otherwise use Python alone or in  any
       derivative version, provided, however, that PSF's License Agreement and
       PSF's notice of copyright, i.e.,	"Copyright (c) 2001, 2002, 2003, 2004,
       2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016,
       2017 Python Software Foundation;	All Rights Reserved" are  retained  in
       Python alone or in any derivative version prepared by Licensee.

       3. In the event Licensee	prepares a derivative work that	is based on or
       incorporates Python or any part thereof,	and wants to make the  deriva-
       tive  work available to others as provided herein, then Licensee	hereby
       agrees to include in any	such work a brief summary of the changes  made
       to Python.

       4. PSF is making	Python available to Licensee on	an "AS IS" basis.  PSF
       MAKES NO	REPRESENTATIONS	OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY  OF
       EXAMPLE,	BUT NOT	LIMITATION, PSF	MAKES NO AND DISCLAIMS ANY REPRESENTA-
       TION OR WARRANTY	OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR  PUR-
       POSE  OR	 THAT  THE  USE	 OF  PYTHON  WILL NOT INFRINGE ANY THIRD PARTY
       RIGHTS.

       5. PSF SHALL NOT	BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON FOR
       ANY  INCIDENTAL,	 SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A	RESULT
       OF MODIFYING, DISTRIBUTING, OR OTHERWISE	USING PYTHON, OR  ANY  DERIVA-
       TIVE THEREOF, EVEN IF ADVISED OF	THE POSSIBILITY	THEREOF.

       6.  This	License	Agreement will automatically terminate upon a material
       breach of its terms and conditions.

       7. Nothing in this License Agreement shall be deemed to create any  re-
       lationship of agency, partnership, or joint venture between PSF and Li-
       censee.	This License Agreement does not	grant permission  to  use  PSF
       trademarks  or  trade  name  in a trademark sense to endorse or promote
       products	or services of Licensee, or any	third party.

       8. By copying, installing or otherwise using Python, Licensee agrees to
       be bound	by the terms and conditions of this License Agreement.

AUTHOR
       fish-shell developers

COPYRIGHT
       2021, fish-shell	developers

3.3				 Nov 06, 2021			   FISH-DOC(1)

NAME | FURTHER READING | INSTALLATION AND START | CONFIGURATION FILES | FURTHER HELP AND DEVELOPMENT | OTHER HELP PAGES | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=fish-doc&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help