diff --git a/sphinx_doc_src/cmds/abbr.rst b/sphinx_doc_src/cmds/abbr.rst index 5721cb6f1..91174d6a5 100644 --- a/sphinx_doc_src/cmds/abbr.rst +++ b/sphinx_doc_src/cmds/abbr.rst @@ -10,13 +10,15 @@ abbr --rename [SCOPE] OLD_WORD NEW_WORD abbr --show abbr --list -\subsection abbr-description Description +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 abbreviated to `gco`. After entering `gco` and pressing @key{Space} or @key{Enter}, the full text `git checkout` will appear in the command line. -\subsection abbr-options Options +Options +------------ The following options are available: @@ -37,7 +39,8 @@ In addition, when adding abbreviations: See the "Internals" section for more on them. -\subsection abbr-example Examples +Examples +------------ \fish abbr -a -g gco git checkout @@ -64,7 +67,8 @@ ssh another_host abbr -s | source \endfish Import the abbreviations defined on another_host over SSH. -\subsection abbr-internals Internals +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 universal 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: diff --git a/sphinx_doc_src/cmds/alias.rst b/sphinx_doc_src/cmds/alias.rst index 0c5957cae..23a424d14 100644 --- a/sphinx_doc_src/cmds/alias.rst +++ b/sphinx_doc_src/cmds/alias.rst @@ -9,7 +9,8 @@ alias [OPTIONS] NAME DEFINITION alias [OPTIONS] NAME=DEFINITION -\subsection alias-description Description +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. @@ -26,7 +27,8 @@ The following options are available: - `-s` or `--save` Automatically save the function created by the alias into your fish configuration directory using funcsave. -\subsection alias-example Example +Example +------------ The following code will create `rmi`, which runs `rm` with additional arguments on every invocation. diff --git a/sphinx_doc_src/cmds/and.rst b/sphinx_doc_src/cmds/and.rst index bf2088706..7a11b6b88 100644 --- a/sphinx_doc_src/cmds/and.rst +++ b/sphinx_doc_src/cmds/and.rst @@ -7,7 +7,8 @@ Synopsis COMMAND1; and COMMAND2 -\subsection and-description Description +Description +------------ `and` is used to execute a command if the previous command was successful (returned a status of 0). @@ -15,7 +16,8 @@ COMMAND1; and COMMAND2 `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. -\subsection and-example Example +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. diff --git a/sphinx_doc_src/cmds/argparse.rst b/sphinx_doc_src/cmds/argparse.rst index 881d4df3b..999cf6ce7 100644 --- a/sphinx_doc_src/cmds/argparse.rst +++ b/sphinx_doc_src/cmds/argparse.rst @@ -7,7 +7,8 @@ Synopsis argparse [OPTIONS] OPTION_SPEC... -- [ARG...] -\subsection argparse-description Description +Description +------------ This command makes it easy for fish scripts and functions to handle arguments in a manner 100% identical to how fish builtin commands handle their arguments. You pass a sequence of arguments that define the options recognized, followed by a literal `--`, then the arguments to be parsed (which might also include a literal `--`). More on this in the usage section below. @@ -17,7 +18,8 @@ Each option that is seen in the ARG list will result in a var name of the form ` For example `_flag_h` and `_flag_help` if `-h` or `--help` is seen. The var 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, does not have an associated value) the values are the short and long flags seen. If the option is not a boolean flag 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 var will not be set. -\subsection argparse-options Options +Options +------------ The following `argparse` options are available. They must appear before all OPTION_SPECs: @@ -33,7 +35,8 @@ The following `argparse` options are available. They must appear before all OPTI - `-h` or `--help` displays help about using this command. -\subsection argparse-usage Usage +Usage +------------ Using this command involves passing two sets of arguments separated by `--`. The first set consists of one or more option specifications (`OPTION_SPEC` above) and options that modify the behavior of `argparse`. These must be listed before the `--` argument. The second set are the arguments to be parsed in accordance with the option specifications. They occur after the `--` argument and can be empty. More about this below but here is a simple example that might be used in a function named `my_function`: @@ -60,7 +63,8 @@ argparse 'h/help' 'n/name' $argv The first `--` seen is what allows the `argparse` command to reliably separate the option specifications from the command arguments. -\subsection argparse-option-specs Option Specifications +Option Specifications +------------ Each option specification is a string composed of @@ -84,7 +88,8 @@ See the `fish_opt` command for a friendlier but more ver In the following examples if a flag is not seen when parsing the arguments then the corresponding _flag_X var(s) will not be set. -\subsection argparse-validation Flag Value Validation +Flag Value Validation +------------ It is common to want to validate the the value provided for an option satisfies some criteria. For example, that it is a valid integer within a specific range. You can always do this after `argparse` returns but you can also request that `argparse` perform the validation by executing arbitrary fish script. To do so simply append an `!` (exclamation-mark) then the fish script to be run. When that code is executed three vars will be defined: @@ -100,7 +105,8 @@ The script should write any error messages to stdout, not stderr. It should retu 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 option 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 allowed. -\subsection argparse-optspec-examples Example OPTION_SPECs +Example OPTION_SPECs +------------ Some OPTION_SPEC examples: @@ -128,6 +134,7 @@ After parsing the arguments the `argv` var is set with local scope to any values If an error occurs during argparse processing it will exit with a non-zero status and print error messages to stderr. -\subsection argparse-notes Notes +Notes +------------ Prior to the addition of this builtin command in the 2.7.0 release there were two main ways to parse the arguments passed to a fish script or function. One way was to use the OS provided `getopt` command. The problem with that is that the GNU and BSD implementations are not compatible. Which makes using that external command difficult other than in trivial situations. The other way is to iterate over `$argv` and use the fish `switch` statement to decide how to handle the argument. That, however, involves a huge amount of boilerplate code. It is also borderline impossible to implement the same behavior as builtin commands. diff --git a/sphinx_doc_src/cmds/begin.rst b/sphinx_doc_src/cmds/begin.rst index 8819a8a63..f53e26585 100644 --- a/sphinx_doc_src/cmds/begin.rst +++ b/sphinx_doc_src/cmds/begin.rst @@ -7,7 +7,8 @@ Synopsis begin; [COMMANDS...;] end -\subsection begin-description Description +Description +------------ `begin` is used to create a new block of code. @@ -18,7 +19,8 @@ The block is unconditionally executed. `begin; ...; end` is equivalent to `if tr `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. -\subsection begin-example Example +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. diff --git a/sphinx_doc_src/cmds/bg.rst b/sphinx_doc_src/cmds/bg.rst index 5e884c268..866dbaa4c 100644 --- a/sphinx_doc_src/cmds/bg.rst +++ b/sphinx_doc_src/cmds/bg.rst @@ -7,7 +7,8 @@ Synopsis bg [PID...] -\subsection bg-description Description +Description +------------ `bg` sends jobs to the background, resuming them if they are stopped. @@ -18,7 +19,8 @@ When at least one of the arguments isn't a valid job specifier (i.e. PID), When all arguments are valid job specifiers, bg will background all matching jobs that exist. -\subsection bg-example Example +Example +------------ `bg 123 456 789` will background 123, 456 and 789. diff --git a/sphinx_doc_src/cmds/bind.rst b/sphinx_doc_src/cmds/bind.rst index 86743a2fe..9a5faebf8 100644 --- a/sphinx_doc_src/cmds/bind.rst +++ b/sphinx_doc_src/cmds/bind.rst @@ -16,7 +16,8 @@ bind (-e | --erase) [(-M | --mode) MODE] (-a | --all | [(-k | --key)] SEQUENCE [SEQUENCE...]) -\subsection bind-description Description +Description +------------ `bind` adds a binding for the specified key sequence to the specified command. @@ -60,7 +61,8 @@ The following parameters are available: - `--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 invocations except for inserting new bindings can operate on both levels at the same time. `--preset` should only be used in full binding sets (like when working on `fish_vi_key_bindings`). -\subsection bind-functions Special input functions +Special input functions +------------ The following special input functions are available: - `accept-autosuggestion`, accept the current autosuggestion completely @@ -144,7 +146,8 @@ The following special input functions are available: - `yank-pop`, rotate to the previous entry of the killring -\subsection bind-example Examples +Examples +------------ \fish bind \\cd 'exit' @@ -163,7 +166,8 @@ bind -M insert \\cc kill-whole-line force-repaint Turns on Vi key bindings and rebinds @key{Control,C} to clear the input line. -\subsection special-case-escape Special Case: The escape Character +Special Case: The escape Character +------------ The escape key can be used standalone, for example, to switch from insertion mode to normal mode when using Vi keybindings. Escape may also be used as a "meta" key, to indicate the start of an escape sequence, such as function or arrow keys. Custom bindings can also be defined that begin with an escape character. diff --git a/sphinx_doc_src/cmds/block.rst b/sphinx_doc_src/cmds/block.rst index 24566083f..4244c5795 100644 --- a/sphinx_doc_src/cmds/block.rst +++ b/sphinx_doc_src/cmds/block.rst @@ -7,7 +7,8 @@ Synopsis block [OPTIONS...] -\subsection block-description Description +Description +------------ `block` prevents events triggered by `fish` or the `emit` command from being delivered and acted upon while the block is in place. @@ -26,7 +27,8 @@ The following parameters are available: - `-e` or `--erase` Release global block -\subsection block-example Example +Example +------------ \fish # Create a function that listens for events @@ -43,6 +45,7 @@ block -e \endfish -\subsection block-notes Notes +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. diff --git a/sphinx_doc_src/cmds/break.rst b/sphinx_doc_src/cmds/break.rst index b20305e58..ebbac6608 100644 --- a/sphinx_doc_src/cmds/break.rst +++ b/sphinx_doc_src/cmds/break.rst @@ -7,14 +7,16 @@ Synopsis LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end -\subsection break-description Description +Description +------------ `break` halts a currently running loop, such as a for loop or a while loop. It is usually added inside of a conditional block such as an if statement or a switch statement. There are no parameters for `break`. -\subsection break-example Example +Example +------------ The following code searches all .c files for "smurf", and halts at the first occurrence. \fish diff --git a/sphinx_doc_src/cmds/breakpoint.rst b/sphinx_doc_src/cmds/breakpoint.rst index 4aa2852cc..81d951ce0 100644 --- a/sphinx_doc_src/cmds/breakpoint.rst +++ b/sphinx_doc_src/cmds/breakpoint.rst @@ -7,7 +7,8 @@ Synopsis breakpoint -\subsection breakpoint-description Description +Description +------------ `breakpoint` is used to halt a running script and launch an interactive debugging prompt. diff --git a/sphinx_doc_src/cmds/builtin.rst b/sphinx_doc_src/cmds/builtin.rst index 6df15691d..6afb4c6ab 100644 --- a/sphinx_doc_src/cmds/builtin.rst +++ b/sphinx_doc_src/cmds/builtin.rst @@ -7,7 +7,8 @@ Synopsis builtin BUILTINNAME [OPTIONS...] -\subsection builtin-description Description +Description +------------ `builtin` forces the shell to use a builtin command, rather than a function or program. @@ -16,7 +17,8 @@ The following parameters are available: - `-n` or `--names` List the names of all defined builtins -\subsection builtin-example Example +Example +------------ \fish builtin jobs diff --git a/sphinx_doc_src/cmds/case.rst b/sphinx_doc_src/cmds/case.rst index 2f06fb0a7..faf21d401 100644 --- a/sphinx_doc_src/cmds/case.rst +++ b/sphinx_doc_src/cmds/case.rst @@ -7,7 +7,8 @@ Synopsis switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end -\subsection case-description Description +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. @@ -18,7 +19,8 @@ Note that fish does not fall through on case statements. Only the first matching 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. -\subsection case-example Example +Example +------------ Say \$animal contains the name of an animal. Then this code would classify it: diff --git a/sphinx_doc_src/cmds/cd.rst b/sphinx_doc_src/cmds/cd.rst index 2e0590759..96d7283bd 100644 --- a/sphinx_doc_src/cmds/cd.rst +++ b/sphinx_doc_src/cmds/cd.rst @@ -7,7 +7,8 @@ Synopsis cd [DIRECTORY] -\subsection cd-description Description +Description +------------ `cd` changes the current working directory. If `DIRECTORY` is supplied, it will become the new directory. If no parameter is given, the contents of the `HOME` environment variable will be used. @@ -20,7 +21,8 @@ Fish also ships a wrapper function around the builtin `cd` that understands `cd 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 removed and recreated. -\subsection cd-example Examples +Examples +------------ \fish cd @@ -30,6 +32,7 @@ cd /usr/src/fish-shell # changes the working directory to /usr/src/fish-shell \endfish -\subsection cd-see-also See Also +See Also +------------ See also the `cdh` command for changing to a recently visited directory. diff --git a/sphinx_doc_src/cmds/cdh.rst b/sphinx_doc_src/cmds/cdh.rst index b122bd362..8ef8bb8b8 100644 --- a/sphinx_doc_src/cmds/cdh.rst +++ b/sphinx_doc_src/cmds/cdh.rst @@ -8,12 +8,14 @@ Synopsis cdh [ directory ] -\subsection cdh-description Description +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 @key{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 directory`. Note that the `cd` command limits directory history to the 25 most recently 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. -\subsection cdh-see-also See Also +See Also +------------ See also the `prevd` and `pushd` commands which also work with the recent `cd` history and are provided for compatibility with other shells. diff --git a/sphinx_doc_src/cmds/command.rst b/sphinx_doc_src/cmds/command.rst index 3e832d57c..c77b653b3 100644 --- a/sphinx_doc_src/cmds/command.rst +++ b/sphinx_doc_src/cmds/command.rst @@ -7,7 +7,8 @@ Synopsis command [OPTIONS] COMMANDNAME [ARGS...] -\subsection command-description Description +Description +------------ `command` forces the shell to execute the program `COMMANDNAME` and ignore any functions or builtins with the same name. @@ -23,7 +24,8 @@ With the `-s` option, `command` treats every argument as a separate command to l For basic compatibility with POSIX `command`, the `-v` flag is recognized as an alias for `-s`. -\subsection command-example Examples +Examples +------------ `command ls` causes fish to execute the `ls` program, even if an `ls` function exists. diff --git a/sphinx_doc_src/cmds/commandline.rst b/sphinx_doc_src/cmds/commandline.rst index 1241d3df7..dd02668d5 100644 --- a/sphinx_doc_src/cmds/commandline.rst +++ b/sphinx_doc_src/cmds/commandline.rst @@ -7,7 +7,8 @@ Synopsis commandline [OPTIONS] [CMD] -\subsection commandline-description Description +Description +------------ `commandline` can be used to set or get the current contents of the command line buffer. @@ -58,7 +59,8 @@ The following options output metadata about the commandline state: - `-P` or `--paging-mode` evaluates to true if the commandline is showing pager contents, such as tab completions -\subsection commandline-example Example +Example +------------ `commandline -j $history[3]` replaces the job under the cursor with the third item from the command line history. diff --git a/sphinx_doc_src/cmds/complete.rst b/sphinx_doc_src/cmds/complete.rst index 3691f7095..12d5a9ec1 100644 --- a/sphinx_doc_src/cmds/complete.rst +++ b/sphinx_doc_src/cmds/complete.rst @@ -20,7 +20,8 @@ complete ( -c | --command | -p | --path ) COMMAND complete ( -C[STRING] | --do-complete[=STRING] ) -\subsection complete-description Description +Description +------------ For an introduction to specifying completions, see Writing your own completions in @@ -93,7 +94,8 @@ The `-w` or `--wraps` options causes the specified command to inherit completion When erasing completions, it is possible to either erase all completions for a specific command by specifying `complete -c COMMAND -e`, or by specifying a specific completion option to delete by specifying either a long, short or old style option. -\subsection complete-example Example +Example +------------ The short style option `-o` for the `gcc` command requires that a file follows it. This can be done using writing: diff --git a/sphinx_doc_src/cmds/contains.rst b/sphinx_doc_src/cmds/contains.rst index 8f69ba214..25b0bd84d 100644 --- a/sphinx_doc_src/cmds/contains.rst +++ b/sphinx_doc_src/cmds/contains.rst @@ -7,7 +7,8 @@ Synopsis contains [OPTIONS] KEY [VALUES...] -\subsection contains-description Description +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. @@ -17,7 +18,8 @@ The following options are available: Note that, like GNU tools and most of fish's builtins, `contains` interprets all arguments starting with a `-` as options to contains, until it reaches an argument that is `--` (two dashes). See the examples below. -\subsection contains-example Example +Example +------------ If $animals is a list of animals, the following will test if it contains a cat: diff --git a/sphinx_doc_src/cmds/continue.rst b/sphinx_doc_src/cmds/continue.rst index 1d7b7fd03..2f131f5e8 100644 --- a/sphinx_doc_src/cmds/continue.rst +++ b/sphinx_doc_src/cmds/continue.rst @@ -7,11 +7,13 @@ Synopsis LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end -\subsection continue-description Description +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 inside of a conditional block such as an if statement or a switch statement. -\subsection continue-example Example +Example +------------ The following code removes all tmp files that do not contain the word smurf. diff --git a/sphinx_doc_src/cmds/count.rst b/sphinx_doc_src/cmds/count.rst index c84e7fe42..afe51ddc4 100644 --- a/sphinx_doc_src/cmds/count.rst +++ b/sphinx_doc_src/cmds/count.rst @@ -7,7 +7,8 @@ Synopsis count $VARIABLE -\subsection count-description Description +Description +------------ `count` prints the number of arguments that were passed to it. This is usually used to find out how many elements an environment variable array contains. @@ -16,7 +17,8 @@ count $VARIABLE `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. -\subsection count-example Example +Example +------------ \fish count $PATH diff --git a/sphinx_doc_src/cmds/dirh.rst b/sphinx_doc_src/cmds/dirh.rst index 451d44c17..61c0342c5 100644 --- a/sphinx_doc_src/cmds/dirh.rst +++ b/sphinx_doc_src/cmds/dirh.rst @@ -7,7 +7,8 @@ Synopsis dirh -\subsection dirh-description Description +Description +------------ `dirh` prints the current directory history. The current position in the history is highlighted using the color defined in the `fish_color_history_current` environment variable. diff --git a/sphinx_doc_src/cmds/dirs.rst b/sphinx_doc_src/cmds/dirs.rst index cd07b0f7a..fba514c59 100644 --- a/sphinx_doc_src/cmds/dirs.rst +++ b/sphinx_doc_src/cmds/dirs.rst @@ -8,7 +8,8 @@ dirs dirs -c -\subsection dirs-description Description +Description +------------ `dirs` prints the current directory stack, as created by the `pushd` command. diff --git a/sphinx_doc_src/cmds/disown.rst b/sphinx_doc_src/cmds/disown.rst index c61ca0c03..07bd5a9da 100644 --- a/sphinx_doc_src/cmds/disown.rst +++ b/sphinx_doc_src/cmds/disown.rst @@ -7,7 +7,8 @@ Synopsis disown [ PID ... ] -\subsection disown-description Description +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. @@ -19,7 +20,8 @@ If a job is stopped, it is sent a signal to continue running, and a warning is p `disown` returns 0 if all specified jobs were disowned successfully, and 1 if any problems were encountered. -\subsection disown-example Example +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. diff --git a/sphinx_doc_src/cmds/echo.rst b/sphinx_doc_src/cmds/echo.rst index b38dbcbcf..d29facf00 100644 --- a/sphinx_doc_src/cmds/echo.rst +++ b/sphinx_doc_src/cmds/echo.rst @@ -7,7 +7,8 @@ Synopsis echo [OPTIONS] [STRING] -\subsection echo-description Description +Description +------------ `echo` displays a string of text. @@ -21,7 +22,8 @@ The following options are available: - `-e`, Enable interpretation of backslash escapes -\subsection echo-escapes Escape Sequences +Escape Sequences +------------ If `-e` is used, the following sequences are recognized: @@ -49,7 +51,8 @@ If `-e` is used, the following sequences are recognized: - `\xHH` byte with hexadecimal value HH (1 to 2 digits) -\subsection echo-example Example +Example +------------ \fish echo 'Hello World' diff --git a/sphinx_doc_src/cmds/else.rst b/sphinx_doc_src/cmds/else.rst index 42a4ac8c8..c6c583deb 100644 --- a/sphinx_doc_src/cmds/else.rst +++ b/sphinx_doc_src/cmds/else.rst @@ -7,12 +7,14 @@ Synopsis if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end -\subsection else-description Description +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. -\subsection else-example Example +Example +------------ The following code tests whether a file `foo.txt` exists as a regular file. diff --git a/sphinx_doc_src/cmds/emit.rst b/sphinx_doc_src/cmds/emit.rst index e66f3c7da..b6c25bdfc 100644 --- a/sphinx_doc_src/cmds/emit.rst +++ b/sphinx_doc_src/cmds/emit.rst @@ -7,12 +7,14 @@ Synopsis emit EVENT_NAME [ARGUMENTS...] -\subsection emit-description Description +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. -\subsection emit-example Example +Example +------------ The following code first defines an event handler for the generic event named 'test_event', and then emits an event of that type. @@ -25,6 +27,7 @@ emit test_event something \endfish -\subsection emit-notes Notes +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. diff --git a/sphinx_doc_src/cmds/end.rst b/sphinx_doc_src/cmds/end.rst index 7ee68ef15..bae471a2f 100644 --- a/sphinx_doc_src/cmds/end.rst +++ b/sphinx_doc_src/cmds/end.rst @@ -11,7 +11,8 @@ for VARNAME in [VALUES...]; COMMANDS...; end switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end -\subsection end-description Description +Description +------------ `end` ends a block of commands. diff --git a/sphinx_doc_src/cmds/eval.rst b/sphinx_doc_src/cmds/eval.rst index 5e1d09aaf..9b75e5406 100644 --- a/sphinx_doc_src/cmds/eval.rst +++ b/sphinx_doc_src/cmds/eval.rst @@ -7,12 +7,14 @@ Synopsis eval [COMMANDS...] -\subsection eval-description Description +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. -\subsection eval-example Example +Example +------------ The following code will call the ls command. Note that `fish` does not support the use of shell variables as direct commands; `eval` can be used to work around this. diff --git a/sphinx_doc_src/cmds/exec.rst b/sphinx_doc_src/cmds/exec.rst index 7e0509397..4c1637bce 100644 --- a/sphinx_doc_src/cmds/exec.rst +++ b/sphinx_doc_src/cmds/exec.rst @@ -7,11 +7,13 @@ Synopsis exec COMMAND [OPTIONS...] -\subsection exec-description Description +Description +------------ `exec` replaces the currently running shell with a new command. On successful completion, `exec` never returns. `exec` cannot be used inside a pipeline. -\subsection exec-example Example +Example +------------ `exec emacs` starts up the emacs text editor, and exits `fish`. When emacs exits, the session will terminate. diff --git a/sphinx_doc_src/cmds/exit.rst b/sphinx_doc_src/cmds/exit.rst index 54467c09c..497e69292 100644 --- a/sphinx_doc_src/cmds/exit.rst +++ b/sphinx_doc_src/cmds/exit.rst @@ -7,7 +7,8 @@ Synopsis exit [STATUS] -\subsection exit-description Description +Description +------------ `exit` causes fish to exit. If `STATUS` is supplied, it will be converted to an integer and used as the exit code. Otherwise, the exit code will be that of the last command executed. diff --git a/sphinx_doc_src/cmds/false.rst b/sphinx_doc_src/cmds/false.rst index 7e64aa757..31645d0fc 100644 --- a/sphinx_doc_src/cmds/false.rst +++ b/sphinx_doc_src/cmds/false.rst @@ -7,6 +7,7 @@ Synopsis false -\subsection false-description Description +Description +------------ `false` sets the exit status to 1. diff --git a/sphinx_doc_src/cmds/fg.rst b/sphinx_doc_src/cmds/fg.rst index df0263687..8ed9731ab 100644 --- a/sphinx_doc_src/cmds/fg.rst +++ b/sphinx_doc_src/cmds/fg.rst @@ -7,11 +7,13 @@ Synopsis fg [PID] -\subsection fg-description Description +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 with the specified group ID is put in the foreground. -\subsection fg-example Example +Example +------------ `fg` will put the last job in the foreground. diff --git a/sphinx_doc_src/cmds/fish.rst b/sphinx_doc_src/cmds/fish.rst index 83183eaa8..f3a36b941 100644 --- a/sphinx_doc_src/cmds/fish.rst +++ b/sphinx_doc_src/cmds/fish.rst @@ -7,7 +7,8 @@ Synopsis fish [OPTIONS] [-c command] [FILE [ARGUMENTS...]] -\subsection fish-description Description +Description +------------ `fish` is a command-line shell written mainly with interactive use in mind. The full manual is available in HTML by using the help command from inside fish. diff --git a/sphinx_doc_src/cmds/fish_breakpoint_prompt.rst b/sphinx_doc_src/cmds/fish_breakpoint_prompt.rst index 2bef17f7c..47a411e98 100644 --- a/sphinx_doc_src/cmds/fish_breakpoint_prompt.rst +++ b/sphinx_doc_src/cmds/fish_breakpoint_prompt.rst @@ -9,7 +9,8 @@ function fish_breakpoint_prompt end -\subsection fish_breakpoint_prompt-description Description +Description +------------ By defining the `fish_breakpoint_prompt` function, the user can choose a custom prompt when asking for input in response to a `breakpoint` command. The `fish_breakpoint_prompt` function is executed when the prompt is to be shown, and the output is used as a prompt. @@ -18,7 +19,8 @@ The exit status of commands within `fish_breakpoint_prompt` will not modify the `fish` ships with a default version of this function that displays the function name and line number of the current execution context. -\subsection fish_breakpoint_prompt-example Example +Example +------------ A simple prompt that is a simplified version of the default debugging prompt: diff --git a/sphinx_doc_src/cmds/fish_config.rst b/sphinx_doc_src/cmds/fish_config.rst index e4098ddbd..2bc16e4b7 100644 --- a/sphinx_doc_src/cmds/fish_config.rst +++ b/sphinx_doc_src/cmds/fish_config.rst @@ -2,7 +2,8 @@ fish_config - start the web-based configuration interface ========================================== -\subsection fish_config-description Description +Description +------------ `fish_config` starts the web-based configuration interface. @@ -15,6 +16,7 @@ The web interface allows you to view your functions, variables and history, and 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. -\subsection fish_config-example Example +Example +------------ `fish_config` opens a new web browser window and allows you to configure certain fish settings. diff --git a/sphinx_doc_src/cmds/fish_indent.rst b/sphinx_doc_src/cmds/fish_indent.rst index 7ee66eaaf..8c7f0a74b 100644 --- a/sphinx_doc_src/cmds/fish_indent.rst +++ b/sphinx_doc_src/cmds/fish_indent.rst @@ -7,7 +7,8 @@ Synopsis fish_indent [OPTIONS] -\subsection fish_indent-description Description +Description +------------ `fish_indent` is used to indent a piece of fish code. `fish_indent` reads commands from standard input and outputs them to standard output or a specified file. diff --git a/sphinx_doc_src/cmds/fish_key_reader.rst b/sphinx_doc_src/cmds/fish_key_reader.rst index 818c4a59e..03199c37d 100644 --- a/sphinx_doc_src/cmds/fish_key_reader.rst +++ b/sphinx_doc_src/cmds/fish_key_reader.rst @@ -7,7 +7,8 @@ Synopsis fish_key_reader [OPTIONS] -\subsection fish_key_reader-description Description +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 standard input. Individual characters themselves and their hexadecimal values are displayed. @@ -25,7 +26,8 @@ The following options are available: - `-v` or `--version` prints fish_key_reader's version and exits. -\subsection fish_key_reader-usage-notes Usage Notes +Usage Notes +------------ The delay in milliseconds since the previous character was received is included in the diagnostic information written to stderr. This information may be useful to determine the optimal `fish_escape_delay_ms` setting or learn the amount of lag introduced by tools like `ssh`, `mosh` or `tmux`. diff --git a/sphinx_doc_src/cmds/fish_mode_prompt.rst b/sphinx_doc_src/cmds/fish_mode_prompt.rst index 2e7d7a4f7..cbaeb2817 100644 --- a/sphinx_doc_src/cmds/fish_mode_prompt.rst +++ b/sphinx_doc_src/cmds/fish_mode_prompt.rst @@ -5,12 +5,14 @@ fish_mode_prompt - define the appearance of the mode indicator The fish_mode_prompt function will output the mode indicator for use in vi-mode. -\subsection fish_mode_prompt-description Description +Description +------------ The default `fish_mode_prompt` function will output indicators about the current Vi editor mode displayed to the left of the regular prompt. Define your own function to customize the appearance of the mode indicator. You can also define an empty `fish_mode_prompt` function to remove the Vi mode indicators. The `$fish_bind_mode variable` can be used to determine the current mode. It will be one of `default`, `insert`, `replace_one`, or `visual`. -\subsection fish_mode_prompt-example Example +Example +------------ \fish function fish_mode_prompt diff --git a/sphinx_doc_src/cmds/fish_opt.rst b/sphinx_doc_src/cmds/fish_opt.rst index a76a42be2..e92b0c8ad 100644 --- a/sphinx_doc_src/cmds/fish_opt.rst +++ b/sphinx_doc_src/cmds/fish_opt.rst @@ -9,7 +9,8 @@ fish_opt ( -s X | --short=X ) [ -l LONG | --long=LONG ] [ --long-only ] \ [ -o | --optional-val ] [ -r | --required-val ] [ --multiple-vals ] -\subsection fish_opt-description Description +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. @@ -29,7 +30,8 @@ The following `argparse` options are available: - `-h` or `--help` displays help about using this command. -\subsection fish_opt-examples Examples +Examples +------------ Define a single option spec for the boolean help flag: diff --git a/sphinx_doc_src/cmds/fish_prompt.rst b/sphinx_doc_src/cmds/fish_prompt.rst index 6a8c7afde..285d87140 100644 --- a/sphinx_doc_src/cmds/fish_prompt.rst +++ b/sphinx_doc_src/cmds/fish_prompt.rst @@ -9,7 +9,8 @@ function fish_prompt end -\subsection fish_prompt-description Description +Description +------------ By defining the `fish_prompt` function, the user can choose a custom prompt. The `fish_prompt` function is executed when the prompt is to be shown, and the output is used as a prompt. @@ -18,7 +19,8 @@ The exit status of commands within `fish_prompt` will not modify the value of `and` or `or` in the condition. The exit status of the last foreground command to exit can always be accessed using the $status variable. -\subsection if-example Example +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`. diff --git a/sphinx_doc_src/cmds/isatty.rst b/sphinx_doc_src/cmds/isatty.rst index bf73f06c1..b421bc725 100644 --- a/sphinx_doc_src/cmds/isatty.rst +++ b/sphinx_doc_src/cmds/isatty.rst @@ -7,7 +7,8 @@ Synopsis isatty [FILE DESCRIPTOR] -\subsection isatty-description Description +Description +------------ `isatty` tests if a file descriptor is a tty. @@ -16,7 +17,8 @@ isatty [FILE DESCRIPTOR] If the specified file descriptor is a tty, the exit status of the command is zero. Otherwise, the exit status is non-zero. No messages are printed to standard error. -\subsection isatty-examples Examples +Examples +------------ From an interactive shell, the commands below exit with a return value of zero: diff --git a/sphinx_doc_src/cmds/jobs.rst b/sphinx_doc_src/cmds/jobs.rst index 2d17d9f92..0c0cd70f3 100644 --- a/sphinx_doc_src/cmds/jobs.rst +++ b/sphinx_doc_src/cmds/jobs.rst @@ -7,7 +7,8 @@ Synopsis jobs [OPTIONS] [PID] -\subsection jobs-description Description +Description +------------ `jobs` prints a list of the currently running jobs and their status. @@ -27,9 +28,11 @@ On systems that supports this feature, jobs will print the CPU usage of each job The exit code of the `jobs` builtin is `0` if there are running background jobs and `1` otherwise. -\subsection prints no output. +no output. +------------ -\subsection jobs-example Example +Example +------------ `jobs` outputs a summary of the current jobs. diff --git a/sphinx_doc_src/cmds/math.rst b/sphinx_doc_src/cmds/math.rst index b263746ae..86183cf8e 100644 --- a/sphinx_doc_src/cmds/math.rst +++ b/sphinx_doc_src/cmds/math.rst @@ -7,7 +7,8 @@ Synopsis math [-sN | --scale=N] [--] EXPRESSION -\subsection math-description Description +Description +------------ `math` is used to perform mathematical calculations. It supports all the usual operations such as addition, subtraction, etc. As well as functions like `abs()`, `sqrt()` and `log2()`. @@ -21,17 +22,20 @@ The following options are available: - `-sN` or `--scale=N` sets the scale of the result. `N` must be an integer. A scale of zero causes results 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 compatibility 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. -\subsection return-values Return Values +Return Values +------------ If the expression is successfully evaluated and doesn't over/underflow or return NaN the return `status` is zero (success) else one. -\subsection math-syntax Syntax +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`) is also available. -\subsection math-operators Operators +Operators +------------ `math` knows the following operators: @@ -47,7 +51,8 @@ For numbers, `.` is always the radix character regardless of locale - `2.5`, not They are all used in an infix manner - `5 + 2`, not `+ 5 2`. -\subsection math-constants Constants +Constants +------------ `math` knows the following constants: @@ -56,7 +61,8 @@ They are all used in an infix manner - `5 + 2`, not `+ 5 2`. Use them without a leading `$` - `pi - 3` should be about 0. -\subsection math-functions Functions +Functions +------------ `math` supports the following functions: @@ -85,7 +91,8 @@ Use them without a leading `$` - `pi - 3` should be about 0. All of the trigonometric functions use radians. -\subsection math-example Examples +Examples +------------ `math 1+1` outputs 2. @@ -99,7 +106,8 @@ All of the trigonometric functions use radians. `math "sin(pi)"` outputs `0`. -\subsection math-notes Compatibility notes +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. diff --git a/sphinx_doc_src/cmds/nextd.rst b/sphinx_doc_src/cmds/nextd.rst index 8ce5ce915..15f66726c 100644 --- a/sphinx_doc_src/cmds/nextd.rst +++ b/sphinx_doc_src/cmds/nextd.rst @@ -7,7 +7,8 @@ Synopsis nextd [ -l | --list ] [POS] -\subsection nextd-description Description +Description +------------ `nextd` moves forwards `POS` positions in the history of visited directories; if the end of the history has been hit, a warning is printed. @@ -17,7 +18,8 @@ Note that the `cd` command limits directory history to the 25 most recently visi You may be interested in the `cdh` command which provides a more intuitive way to navigate to recently visited directories. -\subsection nextd-example Example +Example +------------ \fish cd /usr/src diff --git a/sphinx_doc_src/cmds/not.rst b/sphinx_doc_src/cmds/not.rst index 7c572a251..73def4b37 100644 --- a/sphinx_doc_src/cmds/not.rst +++ b/sphinx_doc_src/cmds/not.rst @@ -7,12 +7,14 @@ Synopsis not COMMAND [OPTIONS...] -\subsection not-description Description +Description +------------ `not` negates the exit status of another command. If the exit status is zero, `not` returns 1. Otherwise, `not` returns 0. -\subsection not-example Example +Example +------------ The following code reports an error and exits if no file named spoon can be found. diff --git a/sphinx_doc_src/cmds/open.rst b/sphinx_doc_src/cmds/open.rst index 891d0589e..d093dc955 100644 --- a/sphinx_doc_src/cmds/open.rst +++ b/sphinx_doc_src/cmds/open.rst @@ -7,13 +7,15 @@ Synopsis open FILES... -\subsection open-description Description +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 exists (which is the case on macOS or Haiku). -\subsection open-example Example +Example +------------ `open *.txt` opens all the text files in the current directory using your system's default text editor. diff --git a/sphinx_doc_src/cmds/or.rst b/sphinx_doc_src/cmds/or.rst index 1d507668c..83c8dfe93 100644 --- a/sphinx_doc_src/cmds/or.rst +++ b/sphinx_doc_src/cmds/or.rst @@ -7,7 +7,8 @@ Synopsis COMMAND1; or COMMAND2 -\subsection or-description Description +Description +------------ `or` is used to execute a command if the previous command was not successful (returned a status of something other than 0). @@ -16,7 +17,8 @@ for `if` and `while` for examples. `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. -\subsection or-example Example +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. diff --git a/sphinx_doc_src/cmds/popd.rst b/sphinx_doc_src/cmds/popd.rst index bd3ab1be6..2ebdb2874 100644 --- a/sphinx_doc_src/cmds/popd.rst +++ b/sphinx_doc_src/cmds/popd.rst @@ -7,13 +7,15 @@ Synopsis popd -\subsection popd-description Description +Description +------------ `popd` removes the top directory from the directory stack and changes the working directory to the new top directory. Use `pushd` to add directories to the stack. You may be interested in the `cdh` command which provides a more intuitive way to navigate to recently visited directories. -\subsection popd-example Example +Example +------------ \fish pushd /usr/src diff --git a/sphinx_doc_src/cmds/prevd.rst b/sphinx_doc_src/cmds/prevd.rst index 224f994ab..50486a7dd 100644 --- a/sphinx_doc_src/cmds/prevd.rst +++ b/sphinx_doc_src/cmds/prevd.rst @@ -7,7 +7,8 @@ Synopsis prevd [ -l | --list ] [POS] -\subsection prevd-description Description +Description +------------ `prevd` moves backwards `POS` positions in the history of visited directories; if the beginning of the history has been hit, a warning is printed. @@ -17,7 +18,8 @@ Note that the `cd` command limits directory history to the 25 most recently visi You may be interested in the `cdh` command which provides a more intuitive way to navigate to recently visited directories. -\subsection prevd-example Example +Example +------------ \fish cd /usr/src diff --git a/sphinx_doc_src/cmds/printf.rst b/sphinx_doc_src/cmds/printf.rst index ab8aaa95d..dd27e690b 100644 --- a/sphinx_doc_src/cmds/printf.rst +++ b/sphinx_doc_src/cmds/printf.rst @@ -7,7 +7,8 @@ Synopsis printf format [argument...] -\subsection printf-description Description +Description +------------ printf formats the string FORMAT with ARGUMENT, and displays the result. The string FORMAT should contain format specifiers, each of which are replaced with successive arguments according to the specifier. Specifiers are detailed below, and are taken from the C library function `printf(3)`. @@ -59,7 +60,8 @@ The `format` argument is re-used as many times as necessary to convert all of th This file 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`. -\subsection printf-example Example +Example +------------ \fish printf '%s\\t%s\\n' flounder fish diff --git a/sphinx_doc_src/cmds/prompt_pwd.rst b/sphinx_doc_src/cmds/prompt_pwd.rst index 951daa7e5..58286b1cc 100644 --- a/sphinx_doc_src/cmds/prompt_pwd.rst +++ b/sphinx_doc_src/cmds/prompt_pwd.rst @@ -7,13 +7,15 @@ Synopsis prompt_pwd -\subsection prompt_pwd-description Description +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 character. 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. -\subsection prompt_pwd-example Examples +Examples +------------ \fish{cli-dark} >_ cd ~/ diff --git a/sphinx_doc_src/cmds/psub.rst b/sphinx_doc_src/cmds/psub.rst index 75060590f..d63689aea 100644 --- a/sphinx_doc_src/cmds/psub.rst +++ b/sphinx_doc_src/cmds/psub.rst @@ -7,7 +7,8 @@ Synopsis COMMAND1 ( COMMAND2 | psub [-F | --fifo] [-f | --file] [-s SUFFIX]) -\subsection psub-description Description +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 program. `psub` combined with a regular command substitution provides the same functionality. @@ -19,7 +20,8 @@ The following options are available: - `-s` or `--suffix` will append SUFFIX to the filename. -\subsection psub-example Example +Example +------------ \fish diff (sort a.txt | psub) (sort b.txt | psub) diff --git a/sphinx_doc_src/cmds/pushd.rst b/sphinx_doc_src/cmds/pushd.rst index 3d4a5a694..238765c65 100644 --- a/sphinx_doc_src/cmds/pushd.rst +++ b/sphinx_doc_src/cmds/pushd.rst @@ -7,7 +7,8 @@ Synopsis pushd [DIRECTORY] -\subsection pushd-description Description +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. @@ -21,7 +22,8 @@ See also `dirs` and `dirs -c`. You may be interested in the `cdh` command which provides a more intuitive way to navigate to recently visited directories. -\subsection pushd-example Example +Example +------------ \fish pushd /usr/src diff --git a/sphinx_doc_src/cmds/pwd.rst b/sphinx_doc_src/cmds/pwd.rst index da99d575b..4111c0685 100644 --- a/sphinx_doc_src/cmds/pwd.rst +++ b/sphinx_doc_src/cmds/pwd.rst @@ -7,7 +7,8 @@ Synopsis pwd -\subsection pwd-description Description +Description +------------ `pwd` outputs (prints) the current working directory. diff --git a/sphinx_doc_src/cmds/random.rst b/sphinx_doc_src/cmds/random.rst index 18df8b676..c073d23c9 100644 --- a/sphinx_doc_src/cmds/random.rst +++ b/sphinx_doc_src/cmds/random.rst @@ -11,7 +11,8 @@ random START STEP END random choice [ITEMS...] -\subsection random-description Description +Description +------------ `RANDOM` generates a pseudo-random integer from a uniform distribution. The range (inclusive) is dependent on the arguments passed. @@ -29,7 +30,8 @@ systems. You should not consider `RANDOM` cryptographically secure, or even statistically accurate. -\subsection random-example Example +Example +------------ The following code will count down from a random even number between 10 and 20 to 1: diff --git a/sphinx_doc_src/cmds/read.rst b/sphinx_doc_src/cmds/read.rst index d16c7223e..d7f69974c 100644 --- a/sphinx_doc_src/cmds/read.rst +++ b/sphinx_doc_src/cmds/read.rst @@ -7,7 +7,8 @@ Synopsis read [OPTIONS] [VARIABLE ...] -\subsection read-description Description +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. @@ -71,11 +72,13 @@ maximum of 10 MiB (1048576 bytes); if the terminator is not reached before this 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. -\subsection read-history Using another read history file +Using another read history file +------------ The `read` command supported the `-m` and `--mode-name` flags in fish versions prior to 2.7.0 to specify an alternative read history file. Those flags are now deprecated and ignored. Instead, set the `fish_history` variable to specify a history session ID. That will affect both the `read` history file and the fish command history file. You can set it to an empty string to specify that no history should be read or written. This is useful for presentations where you do not want possibly private or sensitive history to be exposed to the audience but do want history relevant to the presentation to be available. -\subsection read-example Example +Example +------------ The following code stores the value 'hello' in the shell variable `$foo`. diff --git a/sphinx_doc_src/cmds/realpath.rst b/sphinx_doc_src/cmds/realpath.rst index a34c42198..e3a5bce09 100644 --- a/sphinx_doc_src/cmds/realpath.rst +++ b/sphinx_doc_src/cmds/realpath.rst @@ -7,7 +7,8 @@ Synopsis realpath path -\subsection realpath-description Description +Description +------------ This is implemented as a function and a builtin. The function will attempt to use an external realpath command if one can be found. Otherwise it falls back to the builtin. The builtin does not support any options. It's meant to be used only by scripts which need to be portable. The builtin implementation behaves like GNU realpath when invoked without any options (which is the most common use case). In general scripts should not invoke the builtin directly. They should just use `realpath`. diff --git a/sphinx_doc_src/cmds/return.rst b/sphinx_doc_src/cmds/return.rst index c7b5ab432..f3141bce9 100644 --- a/sphinx_doc_src/cmds/return.rst +++ b/sphinx_doc_src/cmds/return.rst @@ -7,14 +7,16 @@ Synopsis function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end -\subsection return-description Description +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 statement 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. -\subsection return-example Example +Example +------------ The following code is an implementation of the false command as a fish function diff --git a/sphinx_doc_src/cmds/set.rst b/sphinx_doc_src/cmds/set.rst index ee0807a3e..1d2159d55 100644 --- a/sphinx_doc_src/cmds/set.rst +++ b/sphinx_doc_src/cmds/set.rst @@ -13,7 +13,8 @@ set ( -e | --erase ) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]... set ( -S | --show ) [SCOPE_OPTIONS] [VARIABLE_NAME]... -\subsection set-description Description +Description +------------ `set` manipulates shell variables. @@ -82,7 +83,8 @@ In erase mode, if variable indices are specified, only the specified slices of t In assignment mode, `set` does not modify the exit status. This allows simultaneous capture of the output and exit status of a subcommand, e.g. `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 the variable was write-protected or if the variable did not exist. -\subsection set-examples Examples +Examples +------------ \fish # Prints all global, exported variables. set -xg @@ -109,7 +111,8 @@ if set python_path (type -p python) end \endfish -\subsection set-notes Notes +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. diff --git a/sphinx_doc_src/cmds/set_color.rst b/sphinx_doc_src/cmds/set_color.rst index 84eb1d5b2..bae06ddfe 100644 --- a/sphinx_doc_src/cmds/set_color.rst +++ b/sphinx_doc_src/cmds/set_color.rst @@ -7,7 +7,8 @@ Synopsis set_color [OPTIONS] VALUE -\subsection set_color-description Description +Description +------------ `set_color` is used to control the color and styling of text in the terminal. `VALUE` corresponds to a reserved color name such as *red* or a RGB color value given as 3 or 6 hexadecimal digits. 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. A special keyword *normal* resets text formatting to terminal defaults. @@ -30,14 +31,16 @@ The following options are available: Using the *normal* keyword will reset foreground, background, and all formatting back to default. -\subsection set_color-notes Notes +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 characters. Fish provides no way to set the background color for the entire terminal window. Configuring the window background color (and other attributes such as its opacity) has to be done using whatever mechanisms the terminal provides. 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 code of `isatty stdout` before using `set_color` can be useful to decide not to colorize output in a script. -\subsection set_color-example Examples +Examples +------------ \fish set_color red; echo "Roses are red" @@ -46,7 +49,8 @@ set_color 62A; echo "Eggplants are dark purple" set_color normal; echo "Normal is nice" # Resets the background too \endfish -\subsection set_color-detection Terminal Capability Detection +Terminal Capability Detection +------------ Fish uses a heuristic to decide if a terminal supports the 256-color palette as opposed to the more limited 16 color palette of older terminals. Support can be forced on by setting `fish_term256` to *1*. If `$TERM` contains "256color" (e.g., *xterm-256color*), 256-color support is enabled. If `$TERM` contains *xterm*, 256 color support is enabled (except for MacOS: `$TERM_PROGRAM` and `$TERM_PROGRAM_VERSION` are used to detect Terminal.app from MacOS 10.6; support is disabled here it because it is known that it reports `xterm` and only supports 16 colors. diff --git a/sphinx_doc_src/cmds/source.rst b/sphinx_doc_src/cmds/source.rst index e23fbda25..6d72bf2fb 100644 --- a/sphinx_doc_src/cmds/source.rst +++ b/sphinx_doc_src/cmds/source.rst @@ -8,7 +8,8 @@ source FILENAME [ARGUMENTS...] somecommand | source -\subsection source-description Description +Description +------------ `source` evaluates the commands of the specified file in the current shell. This is different from starting a new process to perform the commands (i.e. `fish < FILENAME`) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments 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. @@ -19,7 +20,8 @@ The return status of `source` is the return status of the last job to execute. I `.` (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 version of fish. -\subsection source-example Example +Example +------------ \fish source ~/.config/fish/config.fish diff --git a/sphinx_doc_src/cmds/status.rst b/sphinx_doc_src/cmds/status.rst index 8832855d1..aa1422f9f 100644 --- a/sphinx_doc_src/cmds/status.rst +++ b/sphinx_doc_src/cmds/status.rst @@ -23,7 +23,8 @@ status features status test-feature FEATURE -\subsection status-description Description +Description +------------ With no arguments, `status` displays a summary of the current login and job control status of the shell. @@ -62,7 +63,8 @@ The following operations (sub-commands) are available: - `test-feature FEATURE` returns 0 when FEATURE is enabled, 1 if it is disabled, and 2 if it is not recognized. -\subsection status-notes Notes +Notes +------------ For backwards compatibility each subcommand 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 removed in a future release (but not before fish 3.0). diff --git a/sphinx_doc_src/cmds/string.rst b/sphinx_doc_src/cmds/string.rst index e54784332..2149dc4d4 100644 --- a/sphinx_doc_src/cmds/string.rst +++ b/sphinx_doc_src/cmds/string.rst @@ -28,7 +28,8 @@ string upper [(-q | --quiet)] [STRING...] -\subsection string-description Description +Description +------------ `string` performs operations on strings. @@ -40,7 +41,8 @@ Most subcommands accept a `-q` or `--quiet` switch, which suppresses the usual o The following subcommands are available. -\subsection string-escape "escape" subcommand +"escape" subcommand +------------ `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. @@ -52,7 +54,8 @@ The following subcommands are available. `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 unescaping pcre2. -\subsection string-join "join" subcommand +"join" subcommand +------------ `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. @@ -60,15 +63,18 @@ The following subcommands are available. `string join` 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. -\subsection string-length "length" subcommand +"length" subcommand +------------ `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 otherwise. -\subsection string-lower "lower" subcommand +"lower" subcommand +------------ `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. -\subsection string-match "match" subcommand +"match" subcommand +------------ `string match` tests each STRING against PATTERN and prints matching substrings. Only the first match for each STRING is reported unless `-a` or `--all` is given, in which case all matches are reported. @@ -84,11 +90,13 @@ If `--invert` or `-v` is used the selected lines will be only those which do not Exit status: 0 if at least one match was found, or 1 otherwise. -\subsection string-repeat "repeat" subcommand +"repeat" subcommand +------------ `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. -\subsection string-replace "replace" subcommand +"replace" subcommand +------------ `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. @@ -98,7 +106,8 @@ If you specify the `-f` or `--filter` flag then each input string is printed onl Exit status: 0 if at least one replacement was performed, or 1 otherwise. -\subsection string-split "split" subcommand +"split" subcommand +------------ `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. @@ -110,19 +119,23 @@ See also `read --delimiter`. `split0` has the important property that its output is not further split when used in a command substitution, allowing for the command substitution 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. -\subsection string-sub "sub" subcommand +"sub" subcommand +------------ `string sub` prints a substring of each string argument. The start of the substring can be specified with `-s` or `--start` 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 is not specified, the substring continues to the end of each STRING. Exit status: 0 if at least one substring operation was performed, 1 otherwise. -\subsection string-trim "trim" subcommand +"trim" subcommand +------------ `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. -\subsection string-upper "upper" subcommand +"upper" subcommand +------------ `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. -\subsection regular-expressions Regular Expressions +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. @@ -172,7 +185,8 @@ And some other things: - `^` is the start of the string or line, `$` the end. - `|` is "alternation", i.e. the "or". -\subsection string-example Examples +Examples +------------ \fish{cli-dark} >_ string length 'hello, world' @@ -234,7 +248,8 @@ And some other things: a1_20b2__c_E6_85_A1 \endfish -\subsection string-example-match-glob Match Glob Examples +Match Glob Examples +------------ \fish{cli-dark} >_ string match '?' a @@ -266,7 +281,8 @@ foo2 \endfish -\subsection string-example-match-regex Match Regex Examples +Match Regex Examples +------------ \fish{cli-dark} >_ string match -r 'cat|dog|fish' 'nice dog' @@ -315,7 +331,8 @@ foo2 alpha\\ngamma \endfish -\subsection string-example-replace-literal Replace Literal Examples +Replace Literal Examples +------------ \fish{cli-dark} >_ string replace is was 'blue is my favorite' @@ -330,7 +347,8 @@ foo2 spaces_to_underscores \endfish -\subsection string-example-replace-Regex Replace Regex Examples +Replace Regex Examples +------------ \fish{cli-dark} >_ string replace -r -a '[^\\d.]+' ' ' '0 one two 3.14 four 5x' @@ -344,7 +362,8 @@ foo2 here \endfish -\subsection string-example-repeat Repeat Examples +Repeat Examples +------------ \fish{cli-dark} >_ string repeat -n 2 'foo ' diff --git a/sphinx_doc_src/cmds/suspend.rst b/sphinx_doc_src/cmds/suspend.rst index ef5932f3e..e0b3036b2 100644 --- a/sphinx_doc_src/cmds/suspend.rst +++ b/sphinx_doc_src/cmds/suspend.rst @@ -7,7 +7,8 @@ Synopsis suspend [--force] -\subsection suspend-description Description +Description +------------ `suspend` suspends execution of the current shell by sending it a SIGTSTP signal, returning to the controlling process. It can be diff --git a/sphinx_doc_src/cmds/switch.rst b/sphinx_doc_src/cmds/switch.rst index 7f16550ee..821db0456 100644 --- a/sphinx_doc_src/cmds/switch.rst +++ b/sphinx_doc_src/cmds/switch.rst @@ -7,7 +7,8 @@ Synopsis switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end -\subsection switch-description Description +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. @@ -18,7 +19,8 @@ Note that fish does not fall through on case statements. Only the first matching 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. -\subsection switch-example Example +Example +------------ If the variable \$animal contains the name of an animal, the following code would attempt to classify it: diff --git a/sphinx_doc_src/cmds/test.rst b/sphinx_doc_src/cmds/test.rst index dbe8d07d4..b5e308e3f 100644 --- a/sphinx_doc_src/cmds/test.rst +++ b/sphinx_doc_src/cmds/test.rst @@ -8,7 +8,8 @@ test [EXPRESSION] [ [EXPRESSION] ] -\subsection test-description Description +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. @@ -18,7 +19,8 @@ This test is mostly POSIX-compatible. When using a variable as an argument for a test operator you should almost 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 enclose it in double-quotes. For example, `test "$x" = "$y"`. Since it is always safe to enclose variables in double-quotes when used as `test` arguments that is the recommended practice. -\subsection test-files Operators for files and directories +Operators for files and directories +------------ - `-b FILE` returns true if `FILE` is a block device. @@ -56,7 +58,8 @@ When using a variable as an argument for a test operator you should almost alway - `-x FILE` returns true if `FILE` is marked as executable. -\subsection test-strings Operators for text strings +Operators for text strings +------------ - `STRING1 = STRING2` returns true if the strings `STRING1` and `STRING2` are identical. @@ -66,7 +69,8 @@ When using a variable as an argument for a test operator you should almost alway - `-z STRING` returns true if the length of `STRING` is zero. -\subsection test-numbers Operators to compare and examine numbers +Operators to compare and examine numbers +------------ - `NUM1 -eq NUM2` returns true if `NUM1` and `NUM2` are numerically equal. @@ -82,7 +86,8 @@ When using a variable as an argument for a test operator you should almost alway Both integers and floating point numbers are supported. -\subsection test-combinators Operators to combine expressions +Operators to combine expressions +------------ - `COND1 -a COND2` returns true if both `COND1` and `COND2` are true. @@ -99,7 +104,8 @@ Expressions can be grouped using parentheses. Note that parentheses will usually require escaping with `\(` to avoid being interpreted as a command substitution. -\subsection test-example Examples +Examples +------------ If the `/tmp` directory exists, copy the `/etc/motd` file to it: @@ -157,7 +163,8 @@ if test $status -ne 0 end \endfish -\subsection test-standards Standards +Standards +------------ `test` implements a subset of the IEEE Std 1003.1-2008 (POSIX.1) standard. The following exceptions apply: diff --git a/sphinx_doc_src/cmds/trap.rst b/sphinx_doc_src/cmds/trap.rst index a1e12bcbd..b02aa10fb 100644 --- a/sphinx_doc_src/cmds/trap.rst +++ b/sphinx_doc_src/cmds/trap.rst @@ -7,7 +7,8 @@ Synopsis trap [OPTIONS] [[ARG] REASON ... ] -\subsection trap-description Description +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. @@ -31,7 +32,8 @@ Signal names are case insensitive and the `SIG` prefix is optional. The return status is 1 if any `REASON` is invalid; otherwise trap returns 0. -\subsection trap-example Example +Example +------------ \fish trap "status --print-stack-trace" SIGUSR1 diff --git a/sphinx_doc_src/cmds/true.rst b/sphinx_doc_src/cmds/true.rst index 2e986de4c..5b30b362f 100644 --- a/sphinx_doc_src/cmds/true.rst +++ b/sphinx_doc_src/cmds/true.rst @@ -7,6 +7,7 @@ Synopsis true -\subsection true-description Description +Description +------------ `true` sets the exit status to 0. diff --git a/sphinx_doc_src/cmds/type.rst b/sphinx_doc_src/cmds/type.rst index 26df7876a..6c4a6a6bd 100644 --- a/sphinx_doc_src/cmds/type.rst +++ b/sphinx_doc_src/cmds/type.rst @@ -7,7 +7,8 @@ Synopsis type [OPTIONS] NAME [NAME ...] -\subsection type-description Description +Description +------------ With no options, `type` indicates how each `NAME` would be interpreted if used as a command name. @@ -28,7 +29,8 @@ The following options are available: The `-q`, `-p`, `-t` and `-P` flags (and their long flag aliases) are mutually exclusive. Only one can be specified at a time. -\subsection type-example Example +Example +------------ \fish{cli-dark} >_ type fg diff --git a/sphinx_doc_src/cmds/ulimit.rst b/sphinx_doc_src/cmds/ulimit.rst index 7b6b60317..86e679546 100644 --- a/sphinx_doc_src/cmds/ulimit.rst +++ b/sphinx_doc_src/cmds/ulimit.rst @@ -7,7 +7,8 @@ Synopsis ulimit [OPTIONS] [LIMIT] -\subsection ulimit-description Description +Description +------------ `ulimit` builtin 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. @@ -60,7 +61,8 @@ The `fish` implementation of `ulimit` should behave identically to the implement - Fish `ulimit` does not support getting or setting multiple limits in one command, except reporting all values using the -a switch -\subsection ulimit-example Example +Example +------------ `ulimit -Hs 64` sets the hard stack size limit to 64 kB. diff --git a/sphinx_doc_src/cmds/umask.rst b/sphinx_doc_src/cmds/umask.rst index f884fb69f..a615961b1 100644 --- a/sphinx_doc_src/cmds/umask.rst +++ b/sphinx_doc_src/cmds/umask.rst @@ -7,7 +7,8 @@ Synopsis umask [OPTIONS] [MASK] -\subsection umask-description Description +Description +------------ `umask` displays and manipulates the "umask", or file creation mode mask, which is used to restrict the default access to files. @@ -38,6 +39,7 @@ If the first and second parts are skipped, they are assumed to be `a` and `=`, r Note that symbolic masks currently do not work as intended. -\subsection umask-example Example +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. diff --git a/sphinx_doc_src/cmds/vared.rst b/sphinx_doc_src/cmds/vared.rst index d37e1af0f..c8f43db08 100644 --- a/sphinx_doc_src/cmds/vared.rst +++ b/sphinx_doc_src/cmds/vared.rst @@ -7,11 +7,13 @@ Synopsis vared VARIABLE_NAME -\subsection vared-description Description +Description +------------ `vared` is used to interactively edit the value of an environment variable. Array variables as a whole can not be edited using `vared`, but individual array elements can. -\subsection vared-example Example +Example +------------ `vared PATH[3]` edits the third element of the PATH array diff --git a/sphinx_doc_src/cmds/wait.rst b/sphinx_doc_src/cmds/wait.rst index 08ae375e7..c40d45b44 100644 --- a/sphinx_doc_src/cmds/wait.rst +++ b/sphinx_doc_src/cmds/wait.rst @@ -7,7 +7,8 @@ Synopsis wait [-n | --any] [PID | PROCESS_NAME] ... -\subsection wait-description Description +Description +------------ `wait` waits for child jobs to complete. @@ -16,7 +17,8 @@ wait [-n | --any] [PID | PROCESS_NAME] ... - If neither a pid nor a process name is specified, the command waits for all background jobs. - 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. -\subsection wait-example Example +Example +------------ \fish sleep 10 & diff --git a/sphinx_doc_src/cmds/while.rst b/sphinx_doc_src/cmds/while.rst index 20cf3281b..ba8e7fd2b 100644 --- a/sphinx_doc_src/cmds/while.rst +++ b/sphinx_doc_src/cmds/while.rst @@ -7,7 +7,8 @@ Synopsis while CONDITION; COMMANDS...; end -\subsection while-description Description +Description +------------ `while` repeatedly executes `CONDITION`, and if the exit status is 0, then executes `COMMANDS`. @@ -18,7 +19,8 @@ The exit status of the loop is 0 otherwise. You can use `and` or `or` for complex conditions. Even more complex control can be achieved with `while true` containing a break. -\subsection while-example Example +Example +------------ \fish while test -f foo.txt; or test -f bar.txt ; echo file exists; sleep 10; end