When performing wildcard expansion with a literal path segment,
instead of enumerating the files in the directory, simply apply the
path segment as if we found the directory and continue on. This
enables us to expand strings that contain unreadable directory
components (common with $HOME) and also improves performance, since
we don't waste time enumerating directories unnecessarily. Adds
a test too.
Fixes#2099
1. When run with no arguments, make abbr do the equivalent
of `abbr --show`
2. Enable "implicit add", e.g. `abbr gco git checkout`
3. Teach `abbr --show` to not use quotes for simple cases
4. Teach abbr to output -- when the abbreviation has
leading dashes
Add some basic tests to abbr too.
Add a new function fish_mode_prompt which (if it is defined) has its output
prepended to the left prompt. Rather than replacing the prompt wholesale, make
fish_vi_mode enable this function by setting a variable __fish_vi_mode. This
enables vi mode to interoperate nicely with custom prompts. Users who want
to change how the mode is reported can either redefine this function or
erase it entirely. Fixes#1988.
Prior to this fix, if you exported a variable in one scope
and then unexported it in the next, it would remain exported.
Example:
set -gx VAR 1
function foo; set -l VAR; env; end
foo
Here 'VAR' would be exported to 'env' because we failed to
notice that the env var is shadowed by an unexported variable.
This occurred at env var computation time, not in env_set!
Fixes#2132
su does not reset XDG_RUNTIME_DIR, which means that XDG_RUNTIME_DIR
may point to directories that the user does not have permission
to access. Similarly there is no guarantee that XDG_RUNTIME_DIR
points to a directory that actually exists. Rather than try to
handle these issues, we simply ignore them, effectively disabling
realtime uvar notifications. Fixes#1955.
In FAQ:
> I'm seeing weird output before each prompt when using screen. What's wrong?
The command provided is
echo 'function fish_title;end' > ~/.config/fish/config.fish
Using `>` will overwrite current config.fish.
We should use `>>` instead.
With the fix for #365, fish_command_not_found event handlers
receive the command and all of its arguments. But commands
like /usr/lib/command-not-found expect only the command name.
So when invoking an external command, just pass the command
name, not all of the arguments.
Before running a command, we add the command to history, so
that if the command causes us to exit it's still captured in
history. But that command should not be considered part of
history when expanding the history within the command itself.
For example, `echo $history[1]` should be the previously
run command, not `echo $history[1]` itself.
Fixes#2028
For the case
```
bind \et "commandline -i 1" "commandline -i 2"
```
the order of execution of the commands is now in-order.
Note that functions codes are prepended to the queue in reverse order, so they
will be executed in-order. This should allow all bindings of the form
```
bind \et beginning-of-line force-repaint
```
to remain unchanged.
Using builtin `commandline -f`, one would expect to have commands executed in
the order that they were given. This motivates the change to a queue.
Unfortunately, fish internals still need lookahead_list to act as a stack. Add
and rename functions to support both cases and have lookahead_list as
a std::deque internally.
This code is delicate, and we should probably dog-food this in nightly for
a while before the next-minor release.
Fixes#1567
Examples that work as expected (even completions don't get confused):
$ begin true; end;
$ begin if true; end; end
$ begin if true; echo hi; end
The last example correctly expects another 'end' to match 'begin'.
Fixes#1248.
Do not tombstone a function when it is evicted normally from the LRU cache.
This broke changing `fish_function_path`, since that would evict all nodes,
resulting in accidental tombstones, which caused autoloaded functions to
never be reloaded.
See #213.
In 73f344f41b, we allowed autoloaded functions to be deleted.
For some reason, funcsave immediately deletes the function it
creates. This previously did very little, since the function would
immediately be re-autoloaded, but with the fix for 73f344f41b
the function gets tombstoned. So the effect is that funcsave
makes the function disappear! This simply removes the erase call,
which dates back to fish 1.x.
As suggested by @ridiculousfish, when removing autoloaded functions, add them
to a tombstones set. These functions will never be autoloaded again in the
current shell, not even when the timestamp changes.
Tested as per comment 1 of #1033. `~/.config/fish/functions/ls.fish` contains
the function definition. `function -e ls` removes the redefined `ls` (and
reverts back to the built-in command). `touch .../ls.fish` does not cause the
function to be reloaded.
Works also if tok->show_comments (for highlighting and auto completion) and
with multi-line comments:
function my_function
echo "hello" | \
#remove 'l'
#and more
tr -d 'l'
end
$ my_function
heo
Fixes#983
It seems that `ul` can't handle the escape sequences for bold text that `nroff` generates on my system. Fixed by either removing `| ul`, or adding `-c` to the `nroff` command.
Needs testing for old (OSX?) versions of nroff.
Fixes a bug where generating a lot of autoloaded functions from
syntax highlighting would result in evicting nodes on background threads,
resulting in a thread error.
Fixes#1989
Unfortunately, list-unit-files doesn't understand --state=loaded
This needs a new function to explicitly use list-units
This reverts commit 9f521b7694.
e340baf6cc introduced a bug where fish would not exit from job_continue
when receiving a signal like SIGHUP. This means that it would not in turn
deliver SIGHUP to its children, who would therefore never exit. Those
children may attempt to write to stdout, in which case they would receive
EIO; this can cause other weird issues, like telnet using 100% CPU.
Fixes#1958
Valid uses of this environment variable don't really include passing
it to subsequent child processes.
I confirmed the fix with:
function fish_prompt
echo "cmd duration [$CMD_DURATION] "
end
cmd duration [0] sleep 2
cmd duration [2002]
Prior to b0e09303a, simple jobs like `printf "%s\n" $line | read word _`
never hit the call to select() because they were reaped in the SIGCHLD
signal handler. With that commit, the signal handler no longer reaps
children, and a job like that would enter select() and hit the 10000μs
timeout before discovering that the job was already complete.
Fixes#1884.
Remove global array of file descriptors, in
favor of relying on CLO_EXEC exclusively.
Also correctly implement "pipe avoidance" so
that fd redirections do not conflict
with pipes.
- Rename 'events' to 's_event_handlers'
- Stop inspecting the s_event_handlers list upon receiving
a signal. Instead, maintain the set of signals that are observed
in a separate static array. This lets us avoid mucking with
STL data structures in a signal handler, and so avoid blocking signals
in event.cpp
GNU and BSD `mktemp` handle options differently, and it's a useful
utility for tests. As such, define a common `mktemp` function wrapper
for the test suite.
It might actually be nice to expand this for more flags and support it
globally, but that may result in confusion for any users of BSD mktemp
that expect to be running /bin/mktemp.
Update the test runners so they set up their own environment in
test_util.fish. This simplifies the Makefile and paves the way for
adding utility functions for use in the tests themselves.
Support for space-delimited abbreviations was added to the expansion
parser in fbade198; this commit extends that support to the user-facing
tools, and documents the space-separated behaviour. Equals-delimited
abbreviations are expected to be removed before the next release.
Work on #731.
This prevents cases like `cd /usr/e` from tab-completing to
`cd /usr/` (which is the shared prefix of the tab completions).
Things are still sort of confusing with fuzzy matching, e.g.
with files like this:
foo1bar
foo2bar
Then ba<tab> will replace the token with foo. That's surprising,
but not new to this fix.
Fixes#1727
There is no CTRL-C handler for the default mode in the vi bindings. This makes it difficult to say "never mind" and start a new command line like you can do in bash's vi mode.
There were CTRL-C handlers for insert and visual modes that go back to default mode, but nothing happens in default mode. I copy-pasted the CTRL-C handler from the default key bindings file.
The PROCESS_EXIT event takes 3 args: event name, pid, status. However,
when fish is exiting, the PROCESS_EXIT is instead given the status of
whether the last commandline parsed successfully. Change it to use the
same value that fish itself is going to exit with.
When calculating the version, we don't need to test for the presence of
.git before running `git describe`. This lets us work properly in a
detached work tree if GIT_DIR is set.
(Ideally, the behaviour of git could be implemented: pipe the input
through a pager iff the length is > window size and in interactive
mode).
Closes#1076.
Work on #1073.
fish is not exclusively distributed under the GPL version 2; the
canonical reference is doc_src/license.hdr, so use that as the full
description.
[skip ci]
Prior to this fix, a child process may be reaped in one of two ways:
1. By a call to waitpid() within job_continue
2. By a call to waitpid() within the SIGCHLD signal handler
Only the second call was with the WNOHANG option. Thus if the signal
handler fired first, and then the waitpid call fired, we could get a
deadlock because we'd end up waiting on a long-running process. I have
not been able to reproduce this on fish 1.x, though it seems like it
ought to reproduce there too.
This fix migrates the waitpid() call out of the signal handler; the
second class of calls moves to job_reap. This eliminates the possibility
of a race, because we check for job completion before calling waitpid,
and there is no longer the possibility of the job being marked as
complete asynchronously. It also results in a massive conceptual
simplification, since the signal handler is now very simple and easy to
reason about (no more walking jobs lists, etc).
This partially fixes a bug reported in #1273
Wildcard errors are only reported interactively, and they're also not
really errors. Commands with multiple wildcards would in fact continue
executing if at least one wildcard matched, which is quite surprising.
But they would report an error if there is only one wildcard in the
arguments list and the wildcard has no match, even if there are other
remaining arguments.
Given this inconsistency, and given that sh does not stop execution if a
wildcard fails to match, it seems better to allow execution to continue.
This is better from a scripting perspective anyway, as it means
constructs like `set -l paths foo/*.txt` will actually create the
variable (with an empty value) instead of skipping the `set`
altogether and perhaps causing subsequent code to read or modify a
global or universal variable.
Wildcard errors are only supposed to reported when encountered during
interactive use. The old parser also suppressed them if `is_block` was
true. This was lost in the new parser. However, this also suppresses
errors generated from `begin; code_here; end` and other block
constructs.
Instead, check the parser block stack when we hit an error, and suppress
the error if there are any function calls / events / source invocations.
These all indicate that the code being executed came from somewhere
other than the commandline.
Unmatched wildcard errors during parsing are normally only reported when
run interactively. The switch command was unconditionally reporting them
anyway (and not setting the status to 124). Fix it so switch goes
through the same code path as everything else.
Prior to this change, inherited environment variables
would be split on colons, becoming an array. This change
eliminates that behavior. Now environment variables are
always split on the record separator character (ASCII 0x1e),
with the exception of a short whitelist of PATH, MANPATH,
CDPATH. Likewise, exported variables are also exported
delimited by rs, with the exception of the above whitelist.
Fixes#1374, also see #1656
The terminal width magic that __fish_print_help learned doesn't help
when builtin_print_help runs it in a subshell. Instead, add an
undocumented --tty-width flag to __fish_print_help that's used to pass
the terminal width.
As a result of this rewrite, the output now:
* Expands to fit the terminal width, like `man` does
* Preprocesses the manpage with `tbl` just in case, since `man` does
this, even though I doubt any fish manpages use `tbl` formatting.
* Handle bold/underline with the `ul` command as it was designed for
instead of trying to fake it with `sed`.
* Compresses blank lines as `man` does with the default `less -is`
pager.
We can't use $PATHS to test the :-splitting because the global config
file adds extra paths based on /etc/paths and /etc/paths.d.
Ideally fish would have a way to suppress behavior like that, but for
the time being it doesn't.
The usage is still the same, but it's a lot more robust, and also no
longer assumes $fish_user_abbreviations must be a universal variable.
This also fixes the unexpected error output when calling `abbr -a` with
no existing abbreviations.
Calling `abbr -a` with an abbreviation that already exists now silently
overwrites the abbreviation, just like `function` and `bind` do, instead
of complaining.
Re-running ./configure will cause fish.pc to rebuild, in case any of the
paths changed. It looks like this actually won't rebuild the rest of
fish, but figuring out how to handle that is out of scope for this
commit.
More importantly, this will rebuild fish.pc when the version string
changes.
This fixes the issue with nonexistant directories (some Linux
distributions put these for local modules), and also fixes the
issue of dot meaning any character instead of simply dot.
--inherit-variable takes a variable name and snapshots its current
value. When the function is executed, it will have a local variable with
this value already defined. Printing the function source will include
synthesized `set -l` lines for the values.
This is primarily useful for functions that are created on the fly, such
as in `psub`.
ENV_USER is intended to be used when setting any variable whose name is
controlled by the user. The names given to `function -a` certainly
qualifies. This wasn't an issue in practice because the only restriction
ENV_USER imposes is also imposed on ENV_LOCAL, but the rules may change
in the future.
# The first commit's message is:
Simplify default fish_prompt
No need for the set_color caching now that it's a builtin.
Also simplify the 3 classic prompts in fish_config's sample_prompts set.
Remove comment that AFAICT is not true anymore.
Ensure someone setting __fish_active_key_bindings as a universal
variable doesn't screw up the initial keybinding load.
env.cpp sets up $HOME based on the current user, if it's not inherited
from the environment. fishd_get_config should be using the same
calculated value of $HOME. To that end, move universal variable
initialization to after $HOME is set up, and read the value from the
fish environment instead of using getenv().
Fixes#1725.
If $HOME is unset in the environment, fish calculates it with
getpwnam(). However, it wasn't being exported. Just like the $USER
calculation, $HOME should probably be exported, because everyone will
assume that it's an environment variable (as opposed to an unexported
global variable).
Assists other packages in finding the path to install completions: call
`pkg-config --variable=completionsdir fish` or so (like
bash-completion).
As discussed in #1485.
Instead of globally marking the state as "in block" when evaluating
blocks/functions, update the "in block" status when pushing/popping
blocks on the parser stack.
Fixes#1729.
On a side note, `status -b` is actually pretty useless, because it
always returns 0 inside of a function (even without this patch).
Making `true` into a builtin is a significant optimization to `while
true` loops. As long as `true` is a builtin, we may as well make `false`
builtin as well (despite the fact that it's not typically executed in a
loop).
This makes two changes to parse trees:
1. Unmaterialized nodes no longer have an invalid source location
For example, with the code `while false;end` there are no tokens
associated with the while loop's job_list, and therefore it is
unmaterialized. Previously it would have had a SOURCE_OFFSET_INVALID.
But now it has a zero source length, but an offset equal to the end of
the while loop (i.e. the semicolon), and a zero length. Correspondingly,
the has_source function now checks the length instead of the offset.
2. Special (comment and error) nodes have always been "disconnected,"
meaning they are not the child of any other node. However, they now have
their parent offsets set to whatever the top of the node stack was when
the node was encountered. This gives us a sense of which node the
comment is "in", e.g. if we are constructing a job list then the
comment's parent will be the job list. This lets us determine the
comment's indent.
All opam subcommands and descriptions are covered, along with
all the flags that are common to all commands. However, only
`opam config` has complete subsubcommand coverage.
Apparently, in zsh, Meta+H can be used to display the manpage for
the current command. This commit adds this zsh feature to fish shell.
The F1 keybinding is left, although it's now secondary according to
fish help, as some terminal emulators don't let the user press F1 key.
my_wcswidth() was just a wrapper around fish_wcswidth() already.
Instead, add two convenience overrides of fish_wcswidth() to common.h
that make it a drop-in replacement for my_wcswidth().
If a wildcard or completion expands to a file that begins with
one or more dashes, prepend a ./ to it so that it doesn't get
parsed as an option.
Fixes#1519
history_lru_node_t has implicit destructor defined. However, because
it's being deleted as lru_node_t, it's not being actually called, as
lru_node_t doesn't have a virtual destructor.
It seems expect prioritizes the first pattern in the list, instead of
the pattern that matches earliest in the buffer. That seems pretty
stupid, but let's try moving the prompt pattern to the end and see if
that fixes the Travis failures.
Also tweak colored output to reset before the newline instead of after,
so travis behaves better (for some reason reset causes travis to display
the line in black).
Split test_interactive off from test_fishscript and add a new target
test_high_level that tests both.
Add some Makefile magic so the tests can be run serially without using
sub-make, which gets rid of a little noise from the make output.
Rewrite interactive tests to look better.
re: fish-shell/fish-shell@2726712e01
As this is rendering ok in Firefox, this version should pickup the best
fonts for most browser/os variants based on 'font-stretch' support.
`.fish_left_bar` should be condensed, the main body font shouldn't.
Binds with the same sequence in multiple modes was not working right.
Fix up the implementation to propagate modes everywhere as necessary.
This means that `bind` will properly list distinct binds with the same
sequence, and `bind -e` will take mode into account properly as well.
Note that `bind -e seq` now assumes the bind is in the default bind
mode, whereas before it would erase the first binding with that sequence
regardless of mode.
`bind -e -a` still erases all binds in all modes, though `bind -M mode
-e -a` still only erases all binds in the selected mode.
<em> used to represent something else, but as far as I can tell, all
uses of <em> in the documentation today actually represent text that's
supposed to be visibly different. Notably, the documentation on
supported escapes uses <em> to indicate the letters that are a
placeholder for e.g. a hex digit, as opposed to being a literal
character.
U+F8FF is the last character in the private use area, but it's also the
codepoint used for the Apple symbol (), which is typeable on US
keyboards in OS X, and so should actually work.
Use the new `read -z` flag to complete git aliases better. This approach
won't break if an alias contains a newline.
Also fix stash completion, which was broken on BSD sed.
The `--null` flag to `read` makes it split incoming lines on NUL instead
of newlines. This is intended for processing the output of a command
that uses NUL separators (such as `find -print0`).
Fixes#1694.
This font, at least under Kubuntu 14.04 and Firefox I use is rather
ugly. Anti-aliasing is wrong, and the spaces between letters are
rather random. It makes reading the documentation headings and table
of contents harder than it needs to be.
Those issues don't happen with DejaVu Sans.
Directories are completed like commands, because of implicit cd.
However, directories found inside $PATH entries should not be completed,
as implicit cd doesn't work there. Similarly, directories should not be
completed after the `command` builtin.
Fixes#1695.
`exec` removes fish from the shell "stack", so SHLVL needs to be
decremented to match. This means `exec fish` will result in the same
SHLVL in the new fish instance.
Also tweak the SHLVL logic to interpret an environment SHLVL of "3foo"
as garbage instead of as the value "3".
Fixes#1693.
The wrong lock was being taken around the result queue, leading to the
occasional crash when processing interactive input. This didn't seem to
really affect normal day-to-day usage, but it did sometimes cause the
interactive tests to crash.
Fixes#1692.
As far as I know we can't access the build artifacts from Travis, so we
can't check the interactive logs after a test failure. Add an
environment variable that causes the test runner to dump the logs
itself, and set that variable for Travis.
Split `make test` into two targets `make test_low_level` and `make
test_fishscript`, primarily so fishscript tests can be rechecked quickly
after edits.
Reformat the test.fish file and update some of the code to be a little
more straightforward (e.g. `if not cmd` instead of `if cmd; else`).
This includes:
- Fixing some typos and misspellings
- Being consistent with pronouns (she/he)
- Hyphenating "built-in" and "command-line" where appropriate
Widened 'Commands' menu + fish logo
fish logo added to FAQ menu
'Commands' menu content aligned with Docs menu
'FAQ' menu content aligned and made 1st order as all entires are long
and wrap.
Setting a non-existant path component to PATH logs an error to stderr.
This is not appropriate for non-interactive temporary modifications,
like the one done by the `sudo` completion helper function.
Major documentation cleanup and update.
- Fixes Issue #1557
- Moves entire documentation to Markdown format. Much simpler.
- Fully supports Doxygen 1.8.7+
- All documentation targets updated: user_doc, share/man, doc and
doc/refman.pdf.
- Tested across Ubuntu, CentOS and Mac OS.
See doc_src/FORMATTING.md for in depth rationale and style guide.
Doxygen 1.8.6 and lower do not have the \\htmlonly[block] directive
which fixes a multitude of problems in the rendering of the docs. In
Doxygen 1.8.7 the list of understood HTML entities was greatly
increased. I tested earlier versions and many little issues returned.
Completely fixes#1557 and the underlying Doxygen changes that caused
it. Should make fish docs simpler and more robust, more consistent and
generally prettier.
todo:
- trap unmarked text as arguments in context
- test & fix sed portability - see in particular. (so far tested on BSD
(Mac) and GNU sed).
- test Makefile changes
- last round of aesthetic changes and getting that ascii fish in there…
Addresses issue #1557 as well as fixing many typos, HTML errors and
inconsistencies. Also introduces automatic syntax colouring and enables
new documentation to be written in Markdown. TODO fix Tutorial.
Rework for Doxygen >1.8. Moved large parts of the documentation to a
simplified format, making use of Markdown enhancements and fixing bad
long options.
When using `complete -c foo -l bar -e`, all long options for the command
were being erased because it was also comparing the short option, which
was 0.
When $IFS is empty, command substitution no longer splits on newlines.
However we still want to trim off a single trailing newline, as most
commands will emit a trailing newline and it makes it harder to work
with their output.
The screen size is fetched after a SIGWINCH is delivered. The current
implementation has two issues:
* It calls ioctl() from the SIGWINCH signal handler, despite ioctl() not
being a function that is known to be safe to call.
* It's not thread-safe.
Signals can be delivered on arbitrary threads, so we don't know if it's
actually safe to be modifying the cached winsize in response to a
signal. It's also plausible that the winsize may be requested from a
background thread.
To solve the first issue, we twiddle a volatile boolean flag in the
signal handler and defer the ioctl() call until we actually request the
screen size.
To solve the second issue, we introduce a pthread rwlock around the
cached winsize. A rwlock is used because it can be expected that there
are likely to be far more window size reads than window size writes. If
we were using C++11 we could probably get away with atomics, but since
we don't have that (or boost), a rwlock should suffice.
Fixes#1613.
When a key is bound to a fish function, if that function invokes
`commandline`, it gets a stale copy of the commandline. This is because
any keys passed to `self-insert` (the default) don't actually get added
to the commandline until a special character is processed, such as the
R_NULL that gets returned after running a binding for a fish command.
To fix this, don't allow fish commands to be run for bindings if we're
processing more than one key. When a key wants to invoke a fish command,
instead we push the invocation sequence back onto the input, followed by
an R_NULL, and return. This causes the input loop to break out and
update the commandline. When it starts up again, it will re-process the
keys and invoke the fish command.
This is primarily an issue with pasting text that includes bound keys in
it. Typed text is slow enough that fish will update the commandline
between each character.
---
I don't know of any way to write a test for this, but the issue can be
reproduced as follows:
> bind _ 'commandline -i _'
This binds _ to a command that inserts _. Typing the following works:
> echo wat_is_it
But if you copy that line and paste it instead of typing it, the end
result looks like
> _echo wat_isit
With this fix in place, the pasted output correctly matches the typed
output.
expand_variables() is slightly confused about how to handle last_idx. On
input, it expects it to be the index to start processing at, but when
called recursively it always passes the current index. This means that
it may sometimes pass an index 1 past the end of the input string.
Notably, that happens when typing something like
> echo "$foo
(where "foo" is any string that is not a prefix of some existing
variable name)
Fix this by explicitly defining last_idx as being the last processed
index, meaning the next index to process is actually last_idx-1. This
means we should call it with next.size() instead of next.size()-1.
gcc interpretes C99's compound literals more strictly by invalid the
compound literal on implicit to pointer cast (because of automatic
storage duration, 6.5.2.5.6 in C99 standard draft).
This fixes the issue by not using compound literals at all.
In the base config.fish, fish_function_path and fish_complete_path have
$__fish_datadir/{functions,completions} added to them if not already
present. For some reason they were replacing the final path component
instead of being added on to the end.
The new --wraps functionality was breaking aliases of the form
`alias foo='bar baz'`. That is, aliases where the body is multiple
words. Extract the first word of the body and use that instead.
Use better errors for aliases with no name or no body.
Remove the useless ASCII test of the first byte of IFS. We don't split
on the first character, we only use a non-empty IFS as a signal to split
on newlines.
IFS is used for more than just the read builtin. Setting it to the empty
string also disables line-splitting in command substitution, and it's
done this for the past 7 years. Some day we may have a better way to do
this, but for now, document the current solution.
The docs claimed that the $HOME and $USER variables could only be
changed by the root user. This is untrue. They can be changed by
non-root users as well.
Repurpose the ENV_INVALID return value for env_set(), which wasn't
currently used by anything. When a bad value is passed for the 'umask'
key, return ENV_INVALID to signal this and print a good error message
from the `set` builtin.
This makes `set umask foo` properly produce an error.
The span now properly points at the token that was invalid, rather than
the start of the slice.
Also fix the span for `()[1]` and `()[d]`, which were previously
reporting no source location at all.
We can't color the whole argument as an error, since the tokenizer is
responsible for that and doesn't care abou this case, but we can color
the `$foo[` bit as an error.
The backslash-escape wasn't being properly caught by the highlighter.
Also remove the highlighting of `"\'"`, as `\'` is not a valid escape in
double-quotes, and add highlighting for a backslash-escaped newline.
When a variable is parsed as being empty, parse out the slice and
validate the indexes anyway, behaving for slicing purposes as if the
variable had a single empty value.
Besides providing errors when expected, this also fixes the following:
set -l foo
echo "$foo[1]"
This used to print "[1]", now it properly prints nothing.
Double expansions of variables had the following issues:
* `"$$foo"` threw an error no matter what the value of `$foo` was.
* `set -l foo ''; echo $$foo` threw an error because of the expansion of
`$foo` to `''`.
With this change, double expansion always works properly. When
double-expanding a multi-valued variable, in a double-quoted string the
first word of the inner expansion is used for the outer expansion, and
outside of a quoted string every word is used for the double-expansion
in each of the arguments.
> set -l foo bar baz
> set -l bar one two
> set -l baz three four
> echo "$$foo"
one two baz
> echo $$foo
one two three four
The characters ANY_CHAR, ANY_STRING, and ANY_STRING_RECURSIVE are
currently transformed by unescape, but not by escape. Let's try escaping
them. Fixes#1614.
Add the --wraps option to 'complete' and 'function'. This allows a
command to (recursively) inherit the completions of a wrapped command.
Fixes#393.
When evaluating a completion, we inspect the entire "wrap chain" for a
command, i.e. we follow the sequence of wrapping until we either hit a
loop (which we silently ignore) or the end of the chain. We then
evaluate completions as if the wrapping command were substituted with
the wrapped command. Currently this only works for commands, i.e.
'complete --command gco --wraps git\ checkout' won't work (that would
seem to encroaching on abbreviations anyways). It might be useful to
show an error message for that case.
The commandline builtin reflects the commandline with the wrapped
command substituted in, so e.g. git completions (which inspect the
command line) will just work. This sort of command line munging is
also performed by 'complete -C' so it's not totally without precedent.
'alias will also now mark its generated function as wrapping the
'target.
Completely fixes#1557 and the underlying Doxygen changes that caused
it. Should make fish docs simpler and more robust, more consistent and
generally prettier.
todo:
- trap unmarked text as arguments in context
- test & fix sed portability - see in particular. (so far tested on BSD
(Mac) and GNU sed).
- test Makefile changes
- last round of aesthetic changes and getting that ascii fish in there…
- Require all requests to use a session path.
- Use a redirect file to avoid exposing the URL on the command line, as
it contains the session path.
Fix for CVE-2014-2914.
Closes#1438.
- Require all requests to use a session path.
- Use a redirect file to avoid exposing the '/start' URL on the
command line, as it contains the cookie value.
Fix for CVE-2014-2914.
Closes#1438.
- Change fishd_path to std::string
- Warn, rather than exiting with an error, if the universal variable
server path is not available, and provide more useful advice.
- Export the new __fishd_runtime_dir variable.
- Use a secure path for sockets (some code used under license from
tmux).
- Provide the secure path in the environment as $__fish_runtime_dir.
- Link the new path to the old path to ease migration from earlier
versions.
Closes#1359.
After installing fish built from or after this commit, you MUST
terminate all running fishd processes (`killall fishd`, `pkill fishd`
or similar). Distributors are encouraged to do this from within their
packaging scripts. fishd will restart automatically, and no data should
be lost.
Addresses issue #1557 as well as fixing many typos, HTML errors and
inconsistencies. Also introduces automatic syntax colouring and enables
new documentation to be written in Markdown. TODO fix Tutorial.
Rework for Doxygen >1.8. Moved large parts of the documentation to a
simplified format, making use of Markdown enhancements and fixing bad
long options.
Currently fish doesn't recognize toor as special. However, it's likely
that on BSD systems, fish shell will be used on toor, not on root (toor
is an intentionally existing account to use more advanced shell on, like
shell).
This stops unconditionally setting values for HOME and USER,
if we find those values in the environment. It also saves about 16KB
on OS X, which getpwuid allocates.
When running `make test` we want to use the local function definitions,
not the ones installed on the system.
The system config.fish will still insert the system definitions at the
end, but at least ours will take precedence.
Enhance the `read` builtin to support creating an array with the --array
flag. With --array, only a single variable name is allowed and the
entire input is tokenized and placed into that variable as an array.
Also add custom behavior if IFS is empty or unset. In that event, split
the input on every character, instead of the previous behavior of doing
no splitting at all.
One of the tests was using `>/dev/null` to suppress the `type` output.
That needs to be `^/dev/null` now, but instead just go ahead and use the
new `-q` flag.
Use `functions -q` instead of searching the `functiosn -na` list for the
provided word. This may result in an automatically-loaded function being
sourced, but that happens anyway with the default output.
This change means the results of `test -q foo` can be relied upon to
indicate whether `foo` can actually be invoked. Previosly, if `foo` was
the name of an automatically-loaded function file but did not actually
define a function `foo`, and there was no execuable `foo`, then `type -q
foo` would lie and say `foo` can be invoked when it can't.
The --quiet flag is useful when only the exit status matters.
Fix the documentation for the -t flag to no longer claim that `type` can
print "keyword", as it never does that.
Stop printing a blank line for functions/builtins when the -p flag has
been passed. It's just not useful.
Track whether -a and -f have been supplied separately. That way both
`type -a -f command` and `type -f -a command` behaves correctly, as does
`type -a -f foo` where there are multiple executables named `foo` in the
$PATH.
Stop using getopt to parse flags. It's far more expensive than
necessary, and results in long flags not being parsed on OS X. This also
allows args starting with - after the options list to be properly
interpreted as a value to test.
Print the error message to stderr as is appropriate.
Use the new `command -p` functionality when the -a flag has not been
provided (`command` does not have any equivalent to the -a flag),
instead of using `which`. This is faster and also avoids any possible
disagreement between `which` and what fish thinks is valid.
Stop testing every path to see if it's executable, that test has already
been done by `which` or `command -p`.
The end result is `type -P ls` is roughly 250% faster, according to
profiling, on my OS X machine.
Instead of introducing a new local scope at the point of `set`, merely
push a new local scope at the end of env_init(). This means we have a
single toplevel local scope across the lifetime of the fish process,
which means that
set -l foo bar
echo $foo
behaves as expected, without modifying the global environment.
The mode restricts the scope in which the variable is searched for.
Use this new restricted scope functionality in the `set` builtin. This
fixes `set -g` to not show local shadowing variable values, and also
allows for scoped erasing of slices.
When attempting to set a readonly or electric variable in the local or
universal scopes, print an appropriate error. Similarly, print an error
when setting an electric variable as exported. In most cases this is
simply a nicer error instead of the 'read-only' one, but for the 'umask'
variable it prevents `set -l umask 0023` from silently changing the
global value.
They're dynamically calculated, so they qualify. This also removes them
from the list of exported global variables, because they're actually not
exported.
When using the `set` command with the -l flag, if we're at the top
level, create a temporary local scope. This makes query/assignment
behavior be consistent with the value-printing behavior.
This works by marking the current block as needing to pop the
environment if a local scope was pushed. I assume this is safe to do. I
also assume the current block is the right one to modify, rather than
trying to walk up the stack to the root.
env_exists() wasn't properly handling multiple scopes in some cases,
notably with readonly/electric variables. Rewrite it to operate in a
more straightforward fashion.
When initializing fish, ignore any inherited environment variables that
match any of the readonly or electric variable names.
This prevents really weird behavior when e.g. fish is launched with
COLUMNS already set to something. In that case, testing $COLUMNS within
fish behaves normally, but any subprocesses get the value that fish
itself had inherited.
The inotify notifier is fragile, fails on travis, and fails to compile
on certain Linux kernels. It doesn't appear to work as well as the named
pipe mechanism. Best to just get rid of it.
In the new mode (not yet enabled), universal variables are set by reading and writing the fishd file directly, with some file locking for synchronization. This enables forwards and backwards compatibility. However there is no compatibility with simultaneous edits. Changes may be lost if fishd and the new mechanisms both attempt writes.
fishd is still enabled by default for now; it will be disabled in a future commit. You can opt into the new mechanism (disabling fishd) by setting the environment variable fish_use_fishd to 0 before starting fish. This cannot itself be a universal variable, because of bootstrapping: the value is needed to determine how we read universal variables in the first place.
Universal variable change notifications (i.e. reacting immediately to live edits) are tricky. Checking for changes is simple and relatively inexpensive (just a stat()), but relying solely on that would require frequent wakeups, and show up in fs_usage. So how do we get change notifications into an fd that we can monitor via select()? We support a few strategies, expressed as universal_notifier_t::notifier_strategy_t. By default we use notifyd on OS X and a named pipe on Linux / everywhere else. This is also configurable at runtime via the fish_universal_notifier variable.
* use $XDG_CACHE_HOME for __fish_print_packages completion caches
* when starting fishd, redirect fishd output to /dev/null, not a
predictable path
Fix for CVE-2014-3219.
Closes#1440.
Currently it contains strange code like using `do` loop in order to
avoid `goto`s (they aren't evil, honestly), the pointless `if (mem)`
conditional which doesn't even work (had semicolon for some reason).
You may think this code had a bug where the code didn't check for
the pointer to be null before calling `free`, but this is not the case,
as according to C and C++ standard, `free` should allow `NULL` pointers,
and ignore them.
When you chroot in Debian, bash shows the chroot environment in the prompt:
```bash
...
if [ -z "${debian_chroot:-}" ] && [ -r /etc/debian_chroot ]; then
debian_chroot=$(cat /etc/debian_chroot)
fi
PS1='${debian_chroot:+($debian_chroot)}\u@\h:\w\$ '
...
```
This is the effect:
```
(chroot_env) user@host:~#
```
It is useful when chrooting, since usually the hostname remains the same and thus you can't distinguish where you are.
This removes undefined behavior in the previous code by properly
checking for miliseconds (actually typing proper names, not abusing
pointer arithmetics).
Now fish shell stores version is a small file called by other files.
This means that a slight change which modifies one file won't cause
many of files to recompile.
The compilation unit is intentionally small, this is by design. The
smaller it is, the faster it will recompile, and it will be compiled
a lot.
This makes white work properly in white terminals when used for
`fish_color_*` variables. It's probably silly thing this small
mistake breaks, to be honest, but it's still a bug.
Fix for CVE-2014-2906.
Closes a race condition in funced which would allow execution of
arbitrary code; closes a race condition in psub which would allow
alternation of the data stream.
Note that `psub -f` does not work (#1040); a fix should be committed
separately for ease of maintenance.
Closes#1437
Fix for CVE-2014-2906.
Closes a race condition in funced which would allow execution of
arbitrary code; closes a race condition in psub which would allow
alternation of the data stream.
Note that `psub -f` does not work (#1040); a fix should be committed
separately for ease of maintenance.
The if statement checking the output of hg bookmarks uses two conditions
joined by the or keyword. However, only the first part was being used.
Wrapping the two statements with begin and end properly combines them.
At some point the non-verbose, non-informative variant of the prompt
(e.g. the variant that looks like the bash prompt) was modified to try
and show the behind/ahead counts the same way the informative prompt
does. Besides being wrong, it also didn't work because behind/ahead
weren't defined.
configure will no longer check for the existence of extra include, lib
and bin directories in /usr/pkg /sw /opt /opt/local /usr/local.
The check was not done in a particularly sensible manner and there are
now no mandatory dependencies that not shipped in the main system trees
on virtually every system in existence.
If building with Fink, follow these directions as suggested by the fink
project:
http://www.finkproject.org/faq/usage-general.php#compile-myselfCloses#1185, and closes#1186.
This change replaces fish's execution model, and obviates much of
parser_t. Instead of parsing fish code into a sequence of
commands-arguments, this reifies syntactic constructs into a grammar,
builds a parse tree, and executes that. This provides a big
simplification and (sometimes) performance boost. fish while loops
become C++ while loops, etc.
There are some known regressions in error reporting, which ought to be
fixed in the soon-to-be-merged parser_cleanup branch. There's also
legitimate changes in edge cases. For example, `command builtin ...` now
executes a command called "builtin" instead of doing something else
weird. The most significant change is that syntactic elements must be
unexpected: for example, single quoting 'command' will now cause it to
not be recognized. This should be fixed soon.
Please open issues for any regressions you find!
parse_error_list_t through all of the expand functions, enabling them to
report errors more directly. Improve aspects of error reporting for
expansion failures.
Conditionally uninitialized:
- builtin_commandline.cpp:577
- expand.cpp:869
- parse_util.cpp:1036
Initialization of POD structs:
- event.cpp:61
- autoload.cpp:22
References used with va_start:
- common.cpp:608:18
Found with clang-3.4's awesome -Wconditional-uninitialized,
-Wmissing-field-initializers and -Wvarargs.
Before this change, fish config used 0 as its address. However, this
isn't a good idea from security point of view, as web service can be
accessed from everywhere, and do anything on the account it was ran on.
This also deals with firewalls which block the access to 0 even from
the host machine itself. It possibly might fix#673, but I'm not sure.
Previously, fish's command_not_found handler would be installed in
__fish_config_interactive. Errors that occured early in startup (e.g. in
config.fish) or in non-interactive mode would therefore not be reported.
With this change, fish now exposes its default cnf handler as
__fish_default_command_not_found_handler . config.fish then installs a
cnfh that invokes the default. When fish goes interactive, the initial
cnfh is overwritten with a fancier one, that may in turn fall back to
invoking the default.
promote it to a decoration (like 'command' or 'builtin'). This makes tab
completion and syntax highlighting treat exec's first argument as a
command and is otherwise a nice simplification. Fixes#1300
is specified before Y, then Y will never be invoked because X will
always get there first. Now instead we order bindings in descending
order by length, so that we always test the binding before any others that
prefixes it. Fixes#1283.
commit d81ae2665f
Author: Max Gonzih <gonzih@gmail.com>
Date: Sun Feb 2 16:22:18 2014 +0300
Check for command-not-found command on suse
commit 004b794c82
Author: Max Gonzih <gonzih@gmail.com>
Date: Sun Feb 2 14:04:41 2014 +0300
Fix cnf handler for Suse and Fedora
fixes#1208
Presently, `isatty` only works on a handful of keywords. Here it
is rewritten to be able to take any path, device or fd number as
an argument, and eliminates errors printed to stdout.
Per discussion in #1228, using `builtin test -c` within a pipe to
test special file descriptors is not viable, so this implementation
specifcially uses `command test`. Additionally, a note has been
added to the documentation of `test` regarding this potential
aberration from the expected output of the test utility under the
'Standards' section.
Note: if you have previously cloned the repository, the tags for
previous versions have been edited. Use `git fetch --tags` to
synchronise your local copy.
Comment out 'o' binding
Add '['/']' bindings to navigate current token history
Fix 'P' to paste indeed
Add "*P/"*p to insert current selection clipboard using xsel
These options will be passed to the bind command.
Now it's possible to call
fish_default_key_bindings -M insert
to set all original bindings to the insert mode
The following normal mode bindings are added:
o, I, A, gg, G, g^, g$, x, X, backspace, d*, D, s, S, c*, C, ~, gu,
gU, J, K, y*, Y, p, P
I was not able to add binding for 'O'
dd now deletes the whole line as vim, while D deletes the line to the
end. c, s, y act the same way
The parser here is a LL(2) parser, which is handwritten (to avoid complicating the build process and to maintain good control over error reporting, thread safety, etc). Later it's worth exploring using parser generators (lemon, etc) or other tools to simplify things.
This commit enables the new parser for syntax highlighting, completions, and abbreviations. Syntax highlighting retains the old implementation (disabled), which will be removed shortly. There is also support for a new execution model, based on the new parser, but it is disabled by default (can be enabled by setting the fish_new_parser variable to 1).
There's also lots of new tests, and some machinery for selecting which tests to run.
After living on this commit for a while, we'll enable the new execution model by default, and then begin to tear down the machinery of the old one (the block types, builtin_end, the parser_t junk, etc.). After that we can pursue even more exotic execution models, like multithreaded ones.
(The branch name is really a misnomer - the tree here is a parse tree, or concrete syntax tree, not an abstract one.)
Fixes#557
It would be nice if this would work without this hack,
but until then, this has to work. Requires you to reinstall
the prompt using fish configuration system.
in reader_shell_test, so that there's always a statement terminator.
Otherwise commands like 'echo |' would not be considered an error (just
incomplete).
Continuation of https://github.com/fish-shell/fish-shell/pull/1195/.
Removes use of --delimiter and --fields with cut(1) as these are GNU
extensions.
Note that a number of completions use these options, but as they are
only for GNU/Linux-specific tools have remained unmodified.
Issue #1108: If there are special characters like '{' in the
completion suggestions, then we fail to parse it successfully
as we are passing an unescaped version of the character to
parser_t::eval_args(...).
This causes us to retun w/o completion suggestions.
This bug was discovered while implementing 'git stash' completion
as the suggestion contained strings like 'stash@\{0\}'.
Th fix is to properly escape the string before parsing it.
This was a really stupid change that I should have tested more
before pushing. It broke any non-interactive usage, such as SSH,
fish config, or parsing the script output, as config.fish is
loaded for everything.
There are no issues with different terminal emulators, so this
change will be pushed in the future, but only running in interactive
mode. I apologize for any issues caused by this commit.
This reverts commit d61adfbc53.
Some people like to have their terminals claim UTF-8 support when
their terminals actually are set to another encoding. As nobody
appears to understand this, I have made a change to automatically
fix the encoding problems if possible. This uses ISO 2022 sequences
in order to dynamically change the encoding.
Fixes#692. Fixes#895. Fixes possible future issues about this.
* Show color scheme title in preview box
* Show information about setting terminal background color on Apply
button mouse hover
* Added text_color_for_color method in colors controller scope
Removes some unused variables and out-of-date references.
Wraps some tests in quotes to avoid expansion errors.
Removes the fish.spec generated file as it is out of date and is
arguably better maintained by downstream packagers.
See http://github.com/zanchey/fish-build/ for a better RPM spec file.
This stops fish from accessing the `bool ok[UCHAR_MAX + 1]` table
beyond allocated space potentially accessing memory that doesn't
belong to fish, and crashing.
It appears that Intel C compiler doesn't recognize unsigned wchar_t,
however it doesn't appear to be important (the conversion function is
unused, and in other cases it doesn't appear to be needed).
Closes: https://github.com/fish-shell/fish-shell/issues/1060
'ansi' should always be present (tested on Solaris, Linux, FreeBSD,
Darwin).
Also overrides TERM so that other programs behave consistently e.g.
fish_pager.
The error message makes no specific mention of terminfo or termcap as
these vary across operating systems.
(r+ @ridiculousfish with thanks)
The intention of the block removed appears to be to indent wrapped lines to the column the line started at. What actually happens is that all wrapped lines wrap to column 0.
After adding the sticky short prompt feature, the block removed caused a bug with wrapping wide characters in addition to not appearing to change anything else.
Wide characters would change between wrapping to column 0 and the column the command started at, depending on what column the wide character was at before wrapping.
I am keeping the existing behavior rather than restoring the block's original intention. If the original intention should be restored, it should be on a different branch.
From the Python webbrowser documentation:
"If text-mode browsers are used, the calling process will block until the user exits the browser."
Running fish_config on an ssh server with no GUI browser will open a CLI browser which blocks and stops the server from handling requests.
Using multiprocess to run the server in the background lets CLI browsers access the page, but the page is unusable.
For now, disable CLI browsers and recommend opening the page in a graphical browser.
In the future, maybe write a CLI utility to change prompts and delete history items.
printf expects unsigned long (%lu) argument, however, size_t doesn't
have to be declared as such. As %zu is C99 (but not C++), it shouldn't
be used directly. Instead, I have to cast value to the correct type.
When launching the first instance of fish and fishd is not launched already, this should not be considered an error as long as it can be launched. So ignore the first failure of connect(), as the calling function get_socket() will try again. May need a bit of cleanup.
Prefer the standard library lzma module if available. This change prevents
using the backports-lzma when it is installed for a version of Python that
already has the lzma module in its standard library.
- expunge LIBS_COMMON, it doesn't get used anywhere
- don't reset LIBS to empty
- move the gettext test as every binary depends on it
- only include one set of libraries
They cannot be used as arguments (Perl thinks it's version check, but
version checks are pointless for oneliners), and Debian puts path
containing version depending directories (like 5.14.2) in Perl path.
There is no need to explicitly check for two arguments and set --bold.
Instead the user can simply "set __fish_git_prompt_color_flags --bold
red".
The current check violates the expectation set by the documentation
that you can use any set_color argument as the current code interprets
"--bold red" as "--bold --bold" instead.
Plus, by passing the full contents of the variable directly, the user
can do more adventurous things like set the background as well.
git.git's git-prompt may not contain a configurable prefix, but it
does display a space before the upstream information when displaying
verbose information. Rather than using a space always or never,
default to a space whenever verbose is in showupstream.
Adds a "name" option to __fish_git_prompt_showupstream that shows an
abbreviated branch name when the upstream type is verbose.
Based on git.git 1f6806c: git-prompt.sh: optionally show upstream
branch name
Per my understanding this is not undefined behavior. No ABI depends on the called function reading
variadic arguments, nor does any standard require it. So if this is crashing something else must be going
on.
This reverts commit 22d22f6aa8.
Having function that takes arbitrary number of arguments without
actually reading them is undefined behavior, as it could cause stack
to be in the corrupted state. Now arguments after token are parsed,
even if they aren't needed.
See also: http://asciinema.org/a/5904
Add support for bzip2 and lzma/xz compressed man pages. Support for bzip2 is
part of the Python standard library (at least for 2.7 and >=3.2), while lzma/xz
is only in Python >=3.3; however, there is a backports module for Python 2.7 and
3.2.
[fish](http://fishshell.com/) - the friendly interactive shell
[fish](http://fishshell.com/) - the friendly interactive shell [](https://travis-ci.org/fish-shell/fish-shell)
================================================
fish is a smart and user-friendly command line shell for OS X, Linux, and the rest of the family. fish includes features like syntax highlighting, autosuggest-as-you-type, and fancy tab completions that just work, with no configuration required.
For more on fish's design philosophy, see the [design document](http://fishshell.com/docs/2.0/design.html).
For more on fish's design philosophy, see the [design document](http://fishshell.com/docs/current/design.html).
## Quick Start
fish generally works like other shells, like bash or zsh. A few important differences can be found at <http://fishshell.com/tutorial.html> by searching for magic phrase 'unlike other shells'.
fish generally works like other shells, like bash or zsh. A few important differences can be found at <http://fishshell.com/docs/current/tutorial.html> by searching for the magic phrase 'unlike other shells'.
Detailed user documentation is available by running `help` within fish, and also at <http://fishshell.com/docs/2.0/index.html>
Detailed user documentation is available by running `help` within fish, and also at <http://fishshell.com/docs/current/index.html>
## Building
@@ -17,8 +17,12 @@ fish is written in a sane subset of C++98, with a few components from C++TR1. It
fish can be built using autotools or Xcode. autoconf 2.60 or later is required.
fish depends on a curses implementation, such as ncurses. The headers and libraries are required for building.
fish requires gettext for translation support.
Building the documentation requires Doxygen 1.8.7 or newer.
### Autotools Build
autoconf
@@ -42,15 +46,27 @@ If fish reports that it could not find curses, try installing a curses developme
fish requires a curses implementation, such as ncurses, to run.
fish requires a number of utilities to operate, which should be present on any Unix, GNU/Linux or OS X system. These include (but are not limited to) hostname, grep, awk, sed, which, and getopt. fish also requires the bc program.
Translation support requires the gettext program.
Some optional features of fish, such as the manual page completion parser and the web configuration tool, require Python.
In order to generate completions from man pages compressed with either lzma or xz, you may need to install an extra Python package. Python versions prior to 2.6 are not supported. For Python versions 2.6 to 3.2 you need to install the module `backports.lzma`. How to install it depends on your system and how you installed Python. Most Linux distributions should include it as a package named `backports-lzma` (or similar). From version 3.3 onwards, Python already includes the required module.
## Packages for Linux
Nightly builds for several Linux distros can be downloaded from <http://download.opensuse.org/repositories/home:/siteshwar/>
Instructions on how to find builds for several Linux distros are at <https://github.com/fish-shell/fish-shell/wiki/Nightly-builds>
/* Mark that we're loading this. Hang onto the iterator for fast erasing later. Note that std::set has guarantees about not invalidating iterators, so this is safe to do across the callouts below. */
/* Note that we are NOT locked in this function! */
size_ti;
boolreloaded=0;
/* Try using a cached function. If we really want the function to be loaded, require that it be really loaded. If we're not reloading, allow stale functions. */
/* completion_apply_to_command_line will append a space unless COMPLETE_NO_SPACE is set. We don't want to set COMPLETE_NO_SPACE because that won't close quotes. What we want is to close the quote, but not append the space. So we just look for the space and clear it. */
/* The input data is meant to be something like you would have on the command line, e.g. includes backslashes. The output should be raw, i.e. unescaped. So we need to unescape the command line. See #1127 */
#define VOMIT_ON_FAILURE(a) do { if (0 != (a)) { int err = errno; fprintf(stderr, "%s failed on line %d in file %s: %d (%s)\n", #a, __LINE__, __FILE__, err, strerror(err)); abort(); }} while (0)
#define VOMIT_ON_FAILURE(a) do { if (0 != (a)) { VOMIT_ABORT(errno, #a); }} while (0)
#define VOMIT_ON_FAILURE_NO_ERRNO(a) do { int err = (a); if (0 != err) { VOMIT_ABORT(err, #a); } } while (0)
#define VOMIT_ABORT(err, str) do { int code = (err); fprintf(stderr, "%s failed on line %d in file %s: %d (%s)\n", str, __LINE__, __FILE__, code, strerror(code)); abort(); } while(0)
/** Exits without invoking destructors (via _exit), useful for code after fork. */
/* "Naturally less than" means in a natural ordering, where digits are treated as numbers. For example, foo10 is naturally greater than foo2 (but alphabetically less than it) */
/* Support for "wrap targets." A wrap target is a command that completes liek another command. The target chain is the sequence of wraps (A wraps B wraps C...). Any loops in the chain are silently ignored. */
# If we are compiling against glibc, set some flags to work around
@@ -367,35 +301,6 @@ case $target_os in
;;
esac
# Check for Solaris curses tputs having fixed length parameter list.
AC_MSG_CHECKING([if we are using non varargs tparm.])
AC_COMPILE_IFELSE(
[
AC_LANG_PROGRAM(
[
#include <curses.h>
#include <term.h>
],
[
tparm( "" );
]
)
],
[tparm_solaris_kludge=no],
[tparm_solaris_kludge=yes]
)
if test "x$tparm_solaris_kludge" = "xyes"; then
AC_MSG_RESULT(yes)
AC_DEFINE(
[TPARM_SOLARIS_KLUDGE],
[1],
[Define to 1 if tparm accepts a fixed amount of paramters.]
)
else
AC_MSG_RESULT(no)
fi
#
# BSD-specific flags go here
#
@@ -413,40 +318,6 @@ case $target_os in
esac
#
# Set up PREFIX and related preprocessor symbols. Fish needs to know
# where it will be installed. One of the reasons for this is so that
# it can make sure the fish installation directory is in the path
# during startup.
#
if [[ "$prefix" = NONE ]]; then
prefix=/usr/local
fi
#
# Set up the directory where the documentation files should be
# installed
#
AC_ARG_VAR( [docdir], [Documentation direcotry] )
if test -z $docdir; then
docdir=$datadir/doc/fish
else
docdir=$docdir
fi
#
# Set up locale directory. This is where the .po files will be
# installed.
#
localedir=$datadir/locale
#
# See if Linux procfs is present. This is used to get extra
# information about running processes.
@@ -466,6 +337,9 @@ AC_DEFINE(
[Define to 1 if the wgettext function should be used for translating strings.]
)
# Disable curses macros that conflict with the STL
AC_DEFINE([NCURSES_NOMACROS], [1], [Define to 1 to disable ncurses macros that conflict with the STL])
AC_DEFINE([NOMACROS], [1], [Define to 1 to disable curses macros that conflict with the STL])
#
# Check presense of various libraries. This is done on a per-binary
@@ -475,89 +349,22 @@ AC_DEFINE(
#
# Check for os dependant libraries for all binaries.
LIBS_COMMON=$LIBS
LIBS=""
AC_SEARCH_LIBS( connect, socket, , [AC_MSG_ERROR([Cannot find the socket library, needed to build this package.] )] )
AC_SEARCH_LIBS( nanosleep, rt, , [AC_MSG_ERROR([Cannot find the rt library, needed to build this package.] )] )
AC_SEARCH_LIBS( shm_open, rt, , [AC_MSG_ERROR([Cannot find the rt library, needed to build this package.] )] )
AC_SEARCH_LIBS( pthread_create, pthread, , [AC_MSG_ERROR([Cannot find the pthread library, needed to build this package.] )] )
AC_SEARCH_LIBS( setupterm, [ncurses curses], , [AC_MSG_ERROR([Could not find a curses implementation, needed to build fish. If this is Linux, try running 'sudo apt-get install libncurses5-dev' or 'sudo yum install ncurses-devel'])] )
AC_SEARCH_LIBS( setupterm, [ncurses tinfo curses], , [AC_MSG_ERROR([Could not find a curses implementation, needed to build fish. If this is Linux, try running 'sudo apt-get install libncurses5-dev' or 'sudo yum install ncurses-devel'])] )
AC_SEARCH_LIBS( [nan], [m], [AC_DEFINE( [HAVE_NAN], [1], [Define to 1 if you have the nan function])] )
LIBS_SHARED=$LIBS
LIBS=$LIBS_COMMON
#
# Check for libraries needed by fish.
#
LIBS_COMMON=$LIBS
LIBS="$LIBS_SHARED"
if test x$local_gettext != xno; then
AC_SEARCH_LIBS( gettext, intl,,)
fi
# Check for libiconv_open if we can't find iconv_open. Silly OS X does
# weird macro magic for the sole purpose of amusing me.
AC_SEARCH_LIBS( iconv_open, iconv, , [AC_SEARCH_LIBS( libiconv_open, iconv, , [AC_MSG_ERROR([Could not find an iconv implementation, needed to build fish])] )] )
LIBS_FISH=$LIBS
LIBS=$LIBS_COMMON
#
# Check for libraries needed by fish_indent.
#
LIBS_COMMON=$LIBS
LIBS="$LIBS_SHARED"
if test x$local_gettext != xno; then
AC_SEARCH_LIBS( gettext, intl,,)
fi
LIBS_FISH_INDENT=$LIBS
LIBS=$LIBS_COMMON
#
# Check for libraries needed by fish_pager.
#
LIBS_COMMON=$LIBS
LIBS="$LIBS_SHARED"
if test x$local_gettext != xno; then
AC_SEARCH_LIBS( gettext, intl,,)
fi
AC_SEARCH_LIBS( iconv_open, iconv, , [AC_SEARCH_LIBS( libiconv_open, iconv, , [AC_MSG_ERROR([Could not find an iconv implementation, needed to build fish])] )] )
LIBS_FISH_PAGER=$LIBS
LIBS=$LIBS_COMMON
#
# Check for libraries needed by fishd.
#
LIBS_COMMON=$LIBS
LIBS="$LIBS_SHARED"
if test x$local_gettext != xno; then
AC_SEARCH_LIBS( gettext, intl,,)
fi
AC_SEARCH_LIBS( iconv_open, iconv, , [AC_SEARCH_LIBS( libiconv_open, iconv, , [AC_MSG_ERROR([Could not find an iconv implementation, needed to build fish])] )] )
The fish documentation has been updated to support Doxygen 1.8.7+, and while the main benefit of this change is extensive Markdown support, the addition of a fish lexicon and syntax filter, combined with semantic markup rules allows for automatic formatting enhancements across the HTML user_docs, the developer docs and the man pages.
Initially my motivation was to fix a problem with long options ([Issue #1557](https://github.com/fish-shell/fish-shell/issues/1557) on GitHub), but as I worked on fixing the issue I realised there was an opportunity to simplify, reinforce and clarify the current documentation, hopefully making further contribution easier and cleaner, while allowing the documentation examples to presented more clearly with less author effort.
While the documentation is pretty robust to variations in the documentation source, adherence to the following style guide will help keep the already excellent documention in good shape moving forward.
## Line breaks and wrapping
Contrary to the rest of the fish source code, the documentation greatly benefits from the use of long lines and soft wrapping. It allows paragraphs to be treated as complete blocks by Doxygen, means that the semantic filter can see complete lines when deciding on how to apply syntax highlighting, and means that man pages will consistently wrap to the width of the users console in advanced pagers, such as 'most'.
## Doxygen special commands and aliases
While Markdown syntax forms the basis of the documentation content, there are some exceptions that require the use of Doxygen special commands. On the whole, Doxygen commands should be avoided, especially inline word formatting such as \\c as this would allow Doxygen to make unhelpful assumptions, such as converting double dashes (\--) to n-dashes (–).
### Structure: \\page, \\section and \\subsection
Use of Doxygen sections markers are important, as these determine what will be eventually output as a web page, man page or included in the developer docs.
Currently the make process for the documentation is quite convoluted, but basically the HTML docs are produced from a single, compiled file, doc.h. This contains a number of \\page markers that produce the various pages used in the documentation. The format of a \\page mark is:
\page universally_unique_page_id Page title
The source files that contain the page markers are currently:
- __index.hdr.in__: Core documentation
- __commands.hdr.in__: Individual commands
- __tutorial.hdr__: Tutorial
- __design.hdr__: Design document
- __faq.hdr__: Frequently Asked Questions
- __license.hdr__: Fish and 3rd party licences
Unless there is a _VERY_ good reason and developer consensus, new pages should never be added.
The rest of the documentation is structured using \\section and \\subsection markers. Most of the source files (listed above) contain their full content, the exception being commands, which are separated out into source text files in the doc_src directory. These files are concatenated into one file, so each one starts with a \\section declaration. The synopsis, description and examples (if present) are declared as \\subsections. The format of these marks is practically identical to the page mark.
\section universally_unique_section_id Section title
\subsection universally_unique_subsection_id Subsection title
Each page, section and subsection id _must_ be unique across the whole of the documentation, otherwise Doxygen will issue a warning.
### Semantic markup: the \\fish .. \\endfish block
While Doxygen has support for \\code..\\endcode blocks with enhanced markup and syntax colouring, it only understands the core Doxygen languages: C, C++, Objective C, Java, PHP, Python, Tcl and Fortran. To enhance Fish's syntax presentation, use the special \\fish..\\endfish blocks instead.
Text placed in this block will be parsed by Doxygen using the included lexicon filter (see lexicon_filter.in) as a Doxygen input filter. The filter is built during make so that it can pick up information on builtins, functions and shell commands mentioned in completions and apply markup to keywords found inside the \\fish block.
Basically, preformatted plain text inside the \\fish block is fed through the filter and is returned marked up so that Doxygen aliases can convert it back to a presentable form, according to the output document type.
For instance:
`echo hello world`
is transformed into:
`@cmnd{echo} @args{hello} @args{world}`
which is then transformed by Doxygen into an HTML version (`make user_doc`):
And a simple HTML version for the developer docs (`make doc`) and the LATEX/PDF manual (`make doc/refman.pdf`):
`echo hello world`
### Fonts
In older browsers, it was easy to set the fonts used for the three basic type styles (serif, sans-serif and monospace). Modern browsers have removed these options in their respective quests for simplification, assuming the content author will provide suitable styles for the content in the site's CSS, or the end user will provide overriding styles manually. Doxygen's default styling is very simple and most users will just accept this default.
I've tried to use a sensible set of fonts in the documentation's CSS based on 'good' terminal fonts and as a result the firt preference font used throughout the documentation is '[DejaVu](http://dejavu-fonts.org)'. The rationale behaind this is that while DejaVu is getting a little long in the tooth, it still provides the most complete support across serif, sans-serif and monospace styles (giving a well balanced feel and consistent [x-height](http://en.wikipedia.org/wiki/X-height)), has the widest support for extended Unicode characters and has a free, permissive licenses (though it's still incompatible with GPLv2, though arguably less so than the SIL Open Font license, though this is a moot point when using it solely in the docs).
#### Fonts inside \\fish blocks and \`backticks\`
As the point of these contructs is to make fish's syntax clearer to the user, it makes sense to mimic what the user will see in the console, therefore any content is formatted using the monospaced style, specifically monospaced fonts are chosen in the following order:
1.__DejaVu Sans Mono__: Explained above. [[↓](http://dejavu-fonts.org)]
2.__Source Code Pro__: Monospaced code font, part of Adobe's free Edge Web Fonts. [[↓](https://edgewebfonts.adobe.com)]
5.__Consolas__: Modern Microsoft supplied console font.
6.__Monaco__: Apple supplied console font since 1984!
7.__Lucida Console__: Generic mono terminal font, standard in many OS's and distros.
8.__monospace__: Catchall style. Chooses default monospaced font, often Courier.
9.__fixed__: As above, more often used on mobile devices.
#### General Fonts
1.__DejaVu Sans__: As above.[[↓](http://dejavu-fonts.org)]
2.__Roboto__: Elegant Google free font and is Doxygen's default [[↓](http://www.google.com/fonts/specimen/Roboto)]
3.__Lucida Grande__: Default Apple OS X content font.
4.__Calibri__: Default Microsoft Office font (since 2007).
5.__Verdana__: Good general font found in a lot of OSs.
6.__Helvetica Neue__: Better spaced and balanced Helvetica/Arial variant.
7.__Helvetica__: Standard humanist typeface found almost everywhere.
8.__Arial__: Microsoft's Helvetica.
9.__sans-serif__: Catchall style. Chooses default sans-serif typeface, often Helvetica.
The ordering of the fonts is important as it's designed to allow the documentation to settle into a number of different identities according to the fonts available. If you have the complete DejaVu family installed, then the docs are presented using that, and if your Console is set up to use the same fonts, presentation will be completely consistent.
On OS X, with nothing extra installed, the docs will default to Menlo and Lucida Grande giving a Mac feel. Under Windows, it will default to using Consolas and Calibri on recent versions, giving a modern Windows style.
#### Other sources:
- [Font Squirrel](http://www.fontsquirrel.com): Good source of open source font packages.
### Choosing a CLI style: using a \\fish{style} block
By default, when output as HTML, a \\fish block uses syntax colouring suited to the style of the documentation rather than trying to mimic the terminal. The block has a light, bordered background and a colour scheme that 'suggests' what the user would see in a console.
Additional stying can be applied adding a style declaration:
\fish{additional_style [another_style...]}
...
\endfish
This will translate to classes applied to the `<div>` tag, like so:
<div class="fish additional_style another_style">
...
</div>
The various classes are defined in `doc_src/user_doc.css` and new style can be simply added
The documentation currently defines a couple of additional styles:
- __cli-dark__: Used in the _tutorial_ and _FAQ_ to simulate a dark background terminal, with fish's default colours (slightly tweaked for legibility in the browser).
- __synopsis__: A simple colour theme helpful for displaying the logical 'summary' of a command's syntax, options and structure.
## Markdown
Apart from the exceptions discussed above, the rest of the documentation now supports the use of Markdown. As such the use of Doxygen special commands for HTML tags is unnecessary.
There are a few exceptions and extensions to the Markdown [standard](http://daringfireball.net/projects/markdown/) that are documented in the Doxygen [documentation](http://www.stack.nl/~dimitri/doxygen/manual/markdown.html).
### \`Backticks\`
As is standard in Markdown and 'Github Flavoured Markdown' (GFM), backticks can be used to denote inline technical terms in the documentation, `like so`. In the documentation this will set the font to the monospaced 'console' typeface and will cause the enclosed term to stand out.
However, fenced code blocks using 4 spaces or 3 backticks (\`\`\`) should be avoided as Doxygen will interpret these as \\code blocks and try to apply standard syntax colouring, which doesn't work so well for fish examples. Use `\fish..\endfish` blocks instead.
### Lists
Standard Markdown list rules apply, but as Doxygen will collapse white space on output, combined with the use of long lines, it's a good idea to include an extra new line between long list items to assist future editing.
## Special cases
The following can be used in \\fish blocks to render some fish scenarios. These are mostly used in the tutorial when an interactive situation needs to be displayed.
### Custom formatting tags
-`<s>`: auto\<s\>suggestion\</s\>.
-`<m>`: \<m\>Matched\</m\> items, such as tab completions.
-`<sm>`: Matched items \<sm\>searched\<sm\> for, like grep results.
-`<error>`: \<error\>This would be shown as an error.\</error\>
-`<asis>`: \<asis\>This test will not be parsed for fish markup.\</asis\>
-`<outp>`: \<outp\>This would be rendered as command/script output.\</outp\>
### Prompts and cursors
-`>_`: Display a basic prompt.
-`~>_`: Display a prompt with a the home directory as the current working directory.
-`___` (3 underscores): Display a cursor.
### Keyboard shortcuts: @key{} and @cursor_key{}
Graphical keyboard shortcuts can be defined using the following special commands. These allow for the different text requirements across the html and man pages. The HTML uses CSS to create a keyboard style, whereas the man page would display the key as text.
-`@key{lable}`
Displays a key with a purely textual lable, such as: 'Tab', 'Page Up', 'Page Down', 'Home', 'End', 'F1', 'F19' and so on.
-`@key{modifier,lable}`
Displays a keystroke requiring the use of a 'modifier' key, such as 'Control-A', 'Shift-X', 'Alt-Tab' etc.
-`@key{modifier,entity,lable}`
Displays a keystroke using a graphical entity, such as an arrow symbol for cursor key based shortcuts.
-`@cursor_key{entity,lable}`
A special case for cursor keys, when no modifier is needed. i.e. `@cursor_key{↑,up}` for the up arrow key.
Some useful Unicode/HTML5 entities:
- Up arrow: `↑`
- Down arrow: `↓`
- Left arrow: `←`
- Right arrow `→`
- Shift: `⇧`
- Tab: `⇥`
- Mac option: `⌥`
- Mac command: `⌘`
## Notes
### Doxygen
Tested on:
- Ubuntu 14.04 with Doxygen 1.8.8, built from [GitHub source](https://github.com/doxygen/doxygen.git).
- CentOS 6.5 with Doxygen 1.8.8, built from [GitHub source](https://github.com/doxygen/doxygen.git).
- Mac OS X 10.9 with Homebrew install Doxygen 1.8.7 and 1.8.8.
Graphviz was also installed in all the above testing.
Doxygen 1.8.6 and lower do not have the \\htmlonly[block] directive which fixes a multitude of problems in the rendering of the docs. In Doxygen 1.8.7 the list of understood HTML entities was greatly increased. I tested earlier versions and many little issues returned.
As fish ships with pre-built documentation, I don't see this as an issue.
### Updated Configure/Makefile
- Tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9.
- Makefile has GNU/BSD sed/grep detection.
### HTML output
- The output HTML is HTML5 compliant, but should quickly and elegantly degrade on older browsers without losing basic structure.
- The CSS avoids the use or browser specific extenstions (i.e. -webkit, -moz etc), using the W3C HTML5 standard instead.
- It's been tested in Chrome 37.0 and Firefox 32.0 on Mac OS X 10.9 (+Safari 7), Windows 8.1 (+Internet Explorer 11) and Ubuntu Desktop 14.04.
- My assumption is basically that if someone cares enough to want to install fish, they'll be keeping a browser current.
### Man page output
- Tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9.
- Output is substantially cleaner.
- Tested in cat, less, more and most pagers using the following fish script:
```
function manTest --description 'Test manpage' --argument page
set -l pager
for i in $argv
switch $i
case "-l"
set pager -P '/usr/bin/less -is'
case "-m"
set pager -P '/usr/bin/more -s'
case "-c"
set pager -P '/bin/cat'
end
end
man $pager ~/Projects/OpenSource/fish-shell/share/man/man1/$page.1
end
# Assumes 'most' is the default system pager.
# NOT PORTABLE! Paths would be need to be updated on other systems.
```
### Developer docs and LATEX/PDF output
- HTML developer docs tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9.
- LATEX/PDF reference manual tested on Mac OS X 10.9 using MacTEX. PDF production returns an error (due to Doxygen's use of an outdated 'float' package), but manual PDF output is ok.
### Future changes
1. The documentation creation process would be better if it could be modularised further and moved out of the makefile into a number of supporting scripts. This would allow both the automake and Xcode build processes to use the documentation scripts directly.
2. Remove the Doxygen dependency entirely for the user documentation. This would be very acheivable now that the bulk of the documentation is in Markdown.
3. It would be useful to gauge what parts of the documentation are actually used by users. Judging by the amount of 'missing comment' errors during the developer docs build phase, this aspect of the docs has been rather neglected. If it is not longer used or useful, then this could change the future direction of the documentation and significantly streamline the process.
#### Author: Mark Griffiths [@GitHub](https://github.com/MarkGriffiths)
`abbr` manipulates the list of abbreviations that fish will expand.
Abbreviations are user-defined character sequences or words that are replaced with longer phrases after they are entered. For example, a frequently-run command such as `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.
Abbreviations are stored, by default, in a universal variable.
The following parameters are available:
- `-a WORD PHRASE` or `--add WORD PHRASE` Adds a new abbreviation, where WORD will be expanded to PHRASE.
- `-s` or `--show` Show all abbreviated words and their expanded phrases in a manner suitable for export and import.
- `-l` or `--list` Lists all abbreviated words.
- `-e WORD` or `--erase WORD` Erase the abbreviation WORD.
\subsection abbr-example Examples
\fish
abbr -a gco git checkout
\endfish
Add a new abbreviation where `gco` will be replaced with `git checkout`.
\fish
abbr -e gco
\endfish
Erase the `gco` abbreviation.
\fish
ssh another_host abbr -s | source
\endfish
Import the abbreviations defined on another_host over SSH.
\c alias is a simple wrapper for the \c function builtin.
It exists for backwards compatibility with Posix
shells. For other uses, it is recommended to define a <a
href='#function'>function</a>.
`alias` is a simple wrapper for the `function` builtin. It exists for backwards compatibility with Posix shells. For other uses, it is recommended to define a <a href='#function'>function</a>.
\c fish does not keep track of which functions have been defined using
\c alias. They must be erased using <code>functions -e</code>.
`fish` does not keep track of which functions have been defined using `alias`. They must be erased using `functions -e`.
- NAME is the name of the alias
- DEFINITION is the actual command to execute. The string " $argv" will be appended.
- `NAME` is the name of the alias
- `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.
\subsection alias-example Example
The following code will create \c rmi, which runs \c rm with additional
arguments on every invocation.
The following code will create `rmi`, which runs `rm` with additional arguments on every invocation.
<code>alias rmi "rm -i"</code>
\fish
alias rmi "rm -i"
This is equivalent to entering the following function:
# This is equivalent to entering the following function:
\section and and - conditionally execute a command
\subsection and-synopsis Synopsis
<tt>COMMAND1; and COMMAND2</tt>
\fish{synopsis}
COMMAND1; and COMMAND2
\endfish
\subsection and-description Description
\c and is used to execute a command if the current exit
status (as set by the last previous command) is 0.
`and` is used to execute a command if the current exit status (as set by the last previous command) is 0.
\c and does not change the current exit status.
`and` does not change the current exit status.
The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable.
The exit status of the last foreground command to exit can always be
accessed using the <a href="index.html#variables-status">$status</a>
variable.
\subsection and-example Example
The following code runs the \c make command to build a program. If the
build succeeds, <code>make</code>'s exit status is 0, and the program is installed. If either step fails,
the exit status is 1, and <tt>make clean</tt> is run, which removes the files created by the.
build process.
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.
is unconditionally executed. <code>begin; ...; end</tt> is equivalent
to <tt>if true; ...; end</tt>.
The block is unconditionally executed. `begin; ...; end` is equivalent to `if true; ...; end`.
\c begin is used to group a number of commands into a block.
This 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 \c and.
`begin` is used to group a number of commands into a block. This 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`.
`begin` does not change the current exit status.
\c begin does not change the current exit status.
\subsection begin-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.
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.
<pre>
\fish
begin
set -l PIRATE Yarrr
...
set -l PIRATE Yarrr
...
end
# This will not output anything, since the PIRATE variable went out
# of scope at the end of the block
echo $PIRATE
</pre>
# This will not output anything, since the PIRATE variable
# went out of scope at the end of the block
\endfish
In the following code, all output is redirected to the file out.html.
\c bg sends <a href="index.html#syntax-job-control">jobs</a> 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 with the specified process group IDs are put in the background.
`bg` sends <a href="index.html#syntax-job-control">jobs</a> 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 with the specified process group IDs are put in the background.
The PID of the desired process is usually found by using <a href="index.html#expand-process">process expansion</a>.
\subsection bg-example Example
<tt>bg \%1</tt> will put the job with job ID 1 in the background.
`bg %1` will put the job with job ID 1 in the background.
<tt>bind</tt> adds a binding for the specified key sequence to the
specified command.
`bind` adds a binding for the specified key sequence to the specified command.
SEQUENCE is the character sequence to bind to. These should be written as
<a href="index.html#escapes">fish escape sequences</a>. For example, because pressing
the Alt key and another character sends that character prefixed with
an escape character, Alt-based key bindings can be written using the
\c \\e escape. For example, Alt-w can be written as
<tt>\\ew</tt>. The control character can be written in much the same way
using the \c \\c escape, for example Control-x (^X) can be written as
<tt>\\cx</tt>. 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 \c fish.
SEQUENCE is the character sequence to bind to. These should be written as <a href="index.html#escapes">fish escape sequences</a>. For example, because pressing the Alt key and another character sends that character prefixed with an escape character, Alt-based key bindings can be written using the `\e` escape. For example, @key{Alt,w} can be written as `\ew`. The control character can be written in much the same way using the `\c` escape, for example @key{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 default key binding can be set by specifying a SEQUENCE of the empty
string (that is, <code>''</code>). It will be used whenever no
other binding matches. For most key bindings, it makes sense to use
the \c self-insert function (i.e. <tt>bind '' self-insert</tt> as the
default keybinding. This will insert any keystrokes not specifically
bound to into the editor. Non-printable characters are ignored by the
editor, so this will not result in control sequences being
printable.
The default key binding can be set by specifying a `SEQUENCE` of the empty string (that is, ```''``` ). It will be used whenever no other binding matches. For most key bindings, it makes sense to use the `self-insert` function (i.e. ```bind '' self-insert```) as the default keybinding. This will insert any keystrokes not specifically bound to into the editor. Non- printable characters are ignored by the editor, so this will not result in control sequences being printable.
If the -k switch is used, the name of the 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 \c terminfo(5) for more information, or use <tt>bind
--key-names</tt> for a list of all available named keys.)
If the `-k` switch is used, the name of the 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.)
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.
`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 <a href="#function">function</a> 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.
When `COMMAND` is a shellscript command, it is a good practice to put the actual code into a <a href="#function">function</a> 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 such a script produces output, the script needs to finish by
calling 'commandline -f repaint' in order to tell fish that a repaint
is in order.
If such a script produces output, the script needs to finish by calling `commandline -f repaint` in order to tell fish that a repaint is in order.
Key bindings are not saved between sessions by default. To save custom
keybindings, edit the \c fish_user_key_bindings function and insert the
appropriate \c bind statements.
When multiple `COMMAND`s are provided, they are all run in the specified order when the key is pressed.
If no `SEQUENCE` is provided, all bindings (or just the bindings in the specified `MODE`) are printed. If `SEQUENCE` is provided without `COMMAND`, just the binding matching that sequence is printed.
Key bindings are not saved between sessions by default. To save custom keybindings, edit the `fish_user_key_bindings` function and insert the appropriate `bind` statements.
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.
The following parameters are available:
- <tt>-k</tt> or <tt>--key</tt> Specify a key name, such as 'left' or 'backspace' instead of a character sequence
- <tt>-K</tt> or <tt>--key-names</tt> Display a list of available key names
- <tt>-f</tt> or <tt>--function-names</tt> Display a list of available input functions
- `-k` or `--key` Specify a key name, such as 'left' or 'backspace' instead of a character sequence
- `-K` or `--key-names` Display a list of available key names. Specifying `-a` or `--all` includes keys that don't have a known mapping
- `-f` or `--function-names` Display a list of available input functions
- `-M MODE` or `--mode MODE` Specify a bind mode that the bind is used in. Defaults to "default"
- `-m NEW_MODE` or `--sets-mode NEW_MODE` Change the current mode to `NEW_MODE` after this binding is executed
- `-e` or `--erase` Erase the binding with the given sequence and mode instead 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 sequence.
- `-a` or `--all` See `--erase` and `--key-names`
The following special input functions are available:
- \c backward-char, moves one character to the left
- \c backward-delete-char, deletes one character of input to the left of the cursor
- \c backward-kill-line, move everything from the beginning of the line to the cursor to the killring
- \c backward-kill-word, move the word to the left of the cursor to the killring
- \c backward-word, move one word to the left
- \c beginning-of-history, move to the beginning of the history
- \c beginning-of-line, move to the beginning of the line
- \c capitalize-word, make the current word begin with a capital letter
- \c complete, guess the remainder of the current token
- \c delete-char, delete one character to the right of the cursor
- \c delete-line, delete the entire line
- \c downcase-word, make the current word lowercase
- \c dump-functions, print a list of all key-bindings
- \c end-of-history, move to the end of the history
- \c end-of-line, move to the end of the line
- \c explain, print a description of possible problems with the current command
- \c forward-char, move one character to the right
- \c forward-word, move one word to the right
- \c history-search-backward, search the history for the previous match
- \c history-search-forward, search the history for the next match
- \c kill-line, move everything from the cursor to the end of the line to the killring
- \c kill-whole-line, move the line to the killring
- \c kill-word, move the next word to the killring
- \c upcase-word, make the current word uppercase
- \c yank, insert the latest entry of the killring into the buffer
- \c yank-pop, rotate to the previous entry of the killring
- `backward-char`, moves one character to the left
- `backward-delete-char`, deletes one character of input to the left of the cursor
- `backward-kill-line`, move everything from the beginning of the line to the cursor to the killring
- `backward-kill-word`, move the word to the left of the cursor to the killring
- `backward-word`, move one word to the left
- `beginning-of-history`, move to the beginning of the history
- `beginning-of-line`, move to the beginning of the line
- `capitalize-word`, make the current word begin with a capital letter
- `complete`, guess the remainder of the current token
- `delete-char`, delete one character to the right of the cursor
- `delete-line`, delete the entire line
- `downcase-word`, make the current word lowercase
- `dump-functions`, print a list of all key-bindings
- `end-of-history`, move to the end of the history
- `end-of-line`, move to the end of the line
- `explain`, print a description of possible problems with the current command
- `forward-char`, move one character to the right
- `forward-word`, move one word to the right
- `history-search-backward`, search the history for the previous match
- `history-search-forward`, search the history for the next match
- `kill-line`, move everything from the cursor to the end of the line to the killring
- `kill-whole-line`, move the line to the killring
- `kill-word`, move the next word to the killring
- `upcase-word`, make the current word uppercase
- `yank`, insert the latest entry of the killring into the buffer
- `yank-pop`, rotate to the previous entry of the killring
\subsection bind-example Examples
<tt>bind \\cd 'exit'</tt> causes \c fish to exit when Control-d is pressed.
\fish
bind \cd 'exit'
\endfish
Causes `fish` to exit when @key{Control,D} is pressed.
<tt>bind -k ppage history-search-backward</tt> performs a history search when the Page Up key is pressed.
\fish
bind -k ppage history-search-backward
\endfish
Performs a history search when the @key{Page Up} key is pressed.
\fish
set -g fish_key_bindings fish_vi_key_bindings
bind -M insert \cc kill-whole-line force-repaint
\endfish
Turns on Vi key bindings and rebinds @key{Control,C} to clear the input line.
\section block block - temporarily block delivery of events
\subsection block-synopsis Synopsis
<tt>block [OPTIONS...]</tt>
\fish{synopsis}
block [OPTIONS...]
\endfish
\subsection block-description Description
\c block prevents events triggered by \c fish or the
<a href="commands.html#emit"><code>emit</code></a> command from
being delivered and acted upon while the block is in place.
`block` prevents events triggered by `fish` or the <a href="commands.html#emit">`emit`</a> command from being delivered and acted upon while the block is in place.
In functions, \c block can be useful while performing work that
should not be interrupted by the shell.
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.
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 <code>begin</code>, <code>if</code>, <code>while</code> or
<code>for</code>
Event blocks should not be confused with code blocks, which are created with `begin`, `if`, `while` or `for`
The following parameters are available:
- <tt>-l</tt> or <tt>--local</tt> Release the block automatically at the end of the current innermost code block scope
- <tt>-g</tt> or <tt>--global</tt> Never automatically release the lock
- <tt>-e</tt> or <tt>--erase</tt> Release global block
- `-l` or `--local` Release the block automatically at the end of the current innermost code block scope
- `-g` or `--global` Never automatically release the lock
- `-e` or `--erase` Release global block
\subsection block-example Example
<pre>
\fish
# Create a function that listens for events
function --on-event foo foo; echo 'foo fired'; end
LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end
\endfish
\subsection break-description Description
\c break halts a currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
`break` halts a currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
There are no parameters for `break`.
There are no parameters for <code>break</code>.
\subsection break-example Example
The following code searches all .c files for "smurf", and halts at the first occurrence.
switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
\endfish
\subsection case-description Description
\c switch performs one of several blocks of commands, depending on whether
a specified value equals one of several wildcarded values. \c case is used
together with the \c switch statement in order to determine which block should
be executed.
`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 \c case command is given one or more parameters. The first \c case
command with a parameter that matches the string specified in the
switch command will be evaluated. \c case parameters may contain
wildcards. These need to be escaped or quoted in order to avoid
regular wildcard expansion using filenames.
Each `case` command is given one or more parameters. The first `case` command 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 expansion using filenames.
Note that fish does not fall through on case statements. Only the
first matching case is executed.
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.
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
If the variable \$animal contains the name of an animal, the following
code would attempt to classify it:
<pre>
\fish
switch $animal
case cat
echo evil
@@ -43,8 +35,8 @@ switch $animal
case '*'
echo I have no idea what a $animal is
end
</pre>
\endfish
If the above code was run with \c \$animal set to \c whale, the output
would be \c mammal.
If the above code was run with `$animal` set to `whale`, the output
If \c DIRECTORY is supplied, it will become the new directory. If no parameter
is given, the contents of the \c HOME environment variable will be used.
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.
If \c DIRECTORY is a relative path, the paths found in the
\c CDPATH environment variable array will be tried as prefixes for the specified
path.
If `DIRECTORY` is a relative path, the paths found in the `CDPATH` environment variable array will be tried as prefixes for the specified path.
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 `/`).
Note that the shell will attempt to change directory without requiring \c cd
if the name of a directory is provided (starting with '.', '/' or '~', or ending
with '/').
\subsection cd-example Examples
\c cd changes the working directory to your home directory.
\fish
cd
# changes the working directory to your home directory.
<code>cd /usr/src/fish-shell</code> changes the working directory to
<code>/usr/src/fish-shell</code>.
cd /usr/src/fish-shell
# changes the working directory to /usr/src/fish-shell
\c command forces the shell to execute the program \c COMMANDNAME and ignore any functions or builtins with the same name.
`command` forces the shell to execute the program `COMMANDNAME` and ignore any functions or builtins with the same name.
\subsection command-example Example
The following options are available:
<tt>command ls</tt> causes fish to execute the \c ls program, even if an 'ls' function exists.
- `-s` or `--search` returns the name of the disk file 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 commands were found, or 1 if no commands could be found.
For basic compatibility with POSIX `command`, the `-v` flag is recognized as an alias for `-s`.
\subsection command-example Examples
`command ls` causes fish to execute the `ls` program, even if an `ls` function exists.
`command -s ls` returns the path to the `ls` program.
\section commandline commandline - set or get the current command line buffer
\subsection commandline-synopsis Synopsis
<tt>commandline [OPTIONS] [CMD]</tt>
\fish{synopsis}
commandline [OPTIONS] [CMD]
\endfish
\subsection commandline-description Description
\c commandline can be used to set or get the current contents of the command
line buffer.
`commandline` can be used to set or get the current contents of the command line buffer.
With no parameters, \c commandline returns the current value of the command
line.
With no parameters, `commandline` returns the current value of the command line.
With \c CMD specified, the command line buffer is erased and replaced with
the contents of \c CMD.
With `CMD` specified, the command line buffer is erased and replaced with the contents of `CMD`.
The following options are available:
- \c -C or \c --cursor set or get the current cursor position, not
the contents of the buffer. If no argument is given, the current
cursor position is printed, otherwise the argument is interpreted
as the new cursor position.
- \c -f or \c --function inject readline functions into the
reader. This option cannot be combined with any other option. It
will cause any additional arguments to be interpreted as readline
functions, and these functions will be injected into the reader, so
that they will be returned to the reader before any additional
actual key presses are read.
- `-C` or `--cursor` set or get the current cursor position, not the contents of the buffer. If no argument is given, the current cursor position is printed, otherwise the argument is interpreted as the new cursor position.
The following options change the way \c commandline updates the
command line buffer:
- `-f` or `--function` inject readline functions into the reader. This option cannot be combined with any other option. It will cause any additional arguments to be interpreted as readline functions, and these functions will be injected into the reader, so that they will be returned to the reader before any additional actual key presses are read.
- \c -a or \c --append do not remove the current commandline, append
the specified string at the end of it
- \c -i or \c --insert do not remove the current commandline, insert
the specified string at the current cursor position
- \c -r or \c --replace remove the current commandline and replace it
with the specified string (default)
The following options change the way `commandline` updates the commandline buffer:
The following options change what part of the commandline is printed
or updated:
- `-a` or `--append` do not remove the current commandline, append the specified string at the end of it
- \c -b or \c --current-buffer select the entire buffer (default)
- \c -j or \c --current-job select the current job
- \c -p or \c --current-process select the current process
- \c -t or \c --current-token select the current token.
- `-i` or `--insert` do not remove the current commandline, insert the specified string at the current cursor position
The following options change the way \c commandline prints the current
commandline buffer:
- `-r` or `--replace` remove the current commandline and replace it with the specified string (default)
- \c -c or \c --cut-at-cursor only print selection up until the
current cursor position
- \c -o or \c --tokenize tokenize the selection and print one string-type token per line
The following options change what part of the commandline is printed or updated:
- `-b` or `--current-buffer` select the entire buffer (default)
- `-j` or `--current-job` select the current job
- `-p` or `--current-process` select the current process
- `-t` or `--current-token` select the current token.
The following options change the way `commandline` prints the current commandline buffer:
- `-c` or `--cut-at-cursor` only print selection up until the current cursor position
- `-o` or `--tokenize` tokenize the selection and print one string-type token 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:
- `-L` or `--line` print the line that the cursor is on, with the topmost line starting at 1
- `-S` or `--search-mode` evaluates to true if the commandline is performing a history search
- `-P` or `--paging-mode` evaluates to true if the commandline is showing pager contents, such as tab completions
If \c commandline is called during a call to complete a given string
using <code>complete -C STRING</code>, \c commandline will consider the
specified string to be the current contents of the command line.
\subsection commandline-example Example
<tt>commandline -j $history[3]</tt> replaces the job under the cursor with the
third item from the command line history.
`commandline -j $history[3]` replaces the job under the cursor with the third item from the command line history.
Fish ships with a large number of builtin commands, shellscript functions and external commands. These are all described below.
/**
\page commands Commands
\htmlonly[block]
<div class="fish_left_bar">
<div class="logo"></div>
<div class="menu commands_menu">
\endhtmlonly
@command_list@
\htmlonly </div> \endhtmlonly
@command_list_toc@
\htmlonly[block]
</div>
</div>
<div class="commands fish_right_bar">
<h1 class="interior_title">Command reference</h1>
\endhtmlonly
`fish` ships with a large number of builtin commands, shellscript functions and external commands. These are all described below.
Almost all fish commands respond to the `-h` or `--help` options to display their relevant help, also accessible using the `help` and `man` commands, like so:
\fish
echo -h
echo --help
# Prints help to the terminal window
man echo
# Displays the man page in the system pager
# (normally 'less', 'more' or 'most').
help echo
# Open a web browser to show the relevant documentation
@@ -9,69 +16,88 @@ For an introduction to specifying completions, see <a
href='index.html#completion-own'>Writing your own completions</a> in
the fish manual.
- <tt>COMMAND</tt> is the name of the command for which to add a completion
- <tt>SHORT_OPTION</tt> is a one character option for the command
- <tt>LONG_OPTION</tt> is a multi character option for the command
- <tt>OPTION_ARGUMENTS</tt> is parameter containing a space-separated list of possible option-arguments, which may contain subshells
- <tt>DESCRIPTION</tt> is a description of what the option and/or option arguments do
- <tt>-C STRING</tt> or <tt>--do-complete=STRING</tt> makes complete try to find all possible completions for the specified string
- <tt>-e</tt> or <tt>--erase</tt> implies that the specified completion should be deleted
- <tt>-f</tt> or <tt>--no-files</tt> specifies that the option specified by this completion may not be followed by a filename
- <tt>-n</tt> or <tt>--condition</tt> specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases.
- <tt>-o</tt> or <tt>--old-option</tt> implies that the command uses old long style options with only one dash
- <tt>-p</tt> or <tt>--path</tt> implies that the string COMMAND is the full path of the command
- <tt>-r</tt> or <tt>--require-parameter</tt> specifies that the option specified by this completion always must have an option argument, i.e. may not be followed by another option
- <tt>-u</tt> or <tt>--unauthoritative</tt> implies that there may be more options than the ones specified, and that fish should not assume that options not listed are spelling errors
- <tt>-A</tt> or <tt>--authoritative</tt> implies that there may be no more options than the ones specified, and that fish should assume that options not listed are spelling errors
- <tt>-x</tt> or <tt>--exclusive</tt> implies both <tt>-r</tt> and <tt>-f</tt>
- `COMMAND` is the name of the command for which to add a completion.
Command specific tab-completions in \c fish are based on the notion
of options and arguments. An option is a parameter which begins with a
hyphen, such as '-h', '-help' or '--help'. Arguments are parameters
that do not begin with a hyphen. Fish recognizes three styles of
options, the same styles as the GNU version of the getopt
library. These styles are:
- `SHORT_OPTION` is a one character option for the command.
- Short options, like '-a'. Short options are a single character long, are preceded by a single hyphen and may 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').
- Old style long options, like '-Wall'. 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').
- GNU style long options, like '--colors'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('--quoting-style shell') or by appending the option with a '=' and the value ('--quoting-style=shell'). GNU style long options may be abbreviated so long as the abbreviation is unique ('--h' is equivalent to '--help' if help is the only long option beginning with an 'h').
- `LONG_OPTION` is a multi character option for the command.
The options for specifying command name, command path, or command
switches may all be used multiple times to specify multiple commands
which have the same completion or multiple switches accepted by a
command.
- `OPTION_ARGUMENTS` is parameter containing a space-separated list of possible option-arguments, which may contain subshells.
- `DESCRIPTION` is a description of what the option and/or option arguments do.
- `-C STRING` or `--do-complete=STRING` makes complete try to find all possible completions for the specified string.
- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the specified command to inherit completions from the wrapped command.
- `-e` or `--erase` implies that the specified completion should be deleted.
- `-f` or `--no-files` specifies that the option specified by this completion may not be followed by a filename.
- `-n` or `--condition` specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases.
- `-o` or `--old-option` implies that the command uses old long style options with only one dash.
- `-p` or `--path` implies that the string `COMMAND` is the full path of the command.
- `-r` or `--require-parameter` specifies that the option specified by this completion always must have an option argument, i.e. may not be followed by another option.
- `-u` or `--unauthoritative` implies that there may be more options than the ones specified, and that fish should not assume that options not listed are spelling errors.
- `-A` or `--authoritative` implies that there may be no more options than the ones specified, and that fish should assume that options not listed are spelling errors.
- `-x` or `--exclusive` implies both `-r` and `-f`.
Command specific tab-completions in `fish` are based on the notion of options and arguments. An option is a parameter which begins with a hyphen, such as '`-h`', '`-help`' or '`--help`'. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU version of the getopt library. These styles are:
- Short options, like '`-a`'. Short options are a single character long, are preceded by a single hyphen and may 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`').
- Old style long options, like '`-Wall`'. 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`').
- GNU style long options, like '`--colors`'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('`--quoting-style`') or by appending the option with a '`=`' and the value ('`--quoting-style=shell`'). GNU style long options may be abbreviated so long as the abbreviation is unique ('`--h`') is equivalent to '`--help`' if help is the only long option beginning with an 'h').
The options for specifying command name, command path, or command switches may all be used multiple times to specify multiple commands which have the same completion or multiple switches accepted by a command.
The `-w` or `--wraps` options causes the specified command to inherit completions from another command. The inheriting command is said to "wrap" the inherited command. The wrapping command may have its own completions in addition to inherited ones. A command may 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.
When erasing completions, it is possible to either erase all completions for a specific command by specifying `complete -e -c COMMAND`, or by specifying a specific completion option to delete by specifying either a long, short or old style option.
When erasing completions, it is possible to either erase all
completions for a specific command by specifying <tt>complete -e -c
COMMAND</tt>, or by specifying a specific completion option to delete
by specifying either a long, short or old style option.
\subsection complete-example Example
The short style option <tt>-o</tt> for the \c gcc command requires
that a file follows it. This can be done using writing <tt>complete
-c gcc -s o -r</tt>.
The short style option `-o` for the `gcc` command requires that a file follows it. This can be done using writing:
The short style option <tt>-d</tt> for the \c grep command requires
that one of the strings 'read', 'skip' or 'recurse' is used. This can
be specified writing <tt>complete -c grep -s d -x -a "read skip
recurse"</tt>.
\fish
complete -c gcc -s o -r
\endfish
The \c 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: <tt>complete -x -c su -d "Username" -a "(cat
/etc/passwd|cut -d : -f 1)" </tt>.
The short style option `-d` for the `grep` command requires that one of the strings '`read`', '`skip`' or '`recurse`' is used. This can be specified writing:
The \c rpm command has several different modes. If the \c -e or \c
--erase flag has been specified, \c rpm should delete one or more
packages, in which case several switches related to deleting packages
are valid, like the \c nodeps switch.
\fish
complete -c grep -s d -x -a "read skip recurse"
\endfish
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:
\fish
complete -x -c su -d "Username" -a "(cat /etc/passwd | cut -d : -f 1)"
\endfish
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.
\section contains contains - test if a word is present in a list
\subsection contains-synopsis Synopsis
<code>contains [OPTIONS] KEY [VALUES...]</code>
\fish{synopsis}
contains [OPTIONS] KEY [VALUES...]
\endfish
\subsection contains-description Description
\c contains tests whether the set \c VALUES contains the string
<code>KEY</code>. If so, \c contains exits with status 0; if not, it exits
with status 1.
`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:
- \c -i or \c --index print the word index
- \c -h or \c --help display this message
- `-i` or `--index` print the word index
Note that, like GNU tools, `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
<pre>
for i in ~/bin /usr/local/bin
if not contains \$i \$PATH
set PATH \$PATH \$i
end
end
</pre>
The above code tests if \c ~/bin and \c /usr/local/bin are in the path and adds them if not.
\fish
for i in ~/bin /usr/local/bin
if not contains $i $PATH
set PATH $PATH $i
end
end
\endfish
The above code tests if `~/bin` and `/usr/local/bin` are in the path and adds them if not.
\fish
function hasargs
if contains -- -q $argv
echo '$argv contains a -q option'
end
end
\endfish
The above code checks for `-q` in the argument list, using the `--` argument to demarcate options to `contains` from the key to search for.
LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end
\endfish
\subsection continue-description Description
\c continue skips the remainder of the current iteration of the current inner loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
`continue` skips the remainder of the current iteration of the current inner loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
\subsection continue-example Example
The following code removes all tmp files that do not contain the word smurf.
\section count count - count the number of elements of an array
\subsection count-synopsis Synopsis
<tt>count $VARIABLE</tt>
\fish{synopsis}
count $VARIABLE
\endfish
\subsection count-description Description
<tt>count</tt> 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.
`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.
\c count does not accept any options, including '-h'.
`count` does not accept any options, including `-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.
\c 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
<pre>
\fish
count $PATH
</pre>
# Returns the number of directories in the users PATH variable.
returns the number of directories in the users PATH variable.
<pre>
count *.txt
</pre>
returns the number of files in the current working directory ending with the suffix '.txt'.
# Returns the number of files in the current working directory ending with the suffix '.txt'.
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:
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:
-# Everything that can be done in other shell languages should be
possible to do in fish, though fish may rely on external commands in
doing so.
-# Fish should be user friendly, but not at the expense of expressiveness.
Most tradeoffs between power and ease of use can be avoided with careful design.
-# Whenever possible without breaking the above goals, fish should
follow the Posix syntax.
-# Everything that can be done in other shell languages should be possible to do in fish, though fish may rely on external commands in doing so.
-# Fish should be user friendly, but not at the expense of expressiveness. Most tradeoffs between power and ease of use can be avoided with careful design.
-# Whenever possible without breaking the above goals, fish should follow 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.
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.
\section ortho 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.
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 sourcecode, making the
program harder to maintain and update.
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:
- Here documents are too similar to using echo inside of a pipeline.
- Subshells, command substitution and process substitution are strongly related. \c fish only supports command substitution, the others can be achieved either using a block or the psub shellscript function.
- Having both aliases and functions is confusing, especially since both of them have limitations and problems. \c fish functions have none of the drawbacks of either syntax.
- The many Posix quoting styles are silly, especially \$''.
\section sep The law of responsiveness
- 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.
- 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.
- The many Posix quoting styles are silly, especially $''.
\section design-response 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:
- Features like syntax highlighting and autosuggestions must perform all of their disk I/O asynchronously.
- Startup should minimize forks and disk I/O, so that fish can be started even if the system is under load.
\section conf Configurability is the root of all evil
\section design-configurability 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 failiure of both the program and the programmer
who implemented it.
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 imply
assumptions about the code which change when reimplementing the code,
causing issues with backwards compatibility. But mostly, configuration
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.
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 imply assumptions about the code which change when reimplementing the code, causing issues with backwards compatibility. But mostly, configuration 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:
- 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.
- Fish does not allow you to set the history filename, the number of history entries, different language substyles or any number of other common shell configuration 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
default. 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 support that are
disabled by default include tab-completion of strings containing
wildcards, a sane completion pager and a history file.
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 default. 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 disabled by default include tab-completion of strings containing wildcards, a sane completion pager and a history file.
\section user The law of user focus
When designing a program, one should first think about how to make a
intuitive and powerful program. Implementation issues should only be
considered once a user interface has been designed.
When designing a program, one should first think about how to make a 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 describes 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 to 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.
This design rule is different than the others, since it describes 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:
- There should only be one type of input to the shell, lists of commands. Loops, conditionals and variable assignments are all performed through regular commands.
- The differences between builtin commands and shellscript functions should be made as small as possible. Builtins and shellscript functions should have exactly the same types of argument expansion as other commands, should be possible to use in any position in a pipeline, and should support any io redirection.
- The differences between built-in commands and shellscript functions should be made as small as possible. Built-ins and shellscript functions should have exactly the same types of argument expansion as other commands, should be possible to use in any position in a pipeline, and should support any I/O redirection.
- 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.
- All blocks end with the \c end builtin.
- All blocks end with the `end` built-in.
\section disc The law of discoverability
A program should be designed to make its features as
easy as possible to discover for the user.
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.
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
program is discoverability. In a graphical program, one can discover
all the common features by simply looking at the user interface and
guessing what the different buttons, menus and other widgets do. The
traditional way to discover features in commandline programs is
through manual pages. This requires both that the user starts to use a
different program, and the she/he then remembers the new information
until the next time she/he uses the same program.
The main benefit of a graphical program over a command-line-based program is discoverability. In a graphical program, one can discover all the common features by simply looking at the user interface and guessing what the different buttons, menus and other widgets do. The traditional way to discover features in command-line programs is through manual pages. This requires both that the user starts to use a different program, and then she/he remembers the new information until the next time she/he uses the same program.
Examples:
- Everything should be tab-completable, and every tab completion should have a description.
- Every syntax error and error in a builtin 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 highlighter.
- 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 highlighter.
- The help manual should be easy to read, easily available from the shell, complete and contain many examples
- The language should be uniform, so that once the user understands the command/argument syntax, he will know the whole language, and be able to use tab-completion to discover new featues.
- The language should be uniform, so that once the user understands the command/argument syntax, she/he will know the whole language, and be able to use tab-completion to discover new features.
`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.
if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
\endfish
\subsection else-description Description
<tt>if</tt> will execute the command \c CONDITION. If the condition's exit
status is 0, the commands \c COMMANDS_TRUE will execute. If it is not 0 and
<tt>else</tt> is given, \c COMMANDS_FALSE will be executed.
`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
The following code tests whether a file \c foo.txt exists as a regular file.
The following code tests whether a file `foo.txt` exists as a regular file.
\c 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.
`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
The following code first defines an event handler for the generic
event named 'test_event', and then emits an event of that type.
The following code first defines an event handler for the generic event named 'test_event', and then emits an event of that type.
\section eval eval - evaluate the specified commands
\subsection eval-synopsis Synopsis
<tt>eval [COMMANDS...]</tt>
\fish{synopsis}
eval [COMMANDS...]
\endfish
\subsection eval-description Description
<tt>eval</tt> 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.
`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.
\subsection eval-example Example
The folloing code will call the ls command. Note that \c fish does not
support the use of environment variables as direct commands; \c eval can
be used to work around this.
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.
\section exec exec - execute command in current process
\subsection exec-synopsis Synopsis
<tt>exec COMMAND [OPTIONS...]</tt>
\fish{synopsis}
exec COMMAND [OPTIONS...]
\endfish
\subsection exec-description Description
\c exec replaces the currently running shell with a new command.
On successful completion, \c exec never returns. \c exec cannot be used
inside a pipeline.
`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
<tt>exec emacs</tt> starts up the emacs text editor, and exits \c fish.
When emacs exits, the session will terminate.
`exec emacs` starts up the emacs text editor, and exits `fish`. When emacs exits, the session will terminate.
\c exit causes fish to exit. If <tt>STATUS</tt> 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.
`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.
If exit is called while sourcing a file (using the <a
href="#source">.</a> builtin) the rest of the file will be skipped,
but the shell itself will not exit.
If exit is called while sourcing a file (using the <a href="#source">source</a> builtin) the rest of the file will be skipped, but the shell itself will not exit.
\section faq-envvar How do I set or clear an environment variable?
Use the <a href="commands.html#set"><code>set</code></a> command:
Use the <a href="commands.html#set">`set`</a> command:
<pre>set -x key value
set -e key</pre>
\fish{cli-dark}
set -x key value
set -e key
\endfish
<hr>
\section faq-login-cmd How do I run a command every login? What's fish's equivalent to .bashrc?
Edit the file <tt>~/.config/fish/config.fish</tt>, creating it if it does not
exist. (Note the leading period.)
Edit the file `~/.config/fish/config.fish`, creating it if it does not exist (Note the leading period).
<hr>
\section faq-prompt How do I set my prompt?
The prompt is the output of the \c fish_prompt function. Put it in
<tt>~/.config/fish/functions/fish_prompt.fish</tt>. For example, a simple
prompt is:
<pre>function fish_prompt
set_color $fish_color_cwd
echo -n (prompt_pwd)
set_color normal
echo -n ' > '
end</pre>
The prompt is the output of the `fish_prompt` function. Put it in `~/.config/fish/functions/fish_prompt.fish`. For example, a simple prompt is:
You can also use the Web configuration tool,
<a href="commands.html#fish_config"><code>fish_config</code></a>, to preview
and choose from a gallery of sample prompts.
\fish{cli-dark}
function fish_prompt
set_color $fish_color_cwd
echo -n (prompt_pwd)
set_color normal
echo -n ' > '
end
\endfish
You can also use the Web configuration tool, <a href="commands.html#fish_config">`fish_config`</a>, to preview and choose from a gallery of sample prompts.
<hr>
\section faq-cmd-history How do I run a command from history?
Type some part of the command, and then hit the up or down arrow keys to
navigate through history matches.
Type some part of the command, and then hit the @cursor_key{↑,up} or @cursor_key{↓,down} arrow keys to navigate through history matches.
<hr>
\section faq-subcommand How do I run a subcommand? The backtick doesn't work!
\c fish uses parentheses for subcommands. For example:
`fish` uses parentheses for subcommands. For example:
<pre>for i in (ls)
echo $i
end</pre>
\fish{cli-dark}
for i in (ls)
echo $i
end
\endfish
<hr>
\section faq-exit-status How do I get the exit status of a command?
Use the \c $status variable. This replaces the \c $? variable used in some
other shells.
Use the `$status` variable. This replaces the `$?` variable used in some other shells.
<hr>
\section faq-single-env How do I set an environment variable for just one command?
<i><tt>SOME_VAR=1 command</tt> produces an error: <tt>Unknown command "SOME_VAR=1"</tt>.</i>
<i>`SOME_VAR=1 command` produces an error: `Unknown command "SOME_VAR=1"`.</i>
Use the \c env command.
Use the `env` command.
<tt>env SOME_VAR=1 command</tt>
`env SOME_VAR=1 command`
You can also declare a local variable in a block:
<pre>begin
set -lx SOME_VAR 1
command
end</pre>
\fish{cli-dark}
begin
set -lx SOME_VAR 1
command
end
\endfish
<hr>
\section faq-customize-colors How do I customize my syntax highlighting colors?
Use the web configuration tool,
<a href="commands.html#fish_config"><code>fish_config</code></a>, or alter the
<a href="index.html#variables-color">\c fish_color family of environment variables</a>.
Use the web configuration tool, <a href="commands.html#fish_config">`fish_config`</a>, or alter the <a href="index.html#variables-color">`fish_color` family of environment variables</a>.
<hr>
\section faq-update-manpage-completions How do I update man page completions?
Use the <a href="commands.html#fish_update_completions">`fish_update_completions`</a> command.
<hr>
\section faq-cwd-symlink Why does cd, $PWD and and various fish commands always resolve symlinked directories to their canonical path?
<i>
For example if ~/images is a symlink to ~/Documents/Images, if I write
'cd images', my prompt will say ~/D/Images, not ~/images.
</i>
<i>For example if `~/images` is a symlink to `~/Documents/Images`, if I write '`cd images`', my prompt will say `~/Documents/Images`, not `~/images`.</i>
Because it is impossible to consistently keep symlinked directories
unresolved. It is indeed possible to do this partially, and many other
shells do so. But it was felt there are enough serious corner cases
that this is a bad idea. Most such issues have to do with how '..' is
handled, and are varitations of the following example:
Because it is impossible to consistently keep symlinked directories unresolved. It is indeed possible to do this partially, and many other shells do so. But it was felt there are enough serious corner cases that this is a bad idea. Most such issues have to do with how '..' is handled, and are varitations of the following example:
Writing <code>cd images; ls ..</code> given the above directory
structure would list the contents of ~/Documents, not of ~, even
though using <code>cd ..</code> changes the current directory to ~,
and the prompt, the pwd builtin and many other directory information
sources suggest that the current directory is ~/images and its
parent is ~. This issue is not possible to fix without either making
every single command into a builtin, breaking Unix semantics or
implementing kludges in every single command.
Writing `cd images; ls ..` given the above directory structure would list the contents of `~/Documents`, not of `~`, even though using `cd ..` changes the current directory to `~`, and the prompt, the `pwd` builtin and many other directory information sources suggest that the current directory is `~/images` and its parent is `~`. This issue is not possible to fix without either making every single command into a builtin, breaking Unix semantics or implementing kludges in every single command. This issue can also be seen when doing IO redirection.
This issue can also be seen when doing IO redirection.
Another related issue is that many programs that operate on recursive
directory trees, like the find command, silently ignore symlinked
directories. For example, <code>find $PWD -name '*.txt'</code>
silently fails in shells that don't resolve symlinked paths.
Another related issue is that many programs that operate on recursive directory trees, like the find command, silently ignore symlinked directories. For example, ```find $PWD -name '*.txt'``` silently fails in shells that don't resolve symlinked paths.
<hr>
\section faq-cd-implicit 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 directory. For example, the
fastest way to switch to your home directory is to simply press
<code>~</code> and enter.
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 directory. For example, the fastest way to switch to your home directory is to simply press `~` and enter.
<hr>
\section faq-open The open command doesn't work.
The \c open command uses the MIME type database and the <code>.desktop</code> 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 <a href="index.html#more-help">asking for
more help</a>.
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 <a href="index.html#more-help">asking for more help</a>.
<hr>
\section faq-default 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) as root:
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) as root:
Fish is trying to set the titlebar message of your terminal. While
screen itself supports this feature, your terminal does
not. Unfortunately, when the underlying terminal doesn't support
setting the titlebar, screen simply passes through the escape codes
and text to the underlying terminal instead of ignoring them. It is
impossible 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.
Fish is trying to set the titlebar message of your terminal. While screen itself supports this feature, your terminal does not. Unfortunately, when the underlying terminal doesn't support setting the titlebar, screen simply passes through the escape codes and text to the underlying 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_title function will not work.
Note that fish has a default titlebar message, which will be used if the fish_title function is undefined. So simply unsetting the fish_title function will not work.
<hr>
\section faq-greeting How do I change the greeting message?
Change the value of the variable fish_greeting. For example, to remove
the greeting use:
Change the value of the variable `fish_greeting` or create a `fish_greeting` function. For example, to remove the greeting use:
<pre>
\fish{cli-dark}
set fish_greeting
</pre>
\endfish
<hr>
\section faq-history Why doesn't history substitution ("!$" etc.) work?
Because history substitution is an awkward interface that was invented before
interactive line editing was even possible. Fish drops it in favor of
perfecting the interactive history recall interface. Switching requires a
small change of habits: if you want to modify an old line/word, first recall
it, then edit. E.g. don't type "sudo !!" - first press Up, then Home, then
type "sudo ".
Because history substitution is an awkward interface that was invented before interactive line editing was even possible. Fish drops it in favor of perfecting the interactive history recall interface. Switching requires a small change of habits: if you want to modify an old line/word, first recall it, then edit. E.g. don't type "sudo !!" - first press Up, then Home, then type "sudo ".
Fish history recall is very simple yet effective:
- As in any modern shell, the Up arrow recalls whole lines, starting from the last line executed. A single press replaces "!!", later presses replace "!-3" and the like.
- 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 constrain the recall to lines that include this text, and you will get to the line you want much faster. This replaces "!vi", "!?bar.c" and the like.
- Alt+Up recalls individual arguments, starting from the last argument in the last line executed. A single press replaces "!$", later presses replace "!!:4" and the like.
- 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+Up. This will show only arguments containing that part and you will get what you want much faster. Try it out, this is very convenient!
- 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).
- As in any modern shell, the Up arrow, @cursor_key{↑,Up} recalls whole lines, starting from the last line executed. A single press replaces "!!", later presses replace "!-3" and the like.
- 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 constrain the recall to lines that include this text, and you will get to the line you want much faster. This replaces "!vi", "!?bar.c" and the like.
- @key{Alt,↑,Up} recalls individual arguments, starting from the last argument in the last line executed. A single press replaces "!$", later presses replace "!!:4" and the like.
- 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 @key{Alt,↑,Up}. This will show only arguments containing that part and you will get what you want much faster. Try it out, this is very convenient!
- 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 (@key{Alt,D} and @key{Alt,Backspace} are your friends).
See <a href='index.html#editor'>documentation</a> for more details about line editing in fish.
<hr>
\section faq-uninstalling Uninstalling fish
Should you wish to uninstall fish, first ensure fish is not set as your shell. Run <code>chsh -s /bin/bash</code> if you are not sure.
Should you wish to uninstall fish, first ensure fish is not set as your shell. Run `chsh -s /bin/bash` if you are not sure.
Next, do the following (assuming fish was installed to /usr/local):
\c fg brings the specified <a href="index.html#syntax-job-control">job</a> 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.
`fg` brings the specified <a href="index.html#syntax-job-control">job</a> 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.
The PID of the desired process is usually found by using <a href="index.html#expand-process">process expansion</a>.
\subsection fg-example Example
<tt>fg \%1</tt> will put the job with job ID 1 in the foreground.
`fg %1` will put the job with job ID 1 in the foreground.
\section fish fish - the friendly interactive shell
\subsection fish-synopsis Synopsis
fish [-h] [-v] [-c command] [FILE [ARGUMENTS...]]
\fish{synopsis}
fish [OPTIONS] [-c command] [FILE [ARGUMENTS...]]
\endfish
\subsection fish-description Description
\c fish is a command-line shell written mainly with interactive use in mind. The
full manual is available <a href='index.html'>in HTML</a> by using the
<a href='#help'>help</a> command from inside fish.
`fish` is a command-line shell written mainly with interactive use in mind. The full manual is available <a href='index.html'>in HTML</a> by using the <a href='#help'>help</a> command from inside fish.
The following options are available:
- <code>-c</code> or <code>--command=COMMANDS</code> evaluate the specified commands instead of reading from the commandline
- <code>-d</code> or <code>--debug-level=DEBUG_LEVEL</code> specify the verbosity level of fish. A higher number means higher verbosity. The default level is 1.
- <code>-h</code> or <code>--help</code> display help and exit
- <code>-i</code> or <code>--interactive</code> specify that fish is to run in interactive mode
- <code>-l</code> or <code>--login</code> specify that fish is to run as a login shell
- <code>-n</code> or <code>--no-execute</code> do not execute any commands, only perform syntax checking
- <code>-p</code> or <code>--profile=PROFILE_FILE</code> when fish exits, output timing information on all executed commands to the specified file
- <code>-v</code> or <code>--version</code> display version and exit
- `-c` or `--command=COMMANDS` evaluate the specified commands instead of reading from the commandline
The fish exit status is generally the exit status of the last
foreground command. If fish is exiting because of a parse error, the
exit status is 127.
- `-d` or `--debug-level=DEBUG_LEVEL` specify the verbosity level of fish. A higher number means higher verbosity. The default level is 1.
- `-i` or `--interactive` specify that fish is to run in interactive mode
- `-l` or `--login` specify that fish is to run as a login shell
- `-n` or `--no-execute` do not execute any commands, only perform syntax checking
- `-p` or `--profile=PROFILE_FILE` when fish exits, output timing information on all executed commands to the specified file
- `-v` or `--version` display version and exit
The fish exit status is generally the exit status of the last foreground command. If fish is exiting because of a parse error, the exit status is 127.
\c fish_config starts the web-based configuration interface.
`fish_config` 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.
The web interface allows you to view your functions, variables and history, and to make changes to your prompt and color configuration.
\c fish_config starts a local web server and then opens a web browser window; when
you have finished, close the browser window and then press the Enter key to
terminate the configuration session.
`fish_config` starts a local web server and then opens a web browser window; when you have finished, close the browser window and then press the Enter key to terminate the configuration session.
<code>fish_config</code> optionally accepts name of the initial configuration tab. For e.g. <code>fish_config history</code> will start configuration interface with history tab.
`fish_config` optionally accepts name of the initial configuration tab. For e.g. `fish_config history` will start configuration interface with history tab.
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.
If the \c 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
\c fish_config opens a new web browser window and allows you to configure certain
fish settings.
`fish_config` opens a new web browser window and allows you to configure certain fish settings.
\section fish_indent fish_indent - indenter and prettifier
\subsection fish_indent-synopsis Synopsis
<tt>fish_indent [options]</tt>
\fish{synopsis}
fish_indent [OPTIONS]
\endfish
\subsection fish_indent-description Description
\c fish_indent is used to indent a piece of fish
code. \c fish_indent reads commands from standard input and outputs
them to standard output.
`fish_indent` is used to indent a piece of fish code. `fish_indent` reads commands from standard input and outputs them to standard output.
The following options are available:
- <tt>-h</tt> or <tt>--help</tt> displays this help message and then exits
- <tt>-i</tt> or <tt>--no-indent</tt> do not indent commands
- <tt>-v</tt> or <tt>--version</tt> displays the current fish version and then exits
- `-i` or `--no-indent` do not indent commands; only reformat to one job per line
- `-v` or `--version` displays the current fish version and then exits
- `--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`).
- `--html` outputs HTML, which supports syntax highlighting if the appropriate CSS is defined. The CSS class names are the same as the variable names, such as `fish_color_command`
\section fish_prompt fish_prompt - define the appearance of the command line prompt
\subsection fish_prompt-synopsis Synopsis
<pre>function fish_prompt
\fish{synopsis}
function fish_prompt
...
end</pre>
end
\endfish
\subsection fish_prompt-description Description
By defining the \c fish_prompt function, the user can choose a custom
prompt. The \c fish_prompt function is executed when the prompt is to
be shown, and the output is used as a prompt.
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.
The exit status of commands within \c fish_prompt will not modify the value of <a href="index.html#variables-status">$status</a> outside of the \c fish_prompt function.
The exit status of commands within `fish_prompt` will not modify the value of <a href="index.html#variables-status">$status</a> outside of the `fish_prompt` function.
`fish` ships with a number of example prompts that can be chosen with the `fish_config` command.
\c fish ships with a number of example prompts that can be chosen with the
\c fish_update_completions parses manual pages installed on the system, and attempts to create completion files in the \c fish configuration directory.
`fish_update_completions` parses manual pages installed on the system, and attempts to create completion files in the `fish` configuration directory.
This does not overwrite custom completions.
There are no parameters for <code>fish_update_completions</code>.
There are no parameters for `fish_update_completions`.
\section for for - perform a set of commands multiple times.
\subsection for-synopsis Synopsis
<tt>for VARNAME in [VALUES...]; COMMANDS...; end</tt>
\fish{synopsis}
for VARNAME in [VALUES...]; COMMANDS...; end
\endfish
\subsection for-description Description
<tt>for</tt> is a loop construct. It will perform the commands specified by
\c COMMANDS multiple times. On each iteration, the environment variable specified by
\c VARNAME is assigned a new value from \c VALUES. If \c VALUES is empty, \c COMMANDS will
not be executed at all.
`for` is a loop construct. It will perform the commands specified by `COMMANDS` 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.
\section funced funced - edit a function interactively
\subsection funced-synopsis Synopsis
<code>funced [OPTIONS] NAME</code>
\fish{synopsis}
funced [OPTIONS] NAME
\endfish
\subsection funced-description Description
\c funced provides an interface to edit the definition of the function
<code>NAME</code>.
`funced` provides an interface to edit the definition of the function `NAME`.
If the \c $EDITOR environment variable is set, it will be used as the program
to edit the function. Otherwise, a built-in editor will be used.
If the `$EDITOR` environment variable is set, it will be used as the program to edit the function. Otherwise, a built-in editor will be used.
If there is no function called \c NAME a new function will be created with
the specified name
If there is no function called `NAME` a new function will be created with the specified name
- <code>-e command</code> or <code>--editor command</code> Open the function
body inside the text editor given by the command (for example, "vi"). The
command 'fish' will use the built-in editor.
- <code>-i</code> or <code>--interactive</code> Open function body in the
built-in editor.
- `-e command` or `--editor command` Open the function body inside the text editor given by the command (for example, "vi"). The command 'fish' will use the built-in editor.
- `-i` or `--interactive` Open function body in the built-in editor.
\section funcsave funcsave - save the definition of a function to the user's autoload directory
\subsection funcsave-synopsis Synopsis
<tt>funcsave FUNCTION_NAME</tt>
\fish{synopsis}
funcsave FUNCTION_NAME
\endfish
\subsection funcsave-description Description
\c funcsave saves the current definition of a function to
a file in the fish configuration directory. 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.
`funcsave` saves the current definition of a function to a file in the fish configuration directory. 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.
\c function creates a new function \c NAME with the body <code>BODY</code>.
`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.
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:
- <code>-a NAMES</code> or <code>--argument-names NAMES</code> assigns the value of successive command-line arguments to the names given in NAMES.
- <code>-d DESCRIPTION</code> or \c --description=DESCRIPTION is a description of what the function does, suitable as a completion description.
- <code>-e</code> or <code>--on-event EVENT_NAME</code> tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.
- <code>-j PID</code> or <code> --on-job-exit PID</code> tells fish to run this function when the job with group ID 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 triggered by the exit of the job which created this command substitution.
- <code>-p PID</code> or <code> --on-process-exit PID</code> tells fish to run this function when the fish child process with process ID PID exits.
- <code>-s</code> or <code>--on-signal SIGSPEC</code> 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).
- \c -S or \c --no-scope-shadowing allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents is independent of the calling function.
- <code>-v</code> or <code>--on-variable VARIABLE_NAME</code> tells fish to run this function when the variable VARIABLE_NAME changes value.
- `-a NAMES` or `--argument-names NAMES` assigns the value of successive command-line arguments to the names given in NAMES.
If the user enters any additional arguments after the function, they
are inserted into the environment <a href="index.html#variables-arrays">variable array</a>
<code>$argv</code>. If the \c --argument-names option is provided, the arguments are
also assigned to names specified in that option.
- `-d DESCRIPTION` or `--description=DESCRIPTION` is a description of what the function does, suitable as a completion description.
- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the function to inherit completions from the given wrapped command. See the documentation for <a href="#complete">`complete`</a> for more information.
- `-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.
- `-v` or `--on-variable VARIABLE_NAME` tells fish to run this function when the variable VARIABLE_NAME changes value.
- `-j PGID` or `--on-job-exit PGID` tells fish to run this function when the job with group ID PGID exits. Instead of PGID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.
- `-p PID` or `--on-process-exit PID` tells fish to run this function when the fish child process with process ID PID exits.
- `-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).
- `-S` or `--no-scope-shadowing` allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents is independent of the calling function.
- `-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 executed.
If the user enters any additional arguments after the function, they are inserted into the environment <a href="index.html#variables-arrays">variable array</a> `$argv`. If the `--argument-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 <a href="#emit">emit</a> builtin. Fish generates the following named events:
- \c fish_prompt, which is emitted whenever a new fish prompt is about to be displayed.
- \c fish_command_not_found, which is emitted whenever a command lookup failed.
- `fish_prompt`, which is emitted whenever a new fish prompt is about to be displayed.
- `fish_command_not_found`, which is emitted whenever a command lookup failed.
- `fish_preexec`, which is emitted right before executing an interactive command. The commandline is passed as the first parameter.
Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines.
- `fish_postexec`, which is emitted right after executing an interactive command. The commandline is passed as the first parameter.
Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines.
\subsection function-example Example
<pre>
\fish
function ll
ls -l $argv
ls -l $argv
end
</pre>
\endfish
will run the \c ls command, using the \c -l option, while passing on any additional files and switches to \c ls.
will run the `ls` command, using the `-l` option, while passing on any additional files and switches to `ls`.
<pre>
\fish
function mkdir -d "Create a directory and set CWD"
command mkdir $argv
if test $status = 0
switch $argv[(count $argv)]
case '-*'
command mkdir $argv
if test $status = 0
switch $argv[(count $argv)]
case '-*'
case '*'
cd $argv[(count $argv)]
return
end
end
case '*'
cd $argv[(count $argv)]
return
end
end
end
</pre>
\endfish
will run the mkdir command, and if it is successful, change the
current working directory to the one just created.
This will run the `mkdir` command, and if it is successful, change the current working directory to the one just created.
\fish
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
\endfish
This will beep when the most recent job completes.
\section functions functions - print or erase functions
\subsection function-synopsis Synopsis
<pre>functions [-n]
\subsection functions-synopsis Synopsis
\fish{synopsis}
functions [ -a | --all ] [ -n | --names ]
functions -c OLDNAME NEWNAME
functions -d DESCRIPTION FUNCTION
functions [-eq] FUNCTIONS...</pre>
functions [-e | -q ] FUNCTIONS...
\endfish
\subsection functions-description Description
\c functions prints or erases functions.
`functions` prints or erases functions.
The following options are available:
- <code>-a</code> or <code>--all</code> lists all functions, even those whose name start with an underscore.
- <code>-c OLDNAME NEWNAME</code> or <code>--copy OLDNAME NEWNAME</code> creates a new function named NEWNAME, using the definition of the OLDNAME function.
- <code>-d DESCRIPTION</code> or <code>--description=DESCRIPTION</code> changes the description of this function.
- <code>-e</code> or <code>--erase</code> causes the specified functions to be erased.
- <code>-h</code> or <code>--help</code> displays a help message and exits.
- <code>-n</code> or <code>--names</code> lists the names of all defined functions.
- <code>-q</code> or <code>--query</code> tests if the specified functions exist.
- `-a` or `--all` lists all functions, even those whose name start with an underscore.
The default behavior of <code>functions</code>, when called with no arguments,
is to print the names of all defined functions. Unless the \c -a option is
given, no functions starting with underscores are not included in the output.
- `-c OLDNAME NEWNAME` or `--copy OLDNAME NEWNAME` creates a new function named NEWNAME, using the definition of the OLDNAME function.
If any non-option parameters are given, the definition of the specified
functions are printed.
- `-d DESCRIPTION` or `--description=DESCRIPTION` changes the description of this function.
Automatically loaded functions cannot be removed using <code>functions
-e</code>. Either remove the definition file or change the
$fish_function_path variable to remove autoloaded functions.
- `-e` or `--erase` causes the specified functions to be erased.
Copying a function using \c -c copies only the body of the function, and
does not attach any event notifications from the original function.
- `-n` or `--names` lists the names of all defined functions.
Only one function's description can be changed in a single invocation
of <code>functions -d</code>.
- `-q` or `--query` tests if the specified functions exist.
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 not included in the output.
If any non-option parameters are given, the definition of the specified functions are printed.
Automatically loaded functions cannot be removed using `functions -e`. Either remove the definition file or change the $fish_function_path variable to remove autoloaded functions.
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.
The exit status of \c functions is the number of functions
specified in the argument list that do not exist, which can be used in
concert with the \c -q option.
\subsection functions-example Examples
\fish
functions -n
# Displays a list of currently-defined functions
<code>functions -n</code> displays a list of currently-defined functions.
functions -c foo bar
# Copies the 'foo' function to a new function called 'bar'
<code>functions -c foo bar</code> copies the \c foo function to a new function called
<code>bar</code>.
<code>functions -e bar</code> erases the function <code>bar</code>.
\c history is used to list, search and delete the history of commands used.
`history` is used to list, search and delete the history of commands used.
The following options are available:
- `--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.
- \c --save saves all changes in the history file. The shell automatically
saves the history file; this option is provided for internal use.
- \c --clear clears the history file. A prompt is displayed before the history
is erased.
- \c --search returns history items in keeping with the \c --prefix or
\c --contains options.
- \c --delete deletes history items.
- \c --prefix searches or deletes items in the history that begin with the
specified text string.
- \c --contains searches or deletes items in the history that contain the
specified text string.
- `--save` saves all changes in the history file. The shell automatically saves the history file; this option is provided for internal use.
If \c --search is specified without \c --contains or <code>--prefix</code>,
\c --contains will be assumed.
- `--clear` clears the history file. A prompt is displayed before the history is erased.
- `--search` returns history items in keeping with the `--prefix` or `--contains` options.
- `--delete` deletes history items.
- `--prefix` searches or deletes items in the history that begin with the specified text string.
- `--contains` searches or deletes items in the history that contain the specified text string.
If `--search` is specified without `--contains` or `--prefix`, `--contains` will be assumed.
If `--delete` is specified without `--contains` or `--prefix`, only a history item which exactly matches the parameter will be erased. No prompt will be given. If `--delete` is specified with either of these parameters, an interactive prompt will be displayed before any items are deleted.
If \c --delete is specified without \c --contains or <code>--prefix</code>,
only a history item which exactly matches the parameter will be erased. No
prompt will be given. If \c --delete is specified with either of these
parameters, an interactive prompt will be displayed before any items are
deleted.
\subsection history-examples Example
<code>history --clear</code> deletes all history items
\fish
history --clear
# Deletes all history items
<code>history --search --contains "foo"</code> outputs a list of all previous
commands containing the string "foo".
history --search --contains "foo"
# Outputs a list of all previous commands containing the string "foo".
<code>history --delete --prefix "foo"</code> interactively deletes the record
of previous commands which start with "foo".
history --delete --prefix "foo"
# Interactively deletes the record of previous commands which start with "foo".
<tt>if CONDITION; COMMANDS_TRUE...; [else if CONDITION2; COMMANDS_TRUE2...;] [else; COMMANDS_FALSE...;] end</tt>
\fish{synopsis}
if CONDITION; COMMANDS_TRUE...;
[else if CONDITION2; COMMANDS_TRUE2...;]
[else; COMMANDS_FALSE...;]
end
\endfish
\subsection if-description Description
<tt>if</tt> will execute the command \c CONDITION. If the condition's
exit status is 0, the commands \c COMMANDS_TRUE will execute. If the
exit status is not 0 and <tt>else</tt> is given, \c COMMANDS_FALSE will
be executed.
`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.
In order to use the exit status of multiple commands as the condition
of an if block, use <a href="#begin"><tt>begin; ...; end</tt></a> and
the short circuit commands <a href="commands.html#and"><tt>and</tt></a>
and <a href="commands.html#or"><tt>or</tt></a>.
In order to use the exit status of multiple commands as the condition of an if block, use <a href="#begin">`begin; ...; end`</a> and the short circuit commands <a href="commands.html#and">`and`</a> and <a href="commands.html#or">`or`</a>.
The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable.
The exit status of the last foreground command to exit can always be
accessed using the <a href="index.html#variables-status">$status</a>
variable.
\subsection if-example Example
<pre>
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`.
\fish
if test -f foo.txt
echo foo.txt exists
echo foo.txt exists
else if test -f bar.txt
echo bar.txt exists
echo bar.txt exists
else
echo foo.txt and bar.txt do not exist
echo foo.txt and bar.txt do not exist
end
</pre>will print <tt>foo.txt exists</tt> if the file foo.txt
exists and is a regular file, otherwise it will print
<tt>bar.txt exists</tt> if the file bar.txt exists
\section isatty isatty - test if the specified file descriptor is a tty
\section isatty isatty - test if a file descriptor is a tty.
\subsection isatty-synopsis Synopsis
<tt>isatty [FILE DESCRIPTOR]</tt>
\fish{synopsis}
isatty [FILE DESCRIPTOR]
\endfish
\subsection isatty-description Description
<tt>isatty</tt> tests if a file descriptor is a tty.
<tt>FILE DESCRIPTOR</tt> may be either the number of a file descriptor, or one of the
strings <tt>stdin</tt>, \c stdout and <tt>stderr</tt>.
`isatty` tests if a file descriptor is a tty.
If the specified file descriptor is a tty, the exit status of the command is
zero. Otherwise, it is non-zero.
`FILE DESCRIPTOR` may be either the number of a file descriptor, or one of the strings `stdin`, `stdout`, or `stderr`.
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
From an interactive shell, the commands below exit with a return value of zero:
running <a href="index.html#syntax-job-control">jobs</a> and their status.
`jobs` prints a list of the currently running <a href="index.html#syntax-job-control">jobs</a> and their status.
jobs accepts the following switches:
- <code>-c</code> or <code>--command</code> prints the command name for each process in jobs.
- <code>-g</code> or <code>--group</code> only prints the group ID of each job.
- <code>-h</code> or <code>--help</code> displays a help message and exits.
- <code>-l</code> or <code>--last</code> prints only the last job to be started.
- <code>-p</code> or <code>--pid</code> prints the process ID for each process in all jobs.
- `-c` or `--command` prints the command name for each process in jobs.
- `-g` or `--group` only prints the group ID of each job.
- `-l` or `--last` prints only the last job to be started.
- `-p` or `--pid` prints the process ID for each process in all jobs.
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 expressed as a percentage of full CPU activity. Note that on multiprocessor systems, the total activity may be more than 100\%.
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
expressed as a percentage of full CPU activity. Note that on
multiprocessor systems, the total activity may be more than 100\%.
\subsection jobs-example Example
<code>jobs</code> outputs a summary of the current jobs.
\section math math - Perform mathematics calculations
\subsection math-synopsis Synopsis
<tt>math EXPRESSION</tt>
\fish{synopsis}
math EXPRESSION
\endfish
\subsection math-description Description
\c math is used to perform mathematical calculations. It is a very
thin wrapper for the bc program, which makes it possible to specify an
expression from the command line without using non-standard extensions
or a pipeline.
`math` is used to perform mathematical calculations. It is a very thin wrapper for the bc program, which makes it possible to specify an expression from the command line without using non-standard extensions or a pipeline.
For a description of the syntax supported by math, see the manual for the bc program. Keep in mind that parameter expansion takes place on any expressions before they are evaluated. This can be very useful in order to perform calculations involving shell variables or the output of command substitutions, but it also means that parenthesis have to be escaped.
For a description of the syntax supported by math, see the manual for
the bc program. Keep in mind that parameter expansion takes place on
any expressions before they are evaluated. This can be very useful in
order to perform calculations involving environment variables or the
output of command substitutions, but it also means that parenthesis
have to be escaped.
\subsection math-example Examples
<code>math 1+1</code> outputs 2.
`math 1+1` outputs 2.
<code>math $status-128</code> outputs the numerical exit status of the
last command minus 128.
`math $status-128` outputs the numerical exit status of the last command minus 128.
\section mimedb mimedb - lookup file information via the mime database
\subsection mimedb-synopsis Synopsis
<tt>mimedb [OPTIONS] FILES...</tt>
\fish{synopsis}
mimedb [OPTIONS] FILES...
\endfish
\subsection mimedb-description Description
\c mimedb queries the MIME type database and the \c .desktop files
installed on the system in order to find information on
the files listed in <code>FILES</code>. The information that \c mimedb
can retrieve includes the MIME type for a file, a description of the type,
and the default action that can be performed on the file. \c mimedb can also
be used to launch the default action for this file.
`mimedb` queries the MIME type database and the `.desktop` files installed on the system in order to find information on the files listed in `FILES`. The information that `mimedb` can retrieve includes the MIME type for a file, a description of the type, and the default action that can be performed on the file. `mimedb` can also be used to launch the default action for this file.
The following options are available:
- \c -t, \c --input-file-data determines the files' type both by their filename and by their contents (default behaviour).
- \c -f, \c --input-filename determines the files' type by their filename.
- \c -i, \c --input-mime specifies that the arguments are not files, but MIME types.
- \c -m, \c --output-mime outputs the MIME type of each file (default behaviour).
- \c -f, \c --output-description outputs the description of each MIME type.
- \c -a, \c --output-action outputs the default action of each MIME type.
- \c -l, \c --launch launches the default action for the specified files.
- \c -h, \c --help displays a help message and exit.
- \c -v, \c --version displays the version number and exits.
- `-t`, `--input-file-data` determines the files' type both by their filename and by their contents (default behaviour).
- `-f`, `--input-filename` determines the files' type by their filename.
- `-i`, `--input-mime` specifies that the arguments are not files, but MIME types.
- `-m`, `--output-mime` outputs the MIME type of each file (default behaviour).
- `-f`, `--output-description` outputs the description of each MIME type.
- `-a`, `--output-action` outputs the default action of each MIME type.
- `-l`, `--launch` launches the default action for the specified files.
- `-v`, `--version` displays the version number and exits.
\section open open - open file in its default application
\subsection open-synopsis Synopsis
<tt>open FILES...</tt>
\fish{synopsis}
open FILES...
\endfish
\subsection open-description Description
\c open opens a file in its default application, using the \c xdg-open command if it exists, or else the <a href="commands.html#mimedb">mimedb</a> command.
`open` opens a file in its default application, using the `xdg-open` command if it exists, or else the <a href="commands.html#mimedb">mimedb</a> command.
\subsection open-example Example
<tt>open *.txt</tt> opens all the text files in the current directory using your system's default text editor.
`open *.txt` opens all the text files in the current directory using your system's default text editor.
\c or is used to execute a command if the current exit
status (as set by the last previous command) is not 0.
`or` is used to execute a command if the current exit status (as set by the last previous command) is not 0.
\c or does not change the current exit status.
`or` does not change the current exit status.
The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable.
The exit status of the last foreground command to exit can always be
accessed using the <a href="index.html#variables-status">$status</a>
variable.
\subsection or-example Example
The following code runs the \c make command to build a program. If the
build succeeds, the program is installed. If either step fails,
<tt>make clean</tt> is run, which removes the files created by the
build process.
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.
<tt>popd</tt> removes the top directory from the directory stack and
changes the working directory to the new top directory. Use <a
href="#pushd"><tt>pushd</tt></a> to add directories to the stack.
`popd` removes the top directory from the directory stack and changes the working directory to the new top directory. Use <a href="#pushd">`pushd`</a> to add directories to the stack.
Posix shells 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. \c psub combined with a
regular command substitution provides the same functionality.
Posix shells 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.
If the `-f` or `--file` switch is given to `psub`, `psub` will 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.
If the \c -f or \c --file switch is given to <tt>psub</tt>, \c psub will use a
regular file instead of a named pipe to communicate with the calling
process. This will cause \c 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.
\subsection psub-example Example
<tt>diff (sort a.txt|psub) (sort b.txt|psub)</tt> shows the difference
between the sorted versions of files a.txt and b.txt.
\fish
diff (sort a.txt | psub) (sort b.txt | psub)
# shows the difference between the sorted versions of files `a.txt` and `b.txt`.
\section pushd pushd - push directory to directory stack
\subsection pushd-synopsis Synopsis
<tt>pushd [DIRECTORY]</tt>
\fish{synopsis}
pushd [DIRECTORY]
\endfish
\subsection pushd-description Description
The <tt>pushd</tt> function adds \c DIRECTORY to the top of the directory stack
and makes it the current working directory. <a href="#popd"><tt>popd</tt></a> will pop it off and
return to the original directory.
The `pushd` function adds `DIRECTORY` to the top of the directory stack and makes it the current working directory. <a href="#popd">`popd`</a> will pop it off and return to the original directory.
\c random outputs a random number from 0 to 32766, inclusive.
`random` outputs a random number from 0 to 32766, inclusive.
If a `SEED` value is provided, it is used to seed the random number generator, and no output will be produced. This can be useful for debugging purposes, where it can be desirable to get the same random number sequence multiple times. If the random number generator is called without first seeding it, the current time will be used as the seed.
If a \c SEED value is provided, it is used to seed the random number
generator, and no output will be produced. This can be useful for debugging
purposes, where it can be desirable to get the same random number sequence
multiple times. If the random number generator is called without first
seeding it, the current time will be used as the seed.
\subsection random-example Example
The following code will count down from a random number to 1:
<pre>
\fish
for i in (seq (random) -1 1)
echo $i
sleep
echo $i
sleep
end
</pre>
\endfish
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
