The readlink() function does not null terminate the path it returns.
Remove the OS X code that deals with a path buffer that is too short. For
one thing a loop isn't needed since we're told how big of a buffer
is required if the first _NSGetExecutablePath() call fails. But more
important it is so unlikely that the path will be longer than PATH_MAX
that if it is we should just give up.
Fixes 2931.
(cherry picked from commit 8e103c231e)
This code represents only risk and does nothing useful for anything
that can compile fish.
In C++ situations where __STDC_VERSION__ is unset (as it should be),
fish was assuming we are on < C99 and setting it to __FUNCTION__.
Basically always, __PRETTY_FUNCTION__ ends up reaplaced by __FUNCTION__, this hurt
error message usefulness and richness.
__PRETTY_FUNCTION__: const thing::sub(int)
__FUNCTION__: sub
Prior to this fix, when completing a command that doesn't have a /, we
would prepend each component of PATH and then expand the whole thing. So
any special characters in the PATH would be interpreted when performing
tab completion.
With this fix, we pull the PATH resolution out of complete.cpp and
migrate it to expand.cpp. This unifies nicely with the CDPATH resolution
already in that file. This requires introducing a new expand flag
EXPAND_SPECIAL_FOR_COMMAND, which is analogous to EXPAND_SPECIAL_CD
(which is renamed to EXPAND_SPECIAL_FOR_CD). This flag tells expand to
resolve paths against PATH instead of the working directory.
Fixes#952
I believe apm must have been buggy - example output that I found online
showed `tr` was mangling paths with spaces in it. Should be fixed.
Also, use dscl on OS X in __fish_complete_users.fish like
__fish_print_users.fish already does.
When determining the old path, get the existing value in any scope,
not just the set scope. Also only complain about absolute paths:
relative paths are expected to be invalid sometimes.
Modify `fish_indent` to emit redirections without a space before the target of
the redirection; e.g., "2>&1" rather than "2>& 1" as the former is clearer to
humans.
Fixes#2899
Include information about how to deal with lint warnings and suppress
`clang-format` reformatting of blocks of code.
Move information only relevant to developers from the README.md to the
CONTRIBUTING.md document.
Closes#2901
I didn't notice when I merged commit cb6d5d76c8
by thebespokepixel.com that it removed the explicit wrapping in the `string`
man page. That makes `man string` harder to read so reinstate the explicit
wrapping.
This changes implements two new make targets: `style` and `style-all`. These
make it easy to ensure that a change conforms to the project style guides for
C++ and fish code.
Fixes#571
Per discussion in pull-request #2891, it's not available on Linux (we just
fill it with zero), and unless run as root on OS X (or other BSD system) it
will be zero. Remove it from file_id_t. Also fix the initialization of the
file_id_t structure.
Fixes#2891
- Add options to the autotools build to set the path for the "vendor"
or "extra" configuration snippets, functions and completions
directories.
- Remove the vendor_completions directory from the Xcode build, as
these are relocatable and compiling the paths in does not make sense.
This allows packaging tools like Homebrew and Nix to use a common
directory outside of the main prefix for third-party completions, and
to make these available for programmatic discovery through `pkg-config`.
Closes#2113
Closes#2699
Fixes issues with:
* 'string' function synopsis
* Redirection display issues
* Better file & path detection
* Rendering of % & @ chars in both html and man
* @ symbol in tutorial
Improves robustness by implementing an @EOL marker to prevent hold buffer dumping extra chars after the end of an expression.
Added new '{{' and '}}' meta-chars for when you want curly braces in a regexp that was previously tripping up the lexicon.
Improve man/html presentation consistency for
* string
* printf
* prompt_pwd
* type
Use cli-styling for 'practical' examples.
Add <bs> tag for presenting content with preceding backslash.
Signed-off-by: Mark Griffiths <mark@thebespokepixel.com>
This is a quick and dirty conversion of the atypical, and undocumented,
logging done by env_universal_common.cpp to the usual `debug()` pattern. I
didn't want to drop the messages because they could be useful when
debugging future issues. So I simply converted them to the lowest debug
level using the normal debug() function.
Fixes#2887
Cppcheck has identified a lot of unused functions. This removes funcs that
are unlikely to ever be used. Others that might be useful for debugging I've
commented out with "#if 0".
Commit c0e8ad6 on 2015-10-02 to "Make vi bindings inherit the defaults"
inadvertently reverted commit b6b6de3. Fix that regression. And while I
hate to make "git blame" say I changed the entire file make the function
adhere to fish_indent style.
Since #2849 was merged, there are no further leaks detected by the
address sanitiser. This makes it a good target to enable for Travis,
which will enable regression testing.
Closes#2851.
Only match loaded modules when -r is specified.
Also adds /lib/modules/(uname -r)/misc to the search path.
This directory is used by Gentoo for package-provided modules
(such as the app-emulation/virtualbox-modules)
This fixes all memory leaks found by compiling with
clang++ -g -fsanitize=address and running the tests.
Method:
Ensure that memory is freed by the destructor of its respective container,
either by storing objects directly instead of by pointer, or implementing
the required destructor.
The existing implementation grows the $dirprev array without bounds. Besides
causing what would appear to be a memory leak it also makes the nextd and
prevd commands more expensive than they need to be. It also makes it harder to
create a useful "menu" cd command.
In addition to implementing a reasonable limit on the size of the $dirprev
array I've reformatted the code using fish_indent.
Update the documentation to include mentions of the $dirprev and $dirnext
variables as well as the limit on how much directory history is kept.
Fixes 2836
When explicitly asking for the fish version string the information
should go to stdout rather than stderr. Also, there is no reason to use
exit_without_destructors() rather than exit() in that code path. We
actually want the side-effects of exit() such as flushing stdout and
there aren't any threads or other things that could cause a normal exit
to fail when that function is run.
The early return skipped all cleanup.
This problem is a case for the classic "goto fail" paradigm, but this
change instead makes a few adjustments to take advantage of a previously
unused level of indentation to conditionally execute the success path.
The error message now prints the filename instead of "open",
which should be more idiomatic.
Tip:
This patch makes sense if viewed with `git show --ignore-space-change`.
The swap-selection-start-stop function goes to the other end of the highlighted text, the equivalent of `o' for vim visual mode.
Add binding to the swap-selection-start-stop function, `o' when in visual
mode.
Document swap-selection-start-stop, begin-selection, end-selection, kill-selection.
The relevant standards allow the mbtowc/mbrtowc functions to reject
non-ASCII characters (i.e., chars with the high bit set) when the locale
is C or POSIX. The BSD libraries (e.g., on OS X) don't do this but
the GNU libraries (e.g., on Linux) do. Like most programs we need the
C/POSIX locales to allow arbitrary bytes. So explicitly check if we're
in a single-byte locale (which would also include ISO-8859 variants)
and simply pass-thru the chars without encoding or decoding.
Fixes#2802.
The u_int typedef fails to compile on all platforms (e.g. Windows). It
is part of the code imported from tmux.
Update it to the SUS-standard uid_t.
Closes#2821.
The u_int typedef fails to compile on all platforms (e.g. Windows). It
is part of the code imported from tmux.
Update it to the SUS-standard uid_t.
Closes#2821.
Address the feedback from the prior commit:
- Change the sense of return value testing to match more common
comparison idiom
- Test result of fchmod as well as fchown
- Change sense of return value testing around wrename as well
- Include errno where possible in error message
The function fchown is annotated with warn_unused_result. As
formerly used in the code, it would emit a compiler warning
```warning: ignoring return value of ‘fchown’, declared with
attribute warn_unused_result [-Wunused-result]```
This commit notes the return value and emits appropriate error/logging
messages if the call fails, creating more traceable results and
satisfying the compiler.
instead add a bit of information on how fish's configuration works for
the admin to etc/config.fish.
This means that fish is fully functional without /etc, which might be nice for "stateless" systems.
There is no longer a good reason to detect whether or not getopt_long()
is available. All UNIX implementations we're likely to run on have it. And
if we ever find one that doesn't the right thing to do is not fallback to
getopt() but to include the getopt_long() source in our package like we
do with the pcre2 library. Since it's licensed under LGPL we can legally
do so if it becomes necessary.
This partially addresses issue #2790.
Previously, when decoding UTF-8, we would first run through the
array to compute the correct size, then allocate a buffer of that size,
then run through the array again to fill the buffer, and then copy it
into a std::wstring. With this fix we can copy it into the string
directly, reducing allocations and only requiring a single pass.
We silently upgrade existing abbreviations and change the separator when
saving.
This does not yet warn when the user is using the old syntax.
Resolves#2051
This narrows the range of Unicode codepoints fish reserves for its own
use from U+E000 thru U+F8FE (6399 codepoints) to U+F600 thru U+F73F (320
codepoints). This is still not ideal since fish shouldn't be using any
Unicode private-use codepoints but it's a step in the right direction.
This partially addresses issue #2684.
Turns out some shells will alias which to be something function-aware,
but doing this on fish would blow up because it would call type which
would then call which which would then call type....
Fixes#2775
This was used to cache a narrow string representation
of commands, so that if certain system calls returned errors
after fork, we could output error messages without allocating
memory. But in practice these errors are very uncommon, as are
commands that have wide characters. It is simpler to do a best-effort
output of the wide string, instead of caching a narrow string
unconditionally.
Prior to this fix, read_ni would use parse_util_detect_errors
to lint the script to run, and then parser_t::eval() to execute it.
Both functions would parse the script into a parse tree. This allows
us to re-use the parse tree, improving perfomance.
Introduces a new template moved_ref which is like an rvalue reference.
This allows passing around objects while being explicit that the
receiver may acquire ownership. This will help reduce some allocations.
Much better to only encode the characters that are not URL-safe. This
also doesn't involve any forking, and it even handles newlines and NULs
in the input.
This is a file under version control, there's no reason it should be
listed here. Having it in .gitignore was causing tools like `ag` to
avoid looking at share/config.fish.
This allows "vendors" (i.e. third-party upstreams interested in
supporting fish) to add auto-loaded functions and eager-loaded
configuration "snippets", while still allowing both the user and the administrator to
fully override all of that.
This has been inspired by systemd's configuration hierarchy, and implements a similar scheme
whereby files with the same name in higher-ranking directories override files in lower-ranking ones.
Fixes#1956
I noticed while fixing issue #2702 that the fish program being tested
was sourcing config.fish files outside of the current build. This also
happens when Travis CI runs the tests but isn't an issue there because
of how Travis is configured to execute the tests.
I also noticed that running `make test` was polluting my personal fish
history; which will become a bigger problem if and when the fishd universal
var file is moved from $XDG_CONFIG_HOME to $XDG_DATA_HOME.
This change makes it possible for an individual to run the tests on
their local machine secure in the knowledge that only the config.fish and
related files from their git repository will be used and doing so won't
pollute their personal fish history.
Resolves#469
pcre2_substitute() now sets the output buffer length to PCRE2_UNSET (~0)
if the output buffer is determined to be too small. This change keeps
track of the buffer size separately where pcre2 can't touch it.
A better fix would be to let pcre2 tell fish what size buffer it needs.
This can be done with PCRE2_SUBSTITUTE_OVERFLOW_LENGTH, but this
requires pcre2 10.21 or later (released January 12), which may be too
new to introduce as a dependency at this point.
Fixes#2743
* When using a UTF-8 locale, set locale to C temporarily in order to
read one byte at a time.
* Use the builtin printf in a forward-compatible way. (GNU)
* Improve the readability of the code.
I've run this more than twenty times through Travis CI (by adding/removing
a comment line). Without this tweak the longest sequence seems to be
around six successful runs.
Expand globs to zero arguments (nullglob) only for set, for and count.
The warning about failing globs, and setting the accompanying $status,
now happens regardless of mode, interactive or not.
It is assumed that the above commands are the common cases where
nullglob behaviour is desirable.
More importantly, doing this with `set` is a real feature enabler,
since the resulting empty array can be passed on to any command.
The previous behaviour was actually all nullglob (since commit
cab115c8b9), but this was undocumented;
the failglob warning was still printed in interactive mode,
and the documentation was bragging about failglob behaviour.
Fixes the invocation of a user-specified browser by the `help` command on Cygwin.
- Use `cygstart` to launch the browser with escaped quotes to avoid problems with spaces in the path to the browser, (e.g. Program Files).
- Use `cygpath` to convert the base help dir to a Windows path before constructing the fie URL to pass to the browser.
The values for notification hooks remain available as comments, but this
prevents notifications from other repositories from automatically being
linked across to the official notification channels.
The argv argument may be modified on calls to exchange within the function and should not be const qualified (it's not true from the caller's point of view).
On arm, wchar_t is unsigned, and C++11 and newer disallow implicit
narrowing conversions inside braces. Use an explicit conversion to
fix the build on GCC 6 and up, which defaults to C++11.
This changes the default escape timeout for the default keybindings (emacs
mode) to 300ms and the default for vi keybindings to 10ms.
I couldn't resist fixing a few nits in the fish_vi_key_bindings.fish file
since I was touching it to set the escape timeout.
All versions of fish prior to this change silently discarded anything written
to stderr while source a config.fish file. Apparently just to avoid having
the source command display an error if the file did not exist. This can mask
real problems. So instead this change explicitly checks whether the file is
readable and silently skips sourcing it if it isn't.
Resolves issue #2702.
This fixes all but one of the warnings documented in issue #2685. The
sole remaining warning is from the
string split '' abc
example in doc_src/string.txt. That example results in the man page
displaying
string split {} abc
I leave it to someone else to fix that problem (I'll open an issue
specifically for it since it took some effort to track down the source
of the warning).
Resolves issue #2685.
It used to be that way and we recommend `set fish_greeting` (i.e. set to
empty) in the docs - possibly since we check if the variable is defined
on upgrade.
My previous commit failed in the travis-ci environment despite passing on my
local computer. This appears to be due to expect timing out looking for the
expected input. See if increasing the expect timeout slightly fixes the
problem.
Introduce a "fish_escape_delay_ms" variable to allow the user to configure the
delay used when seeing a bare escape before assuming no other characters will
be received that might match a bound character sequence. This is primarily
useful for vi mode so that a bare escape character (i.e., keystroke) can
switch to vi "insert" to "normal" mode in a timely fashion.
Rather than storing short and long options separately, using
a complicated set of invariants, store them in a single string
and use an explicit type complete_option_type_t to track how they
are interpreted.
This was a "cache" of dubious value that was also very confusing.
The idea was to express in one place all of the short options that
were allowed for a command, in a big string. But it's simpler to
just construct that on-demand by walking the list of
complete_entry_opt_t.
Also remove some other dead code as part of cleanup.
This is meant to make it clear that fish cannot control the terminal
window background color. It also augments the set_color documentation to
describe how it decides which color the terminal can display.
Resolves#2421.
Resolves#2184.
To implement this mostly as a wrapper around pactl, we add the list of
commands for this to that. It's 90% the same anyway. (This means that
`pactl suspend ` will complete files instead of commands like `pactl
banana ` would, but neither is correct)
This fails on e.g. an abbr that uses `env a=b`, like the included test demonstrates.
Unfortunately it decreases the speed again (2s vs 2.2s vs 4s original),
but correctness is more important.
- Replace __fish_abbr_escape with `string escape`
- Don't double-parse the key
- Replace IFS magic with string
Together, this seems to speed it up by a factor of about 2.
Unfortunately, nvim will, even when running in a terminal that supports
it, swallow the sequences whole, rendering the displayed text _white_.
This means falling back to 256 colors is the lesser evil as at least a
blue-ish color will display as blue while a red-ish will be red, instead
of both showing white.
nvim's behavior does _not_ change depending on
$NVIM_TUI_ENABLE_TRUE_COLOR or any other option I could find and neovim-qt
exhibits the same behavior.
Fixes#2600.
The fix for #2075 inadvertently started unescaping the strings emitted
from `commandline -b`. Only strings emitted with the `-o` flag are
supposed to be unescaped.
Fixes#2210.
If you have a prompt preceded by a new line, you'll get a line full of spaces instead of an empty line above your prompt. This doesn't make a difference in normal usage, but copying and pasting your terminal log becomes a pain. This commit clears that line, making it an actual empty line.
The random builtin command may or may not produce values with a truly
random distribution. So make the documentation reflect that reality. Also,
make the command consistent with similar shells (e.g., bash, zsh) which
produce a range of [0..32767].
Resolves issue #1272.
Before this change, `fish ./test.fish` would fully resolve the
relative paths and symlinks of test.fish, as reported by `status -f`.
However `source` would not. With this change, both cases return relative
paths. `realpath` may be used by scripts to resolve them.
Fixes#2643
This patch is currently floated from the NixOS side as part of
https://github.com/NixOS/nixpkgs/pull/12000, but prior versions of the
hook ignore anything but the first argument anyway, so this is
backwards-compatible.
* Add a note to the `--wrap` docs saying that wrapping only works when
specifying completions for commands, not for paths.
* Add more info about how `--arguments` is handled.
* Indicate which options can be repeated in the usage lines.
* Reorder the options in usage slightly to group better.
* Reorder the option descriptions to match the order as seen in usage.
* Update some of the option descriptions.
* Fix the documentation for -C to show that it must be `-CSTRING`
instead of `-C STRING`.
* Document the behavior of `-C` with no argument.
* Tweak some of the explanatory text after the option list.
* Delete `--authoritative` and `--unauthoritative` from the
documentation entirely. Those options appear to not actually do
anything in the new parser.
This skips the weird dance where we'd define a simple handler and then
later overwrite with a fancier one, once the first event came in.
It turns out that isn't necessary, as it doesn't actually improve
startup speed because the checks needed to define fancier handlers are fast.
In case we are non-interactive, still define the simple handler, and
keep the default handler for users to switch to.
My PR #2578 had the unexpected side-effect of altering the tty modes of
commands run via "fish -c command" or "fish scriptname". This change fixes
that; albeit incompletely. The correct solution is to unconditionally set
shell tty modes if stdin is attached to a tty and restore the appropriate
modes whenever an external command is run -- regardless of the path used to
run the external command. The proper fix should be done as part of addressing
issues #2315 and #1041.
Resolves issue #2619
Increase the delay between seeing an escape character and giving up on
whether additional characters that match a key binding are seen. I'm
setting the value to 500 ms to match the readline library. We don't need
such a large window for sequences transmitted by a terminal (even over ssh
where network delays can be a problem). However, we can't expect humans to
reliably press the escape key followed by another key with an inter-char
delay of less than ~250 ms based on my testing and research. A value of
500 ms provides a nice experience even for people using "fish_vi_mode"
bindings as a half second to switch from insert to normal mode is still
fast enough that most people won't even notice.
Resolves#1356
While investigating issue #2619 my first thought was that the problem
had something to do with the "is_interactive_session" global variable.
That preliminary conclusion appears to be wrong (i.e., the problem
lies elsewhere). However, that hypothesis caused me to look at function
"fish_parse_opt" and other mentions of "is_interactive_session".
I decided to take the opportunity to simplify and improve the style of
"fish_parse_opt" since I just spent an hour reviewing the code that
references "is_interactive_session". For example, the "has_cmd" variable
isn't really needed. And there is inconsistent whitespace not to mention
confusion about bool's versus int's and zero versus NULL.
Rather than returning a list of productions and an index,
return the relevant production directly from the rule function.
Also introduce a tag value (replacing production_idx) which tracks
information like command decorations, etc. with more clarity.
That's probably the part where commit hashes are most used, we can add
the other subcommands later.
This generates a _lot_ of options, so hooking it up everywhere would be
unwise, though our pager helps quite nicely with filtering - typing
"Branch" will filter out the commits, and typing other things will
filter the subjects, which is quite cool.
This turns '\040' into a space. /etc/mtab also supports other
escapes ("\\" for backslash, "\011" for tab), but I can't find
documentation for those in fstab.
When replacing the existing fish process with a new process it is
important to restore the temrinal modes to what they were when fish
started running. We don't want any tweaks done for the benefit of fish
(e.g., disabling ICRNL mode) to bleed thru to an "exec"ed command.
Resolves#2609
This adds blockdevices (and directories) and fixes the regexes to no
longer include comments but include UUID= and LABEL=, which at least
util-linux mount understands.
It also shouldn't fail on systems without fstab any longer (like default OSX).
Fixes#2606.
* Add missing options to `git clone` in order to make the suggestions as
similar to the manual (https://git-scm.com/docs/git-clone) as
possible.
Signed-off-by: mr.Shu <mr@shu.io>
Unfortunately, there's no standard way to detect support (importantly,
terminfo doesn't encode it), but there's a variety of terminals that
support it that we can detect.
It's better than letting this functionality go to waste.
Check KONSOLE_PROFILE_NAME instead of DBUS_SESSION because Konsole can be compiled without dbus support.
Check ITERM_SESSION_ID's format for 24bit support
This has changed since the last release, just like 24bit support. So if
we check one, we get the other.
If stdio is dead due to EPIPE, there's no great reason to spew a stack dump.
This will still write an error to stderr if stdout dies. This might be
undesirable, but changing that should be considered separately.
It is critical that we ensure our interactive tty modes are in effect at
the earliest possible moment. This achieves that goal and is harmless if
stdin is not tied to a tty. The reason for doing this is to ensure that
\r characters are not converted to \n if we're running on the slave side
of a pty controlled by a program like tmux that is stuffing keystrokes
into the pty before we issue our first prompt.
The special token "normal" should not be in the basic sixteen color table
because a) it is not a color, and b) it is special cased with the result of
resetting the terminal colors (usually via a ANSI X3.64 CSI [0m sequence).
This adds support for the ANSI x3.64 "bright" colors in the basic sixteen
color palette. This is especially useful when trying to use the base colors
as a background color. The "bright" variants tend to be more useful as
background colors compared to the non-bright variants.
This also fixes a bug in so far as palette number 7 is actually grey and
not white whereas palette number 15 is white. At least on the terminal
emulators on which I've tested this change (Ubuntu xterm & uxterm, Mac
OS X Terminal & iTerm2).
Resolves issue #1464.
* Make sure that the `git remote` subcommands are not repeatedly
suggested (that is do not suggest a subcommand if there already is one).
* Add both long and short options to `git remote` subcommands where
appropriate.
Signed-off-by: mr.Shu <mr@shu.io>
This does a number of things:
- Removing trailing space from suggested repos for hg.
- Use the string builtin for hg completions.
- Add more internal merge tools to hg completion.
- Enable completions for abbreviated hg commands.
- Stop completing a deprecated hg branches option.
- Properly match the hg subcommand when preceeded by global switches.
- Stop completing deprecated hg glog.
- Complete hg config instead of showconfig.
- Properly complete when global switches are before the hg command.
- Properly handle the repository switch for hg completions.
- Properly handle the hg global switch cwd.
We identify when the universal variable file has changed out from under us by
comparing a bunch of fields from its stat: inode, device, size, high-precision
timestamp, generation. Linux aggressively reuses inodes, and the size may be
the same by coincidence (which is the case in the tests). Also, Linux
officially has nanosecond precision, but in practice it seems to only uses
millisecond precision for storing mtimes. Thus if there are three or more
updates within a millisecond, every field we check may be the same, and we are
vulnerable to the ABA problem. I believe this explains the occasional test
failures.
The solution is to manually set the nanosecond field of the mtime timestamp to
something unlikely to be duplicated, like a random number, or better yet, the
current time (with nanosecond precision). This is more in the spirit of the
timestamp, and it means we're around a million times less likely to collide.
This seems to fix the tests.
Currently if there is a conflict with two manpages having the same
name, one completion will override the other. But if one can be parsed
and the other can't the one with parsed results will always have a
higher priority.
It seems smart to only let files be parsed that are clearly
manpage files. Other files wouldn't be openend by man so
I think it is safe to guess that only these files are man
pages.
input_mapping_execute, when passed false for allow_commands, will return
R_NULL. However currently it does this unconditionally, even if we don't
have any commands. This defeats our read-ahead optimization, so we
always read and process one byte at a time. This caused pasting to be
much slower.
Fixes#2215
If we are cd'ing into a directory, and the directory has only one
child which is itself a directory, the autosuggestion should
descend as far as it can.
Fixes#2531
Allows the length of each shortened path component to be customized by setting the `fish_prompt_pwd_dir_length` variable to the number of characters to include (plus a leading dot because that's special). Maintains the default behavior of shortening path components to just one character. You can also set `fish_prompt_pwd_dir_length` to an empty or invalid value or 0 to disable shortening completely.
Previously 'set -ql' would only look for variables in the
immediate local scope. This was not very useful. It's also
arguably surprising, since a 'set -l' in a function, followed
by a 'set -ql' in a child block, would fail. There was also no
way to check for a function-scoped variable, since omitting the
scope would also pull in global variables.
We could revisit this and introduce an explicit function scope.
Fixes#2502
This isn't pretty, but it fails for, as far as I can see, no _real_
reason.
It doesn't seem to be possible to trigger the failure in real usage, no
matter how fast you press the ESC key followed by something else.
So now this is known and constant travis emails don't help it in any way.
New implementation of migration code within the history_t class will
copy the contents of the old fish_history found in the config directory
to its new location in the data directory. The old file is left intact.
This is done only in the event that a fish_history is not already found in
the data directory ($XDG_DATA_HOME/fish or ~/.local/share/fish).
The fish_history file is now located in the "data"
directory ($XDG_DATA_HOME/fish or ~/.local/share/fish),
accessible using the function `path_get_data`.
(This commit also cleans trailing whitespace in the source file.)
Add new functions path_get_data and path_create_data which parallel existing
functions path_get_config and path_create_data. The new functions refer to
XDG_DATA_HOME, if it is defined, or ./local/share if not.
Modify history_filename to use the new function path_get_data.
As a consequence, fish_history will now be located in XDG_DATA_HOME,
not XDG_CONFIG_HOME.
Note that these changes mirror what is already used in
fish-shell/share/tools/create_manpage_completions.py, which stores the
completions in XDG_DATA_HOME
This change matches recommendations in the xdg basedir spec at
http://standards.freedesktop.org/basedir-spec/basedir-spec-0.7.html
($XDG_DATA_HOME defines the base directory relative to which user specific data
files should be stored. If $XDG_DATA_HOME is either not set or empty, a default
equal to $HOME/.local/share should be used.)
It addresses suggestions from the following issues:
1. Don't put history in $XDG_CONFIG_HOME (closes#744)
https://github.com/fish-shell/fish-shell/issues/744
2. Fish is placing non-config files in $XDG_CONFIG_HOME #1257https://github.com/fish-shell/fish-shell/issues/1257
3. Move non-config data out of $XDG_CONFIG_HOME #1669https://github.com/fish-shell/fish-shell/issues/1669
This reduces code duplication and adds some previously unavailable
bindings that don't quite _violate_ the vi-principle (like
prevd-or-backward-word on alt-left) and matches other "impure" bindings
like \cf for forward-word (a quite emacs-ish binding) we already have.
Fixes#2412Fixes#2472Fixes#2255
For cygwin, you can't `cd C:`, so a prompt of "C:/Something" is
misleading.
For OSX, we dereference symlinks elsewhere
This also simplifies prompt_pwd quite a bit.
Instead of duplicating the script invocation across targets,
put it into a separate target and add dependencies. This also
requires moving its output into the SHARED_DERIVED_FILE_DIR
(which may be undocumented)?
Not for _everything_ because that causes too many options to be
generated (which is an issue for git as it is), but for modified, staged
and added files - which is where it is most useful.
Fixes#901 as far as I'm concerned.
git has options that can appear before commands, but not all of
them, and some of them need an argument. This means
`__fish_seen_subcommand_from` will give too many false-positives, while
`[ (count $cmd) -eq 2 ]` will give too many false-negatives.
Instead go through all arguments and check if they are in that list of
options that can be before a command and skip the argument for them, if
any.
Teach Xcode to run new script xcode_version_gen.sh before building
the fish_shell and fish_indent targets. The script generates file
fish-build-version.h for inclusion by fish_version.cpp.
Note that Xcode always runs the script because of the phony target
named force-fish-build-version.h, but fish-build-version.h is only
touched if the contents of FISH-BUILD-VERSION-FILE change.
Fixes#890
This is to the benefit of systems with ancient GNU sed, which does not
recognize "-E", but only "-r".
Fixes#2305 - even if it doesn't replace all `sed -E` invocations in the
codebase, the others are unlikely to occur on CentOS and other similarly
crusty systems.
`__fish_apm_using_command` was incorrectly taking lists of commands, new function added to support multiple a command having synonyms.
Simplify switch statement
Also remove superfluous function.
Allow for multiple completions after a command
Useful for removing packages, will complete for more than one.
Code improvements
`sort -u | uniq` is completely redundant, calling grep for every
status-pair is unnecessary, `contains` doesn't take the word "in" as
special.
None of these are critical and there's basically no performance benefit
since this function is utterly dominated by hg calls.
This doesn't add anything except slowing the function down by about
33%. Checking for a branch is just as good and that is displayed in the
prompt anyway.
commit 33c7c4df307b144652d6d842472aa843cc6a5420
Author: Ian Ray <ianjray@me.com>
Date: Sat Sep 26 21:28:50 2015 +0300
Fix xcode include paths for pcre2.h
commit 03d255a3e5e2e9b109c0bc6789ffa431381b6cb3
Author: Ian Ray <ianjray@me.com>
Date: Sat Sep 26 21:02:42 2015 +0300
Fix xcode include paths for pcre2.h
According to the newer code below:
xdg_data_home = os.getenv('XDG_DATA_HOME', '~/.local/share')
the actual default path is ~/.local/share/fish/generated_completions/
This is used in at least 4 places, all of which have a bug in that they
print "options" as a valid repo. It seems better to fix it once,
especially given that there are tons of AUR helpers and pacman wrappers,
all of which might need this info.
net_tools, which provides `ifconfig` and `netstat`, among other things,
has last been updated in 2013. This means `ifconfig` on linux is
basically dead.
Instead of ifconfig, use `ip` (from iproute2), which is much more powerful and
provides a much more annoying commandline syntax.
Instead of netstat, just look at /sys/class/net.
This change eliminates global variables like stdout_buffer. Instead we wrap up
the IO information into a new struct io_streams_t, and thread that through
every builtin. This makes the intent clearer, gives us a place to hang new IO
data, and eliminates the ugly global state management like builtin_push_io.
This adds the new builtin 'string' which supports various string
manipulation and matching algorithms, including PCRE based regular
expressions.
Fixes#2296
Squashed commit of the following:
commit 4c3eaeb6e57d76463e9683c327142b0aeafb92b8
Author: ridiculousfish <corydoras@ridiculousfish.com>
Date: Sat Sep 12 12:51:30 2015 -0700
Remove testdata and doc dirs from pcre2 source
commit b2a8b4b50f2398b204fb72cfe4b5ba77ece2e1ab
Merge: 11c8a477974aab
Author: ridiculousfish <corydoras@ridiculousfish.com>
Date: Sat Sep 12 12:32:40 2015 -0700
Merge branch 'string' of git://github.com/msteed/fish-shell into string-test
commit 7974aab6d3
Author: Michael Steed <msteed@saltstack.com>
Date: Fri Sep 11 13:00:02 2015 -0600
build pcre2 lib only, no docs
commit eb20b43d2d
Merge: 1a09e705f519cb
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Sep 10 20:00:47 2015 -0600
Merge branch 'string' of github.com:msteed/fish-shell into string
commit 1a09e709d0
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Sep 10 19:58:24 2015 -0600
rebase on master & address the fallout
commit a0ec9772cd
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Sep 10 19:26:45 2015 -0600
use fish's wildcard_match() for glob matching
commit 64c25a01e3
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Aug 27 08:19:23 2015 -0600
some fixes from review
- string_get_arg_stdin(): simplify and don't discard the argument when
the trailing newline is absent
- fix calls to pcre2 for e.g. string match -r -a 'a*' 'b'
- correct test for args coming from stdin
commit ece7f35ec5
Author: Michael Steed <msteed68@gmail.com>
Date: Sat Aug 22 19:35:56 2015 -0600
fixes from review
- Makefile.in: restore iwyu target
- regex_replacer_t::replace_matches(): correct size passed to realloc()
commit 9ff7477a92
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Aug 20 13:08:33 2015 -0600
Minor doc improvements
commit baf4e096b2
Author: Michael Steed <msteed68@gmail.com>
Date: Wed Aug 19 18:29:02 2015 -0600
another attempt to fix the ci build
commit 896a2c2b27
Author: Michael Steed <msteed68@gmail.com>
Date: Wed Aug 19 18:03:49 2015 -0600
Updates after review comments
- make match/replace without -a operate on the first match on each
argument
- use different exit codes for "no operation performed" and errors, as
grep does
- refactor regex compile code
- use human-friendly error messages from pcre2
- improve error handling & reporting elsewhere
- add a few tests
- make some doc fixes
- some simplification & cleanup
- fix ci build failure (I hope)
commit efd47dcbda
Author: Michael Steed <msteed68@gmail.com>
Date: Wed Aug 12 00:26:07 2015 -0600
fix dependencies for parallel make
commit ed0850e2db
Author: Michael Steed <msteed68@gmail.com>
Date: Tue Aug 11 23:37:22 2015 -0600
Add missing pcre2 files + .gitignore
commit 9492e7a7e9
Author: Michael Steed <msteed68@gmail.com>
Date: Tue Aug 11 22:44:05 2015 -0600
add pcre2-10.20 and update license.hdr
commit 1a60b93371
Author: Michael Steed <msteed68@gmail.com>
Date: Tue Aug 11 22:41:19 2015 -0600
add string builtin files
- string builtin source, tests, & docs
- changes to configure.ac & Makefile.in
commit 5f519cb2a2
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Sep 10 19:26:45 2015 -0600
use fish's wildcard_match() for glob matching
commit 2ecd24f795
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Aug 27 08:19:23 2015 -0600
some fixes from review
- string_get_arg_stdin(): simplify and don't discard the argument when
the trailing newline is absent
- fix calls to pcre2 for e.g. string match -r -a 'a*' 'b'
- correct test for args coming from stdin
commit 45b777e4dc
Author: Michael Steed <msteed68@gmail.com>
Date: Sat Aug 22 19:35:56 2015 -0600
fixes from review
- Makefile.in: restore iwyu target
- regex_replacer_t::replace_matches(): correct size passed to realloc()
commit 981cbb6ddf
Author: Michael Steed <msteed68@gmail.com>
Date: Thu Aug 20 13:08:33 2015 -0600
Minor doc improvements
commit ddb6a2a8fd
Author: Michael Steed <msteed68@gmail.com>
Date: Wed Aug 19 18:29:02 2015 -0600
another attempt to fix the ci build
commit 1e34e3191b
Author: Michael Steed <msteed68@gmail.com>
Date: Wed Aug 19 18:03:49 2015 -0600
Updates after review comments
- make match/replace without -a operate on the first match on each
argument
- use different exit codes for "no operation performed" and errors, as
grep does
- refactor regex compile code
- use human-friendly error messages from pcre2
- improve error handling & reporting elsewhere
- add a few tests
- make some doc fixes
- some simplification & cleanup
- fix ci build failure (I hope)
commit 34232e152d
Author: Michael Steed <msteed68@gmail.com>
Date: Wed Aug 12 00:26:07 2015 -0600
fix dependencies for parallel make
commit 00d7e78169
Author: Michael Steed <msteed68@gmail.com>
Date: Tue Aug 11 23:37:22 2015 -0600
Add missing pcre2 files + .gitignore
commit 4498aa5f57
Author: Michael Steed <msteed68@gmail.com>
Date: Tue Aug 11 22:44:05 2015 -0600
add pcre2-10.20 and update license.hdr
commit 290c58c72e
Author: Michael Steed <msteed68@gmail.com>
Date: Tue Aug 11 22:41:19 2015 -0600
add string builtin files
- string builtin source, tests, & docs
- changes to configure.ac & Makefile.in
net_tools, which provides `ifconfig` and `netstat`, among other things,
has last been updated in 2013. This means `ifconfig` on linux is
basically dead.
Instead of ifconfig, use `ip` (from iproute2), which is much more powerful and
provides a much more annoying commandline syntax.
Instead of netstat, just look at /sys/class/net.
Previously, the process's inherited $TERM value would be used.
This prevented users from being able to set $TERM in their config.fish files.
To make matters worse, the error message would print the computed $TERM value,
giving the mistaken impression that it was being used.
Signed-off-by: David Adam <zanchey@ucc.gu.uwa.edu.au>
fish_user_key_bindings is the user's, and they should know if they want
vi-ish bindings or emacs-ish (or nano-ish). If they want to define
multiple, they can also do that (e.g. via checking what
$fish_key_bindings is set to).
Fixes#2254
CC @kballard
This doesn't work with fish_config.
For terlar and pythonista, remove unnecessary color setting.
For informative+git and pythonista, move variable setup into fish_prompt
Fixes#1141
See #1925: This allows users to disable the cnf-logic which can be quite
slow on small hardware (like a raspberry pi).
Squashed commit of the following:
commit 742a59e30d8db24b6bb5067d4204d4b5cc01c1c3
Author: Fabian Homborg <FHomborg@gmail.com>
Date: Sun Aug 30 18:23:41 2015 +0200
Erase startup cnf-handler early
Simplifies the code a bit - in particular it removes the special-casing
from the startup handler.
commit 638a97e7f31f302b65e044c93c638c03a69e31f5
Author: Fabian Homborg <FHomborg@gmail.com>
Date: Mon Aug 24 20:14:46 2015 +0200
Make overriding cnf-handler work
Do this by renaming the __fish_command_not_found_handler used during
startup to __fish_startup_command_not_found_handler. That allows us to
check if __fish_command_not_found_handler has been defined and skip the
setup of the normal one.
Now disabling cnf-handling can be done via defining an empty
__fish_command_not_found_handler in config.fish
This adds a special colorscheme and prompt function guaranteed to work
on a VT and activates them automatically if $TERM = "linux".
set_color is overridden to only allow the 8 colors VTs have (under the
assumption those are always the same) and the color variables are
shadowed with global ones so they don't pollute our nice capable terms.
Cygwin FIFOs do not support more than one reader, so avoid them on this
platform. An autoconf feature test would be helpful but is tricky to
write.
Closes#2152.
This is already done by fish before calling the completion.
It breaks completion with combiners (#2025) and also with wrappers.
(This does not include git because that's better solved in #2145)
There are two main problems in the existing Fossil autocompletion that this
patch solves:
* Because Fossil lacks an alias system similar to those in Hg and Git,
wrapper scripts are common, and aliasing them to `fossil` is also fairly
common. The lack of the `command fossil` pattern in the completions script
meant that the actual fossil command might not be called, but rather the
alias. This problem has been fixed by introducing a __fish_fossil command,
similar to the __fish_hg and __fish_git commands in those completion shells,
that does this, and converting all explicit fossil calls in the completion
script to use __fish_fossil instead
* Because there's now a centralized location for calling Fossil, I also moved
all of the repetitive stderr redirects that function.
This results in more robust and cleaner code.
When an error occurs midway through a token, like abc(def,
make the caret point at the location of the error (i.e. the paren)
instead of at the beginning of the token.
In a few places, we need to add a prefix to completions that
replace the token. This change factors that logic into its
own function prepend_token_prefix.
This was too simplistic, among other things it completed things that
looked like key ids but weren't, didn't turn "\x3a" back into
colons (which made the argument invalid)....
gpg is weird.
Might fix#2150
Bit one: Make all the fossil command invocations throw away stderr so we don't
get annoying messages when not in a repository.
Also:
- Move checkout into alphabetical order.
- Fix ls to complete against tags for -r option, not no option.
- Add missing option to delete command.
- Make commit complete against modified files.
- Make add only complete against extra files.
- Remove now ununused function to list extra & modified files.
- Add -f option in a number of places where it seemd appropriate.
Rather than trying to detect Unicode support from the environment, check
the printable width of characters in the current locale before deciding
on whether to use them.
Closes#1927.
This is very ugly because makedepend has no native support
for building outside the source tree. It always wants to
prepend 'src/' to the object file path. So instead we have
to cons up a new source tree, with the sources files at the
root, and run makedepend on that.
This change moves source files into a src/ directory,
and puts object files into an obj/ directory. The Makefile
and xcode project are updated accordingly.
Fixes#1866
This change moves source files into a src/ directory,
and puts object files into an obj/ directory. The Makefile
and xcode project are updated accordingly.
Fixes#1866
__fish_complete_mime used in that way is a no-op on current fish anyway,
and emacs is by no means useful for just text files (it can also view
PDFs, images, ...).
Otherwise this completion currently only offers options, not arguments.
For most these are pretty much incompletable (lisp code, for example),
and for others it's just not all that useful.
Signed-off-by: David Adam <zanchey@ucc.gu.uwa.edu.au>
This used to be a function because we didn't have complete -w
Use that and it becomes a bit simpler.
This also simplifies the code in a few other ways (like removing a
useless-use-of-cat)
and adds comments about a few edgecases.
Declaring errno as an extern int breaks when errno is implemented
as a macro (as is allowed by POSIX). Specifically it breaks
building fish-shell on Android.
New sample prompt from Acidhub (github.com/acidhub)
This prompt show user|path (full), and a small symbol to
show last command status.
If in a git repository, it's show after the path several
symbols to indicate the branch status and the branch name.
Very handy to me so far.
Signed-off-by: Fernando Manfredi <contact@acidhub.click>
changed `function __trap_handler_EXIT --on-exit %self` to `function __trap_handler_EXIT --on-process-exit %self`
I'm guessing the on-exit syntax was from an older version? Trapping EXIT with that syntax caused errors.
The following behaviour is added:
- an empty pushd exchanges the top two directories in the stack;
- pushd +<n> rotates the stack so that the n-th directory (counting from the left of the list shown by dirs, starting with zero) is at the top;
- pushd -<n> rotates the stack so that the nth directory (counting from the right of the list shown by dirs, starting with zero) is at the top.
This reverts commit cd7f1a15f8.
Contemporary Cygwin systems provide the correct symlinks on both 32-bit
and 64-bit installations to allow the transparent use of libncursesw as
libncurses.
Reversion of #1454.
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
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.
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.
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
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
- Add four new functions: forward-bigword, backward-bigword,
kill-bigword, backward-kill-bigword
- Add new enum move_word_style_whitespace and related state machine
method
- Change vi key bindings to operate on bigwords: B, gE, W, E, dW, diW,
daW, dE, dB, dgE, cW, ciW, caW, cE, cB, cgE, yW, yiW, yaW, yE, yB,
ygE
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.
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.
Notification is sent using an OSC 777 escape sequence as described at
http://known.phyks.me/2014/local-notifications-for-weechat-and-urxvt.
The specific notification is crafted to match that emitted by bash
when running under Fedora 22 with the "vte-profile" RPM installed.
See the code for "__vte_prompt_command" starting at
http://pkgs.fedoraproject.org/cgit/vte291.git/tree/vte291-command-notify.patch#n307
to see exactly what bash produces. My approach is, however, a bit
more paranoid about control characters embedded in commands.
Gnome-terminal 3.16 responds to this escape sequence by posting a
desktop notification if the containing terminal window does not have
focus. This lets the user know that a long-running background command
has completed. Job notification is promoted as a Fedora 22 feature
(http://fedoramagazine.org/terminal-job-notifications-in-fedora-22-workstation/),
so it would be good for fish users to be benefit from it.
Conversely, anyone who does not want this feature can use "functions
--erase __notify_vte_command_completed" to turn it off.
Before this fix, `function -a arg1 name1` would produce a
function named 'arg1'. After this fix, it will produce a
function named 'name'. See #2068 for more.
When declaring a function using the function "function", the options must follow, not precede, the function name.
The examples demonstrate this syntax, but the synopsis previously showed the options preceding the name.
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
in reader_shell_test, so that there's always a statement terminator.
Otherwise commands like 'echo |' would not be considered an error (just
incomplete).
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
- A new `string` builtin to handle... strings! (#2296)
- Allow using escape as the Meta modifier key, by waiting after seeing an escape character wait up to 300ms for an additional character. This is consistent with readline (e.g. bash) and can be configured via the fish_escape_delay_ms variable. This allows using escape as the Meta modifier. (#1356)
- Add new directories for vendor functions and configuration snippets (#2500)
# Backward-incompatible changes
- Unmatched globs will now cause an error, except when used with `for`, `set` or `count` (#2719)
-`and` and `or` will now bind to the closest `if` or `while`, allowing compound conditions without `begin` and `end` (#1428)
-`set -ql` now searches up to function scope for variables (#2502)
-`status -f` will now behave the same when run as the main script or using `source` (#2643)
-`source` no longer puts the file name in `$argv` if no arguments are given (#139)
# Other notable fixes and improvements
- Fish no longer silences errors in config.fish (#2702)
- Move the history file to $XDG_DATA_HOME/fish (or ~/.local/share if it has not been set)
- Directory autosuggestions will now descend as far as possible if there is only one child directory (#2531)
- Add support for bright colors (#1464)
- Allow Ctrl-J (\cj) to be bound separately from Ctrl-M (\cm) (#217)
- psub now has a "-s"/"–suffix" option to name the temporary file with that suffix
- Enable 24-bit colors on select terminals (#2495)
- Support for SVN status in the prompt (#2582)
- Mercurial and SVN support have been added to the Classic + Git (now Classic + VCS) prompt (via the new \__fish_vcs_prompt function) (#2592)
- export now handles variables with a "=" in the value (#2403)
- Fish no longer has a function called sgrep, freeing it for user customization (#2245)
- A rewrite of the completions for cd, fixing a few bugs (#2299, #2300, #562)
- Linux VTs now run in a simplified mode to avoid issues (#2311)
- The vi-bindings now inherit from the emacs bindings
- Fish will also execute fish_user_key_bindings when in vi-mode
-`funced` will now also check $VISUAL (#2268)
- A new `suspend` function (#2269)
- Subcommand completion now works better with split /usr (#2141)
- The command-not-found-handler can now be overridden by defining a function called __fish_command_not_found_handler in config.fish (#2332)
- A few fixes to the Sorin theme
- PWD shortening in the prompt can now be configured via the fish_prompt_pwd_dir_length variable, set to the length per path component (#2473)
- fish now ships a skeleton file for /etc/fish/config.fish that only contains some documentation, the included code has been moved to the corresponding file in /usr (#2799)
# fish 2.2.0 (released July 12, 2015)
### Significant changes ###
* Abbreviations: the new `abbr` command allows for interactively-expanded abbreviations, allowing quick access to frequently-used commands (#731).
* Vi mode: run `fish_vi_mode` to switch fish into the key bindings and prompt familiar to users of the Vi editor (#65).
* New inline and interactive pager, which will be familiar to users of zsh (#291).
* Underlying architectural changes: the `fishd` universal variable server has been removed as it was a source of many bugs and security problems. Notably, old fish sessions will not be able to communicate universal variable changes with new fish sessions. For best results, restart all running instances of `fish`.
* The web-based configuration tool has been redesigned, featuring a prompt theme chooser and other improvements.
* New German, Brazilian Portuguese, and Chinese translations.
### Backward-incompatible changes ###
These are kept to a minimum, but either change undocumented features or are too hard to use in their existing forms. These changes may break existing scripts.
*`commandline` no longer interprets functions "in reverse", instead behaving as expected (#1567).
* The previously-undocumented `CMD_DURATION` variable is now set for all commands and contains the execution time of the last command in milliseconds (#1585). It is no longer exported to other commands (#1896).
*`if` / `else` conditional statements now return values consistent with the Single Unix Specification, like other shells (#1443).
* A new "top-level" local scope has been added, allowing local variables declared on the commandline to be visible to subsequent commands. (#1908)
### Other notable fixes and improvements ###
* New documentation design (#1662), which requires a Doxygen version 1.8.7 or newer to build.
* Fish now defines a default directory for other packages to provide completions. By default this is `/usr/share/fish/vendor-completions.d`; on systems with `pkgconfig` installed this path is discoverable with `pkg-config --variable completionsdir fish`.
* A new parser removes many bugs; all existing syntax should keep working.
* New `fish_preexec` and `fish_postexec` events are fired before and after job execution respectively (#1549).
* Unmatched wildcards no longer prevent a job from running. Wildcards used interactively will still print an error, but the job will proceed and the wildcard will expand to zero arguments (#1482).
* The `.` command is deprecated and the `source` command is preferred (#310).
*`bind` supports "bind modes", which allows bindings to be set for a particular named mode, to support the implementation of Vi mode.
* A new `export` alias, which behaves like other shells (#1833).
*`command` has a new `--search` option to print the name of the disk file that would be executed, like other shells' `command -v` (#1540).
*`commandline` has a new `--paging-mode` option to support the new pager.
*`complete` has a new `--wraps` option, which allows a command to (recursively) inherit the completions of a wrapped command (#393), and `complete -e` now correctly erases completions (#380).
* Completions are now generated from manual pages by default on the first run of fish (#997).
*`fish_indent` can now produce colorized (`--ansi`) and HTML (`--html`) output (#1827).
*`functions --erase` now prevents autoloaded functions from being reloaded in the current session.
*`history` has a new `--merge` option, to incorporate history from other sessions into the current session (#825).
*`jobs` returns 1 if there are no active jobs (#1484).
*`read` has several new options:
*`--array` to break input into an array (#1540)
*`--null` to break lines on NUL characters rather than newlines (#1694)
*`--nchars` to read a specific number of characters (#1616)
*`--right-prompt` to display a right-hand-side prompt during interactive read (#1698).
*`type` has a new `-q` option to suppress output (#1540 and, like other shells, `type -a` now prints all matches for a command (#261).
* Pressing F1 now shows the manual page for the current command (#1063).
*`fish_title` functions have access to the arguments of the currently running argument as `$argv[1]` (#1542).
* The OS command-not-found handler is used on Arch Linux (#1925), nixOS (#1852), openSUSE and Fedora (#1280).
*`Alt`+`.` searches backwards in the token history, mapping to the same behavior as inserting the last argument of the previous command, like other shells (#89).
* The `SHLVL` environment variable is incremented correctly (#1634 & #1693).
fish 2.1.2 contains a workaround for a filesystem bug in Mac OS X Yosemite. #1859
Specifically, after installing fish 2.1.1 and then rebooting, "Verify Disk" in Disk Utility will report "Invalid number of hard links." We don't have any reports of data loss or other adverse consequences. fish 2.1.2 avoids triggering the bug, but does not repair an already affected filesystem. To repair the filesystem, you can boot into Recovery Mode and use Repair Disk from Disk Utility. Linux and versions of OS X prior to Yosemite are believed to be unaffected.
There are no other changes in this release.
---
# fish 2.1.1 (released September 26, 2014)
__Important:__ if you are upgrading, stop all running instances of `fishd` as soon as possible after installing this release; it will be restarted automatically. On most systems, there will be no further action required. Note that some environments (where `XDG_RUNTIME_DIR` is set), such as Fedora 20, will require a restart of all running fish processes before universal variables work as intended.
Distributors are highly encouraged to call `killall fishd`, `pkill fishd` or similar in installation scripts, or to warn their users to do so.
### Security fixes
* The fish_config web interface now uses an authentication token to protect requests and only responds to requests from the local machine with this token, preventing a remote code execution attack. (closing CVE-2014-2914). #1438
*`psub` and `funced` are no longer vulnerable to attacks which allow local privilege escalation and data tampering (closing CVE-2014-2906 and CVE-2014-3856). #1437
*`fishd` uses a secure path for its socket, preventing a local privilege escalation attack (closing CVE-2014-2905). #1436
*`__fish_print_packages` is no longer vulnerable to attacks which would allow local privilege escalation and data tampering (closing CVE-2014-3219). #1440
### Other fixes
*`fishd` now ignores SIGPIPE, fixing crashes using tools like GNU Parallel and which occurred more often as a result of the other `fishd` changes. #1084 & #1690
---
# fish 2.1.0
Significant Changes
-------------------
* **Tab completions will fuzzy-match files.** #568
When tab-completing a file, fish will first attempt prefix matches (`foo` matches `foobar`), then substring matches (`ooba` matches `foobar`), and lastly subsequence matches (`fbr` matches `foobar`). For example, in a directory with files foo1.txt, foo2.txt, foo3.txt…, you can type only the numeric part and hit tab to fill in the rest.
This feature is implemented for files and executables. It is not yet implemented for options (like `--foobar`), and not yet implemented across path components (like `/u/l/b` to match `/usr/local/bin`).
* **Redirections now work better across pipelines.** #110, #877
In particular, you can pipe stderr and stdout together, for example, with `cmd ^&1 | tee log.txt`, or the more familiar `cmd 2>&1 | tee log.txt`.
* **A single `%` now expands to the last job backgrounded.** #1008
Previously, a single `%` would pid-expand to either all backgrounded jobs, or all jobs owned by your user. Now it expands to the last job backgrounded. If no job is in the background, it will fail to expand. In particular, `fg %` can be used to put the most recent background job in the foreground.
Other Notable Fixes
-------------------
* alt-U and alt+C now uppercase and capitalize words, respectively. #995
* VTE based terminals should now know the working directory. #906
* The autotools build now works on Mavericks. #968
* The end-of-line binding (ctrl+E) now accepts autosuggestions. #932
* Directories in `/etc/paths` (used on OS X) are now prepended instead of appended, similar to other shells. #927
* Option-right-arrow (used for partial autosuggestion completion) now works on iTerm2. #920
* Tab completions now work properly within nested subcommands. #913
*`printf` supports \e, the escape character. #910
*`fish_config history` no longer shows duplicate items. #900
*`$fish_user_paths` is now prepended to $PATH instead of appended. #888
* Jobs complete when all processes complete. #876
For example, in previous versions of fish, `sleep 10 | echo Done` returns control immediately, because echo does not read from stdin. Now it does not complete until sleep exits (presumably after 10 seconds).
* Better error reporting for square brackets. #875
* fish no longer tries to add `/bin` to `$PATH` unless PATH is totally empty. #852
* History token substitution (alt-up) now works correctly inside subshells. #833
* Flow control is now disabled, freeing up ctrl-S and ctrl-Q for other uses. #814
* sh-style variable setting like `foo=bar` now produces better error messages. #809
* Commands with wildcards no longer produce autosuggestions. #785
* funced no longer freaks out when supplied with no arguments. #780
* fish.app now works correctly in a directory containing spaces. #774
* Tab completion cycling no longer occasionally fails to repaint. #765
* Comments now work in eval'd strings. #684
* History search (up-arrow) now shows the item matching the autosuggestion, if that autosuggestion was truncated. #650
* Ctrl-T now transposes characters, as in other shells. #128
---
# fish 2.0.0
Significant Changes
-------------------
* **Command substitutions now modify `$status`#547.**
Previously the exit status of command substitutions (like `(pwd)`) was ignored; however now it modifies $status. Furthermore, the `set` command now only sets $status on failure; it is untouched on success. This allows for the following pattern:
```sh
if set python_path (which python)
...
end
```
Because set does not modify $status on success, the if branch effectively tests whether `which` succeeded, and if so, whether the `set` also succeeded.
* **Improvements to $PATH handling.**
* There is a new variable, `$fish_user_paths`, which can be set universally, and whose contents are appended to $PATH #527
* /etc/paths and /etc/paths.d are now respected on OS X
* fish no longer modifies $PATH to find its own binaries
* **Long lines no longer use ellipsis for line breaks**, and copy and paste
should no longer include a newline even if the line was broken #300
* **New syntax for index ranges** (sometimes known as "slices") #212
* **fish now supports an `else if` statement** #134
* **Process and pid completion now works on OS X** #129
* **fish is now relocatable**, and no longer depends on compiled-in paths #125
* **fish now supports a right prompt (RPROMPT)** through the fish_right_prompt function #80
* **fish now uses posix_spawn instead of fork when possible**, which is much faster on BSD and OS X #11
Other Notable Fixes
-------------------
* Updated VCS completions (darcs, cvs, svn, etc.)
* Avoid calling getcwd on the main thread, as it can hang #696
* Control-D (forward delete) no longer stops at a period #667
* Completions for many new commands
* fish now respects rxvt's unique keybindings #657
* xsel is no longer built as part of fish. It will still be invoked if installed separately #633
* __fish_filter_mime no longer spews #628
* The --no-execute option to fish no longer falls over when reaching the end of a block #624
* fish_config knows how to find fish even if it's not in the $PATH #621
* A leading space now prevents writing to history, as is done in bash and zsh #615
* Hitting enter after a backslash only goes to a new line if it is followed by whitespace or the end of the line #613
* printf is now a builtin #611
* Event handlers should no longer fire if signals are blocked #608
* set_color is now a builtin #578
* man page completions are now located in a new generated_completions directory, instead of your completions directory #576
* tab now clears autosuggestions #561
* tab completion from within a pair of quotes now attempts to "appropriate" the closing quote #552
* $EDITOR can now be a list: for example, `set EDITOR gvim -f`) #541
* `case` bodies are now indented #530
* The profile switch `-p` no longer crashes #517
* You can now control-C out of `read` #516
* `umask` is now functional on OS X #515
* Avoid calling getpwnam on the main thread, as it can hang #512
* Alt-F or Alt-right-arrow (Option-F or option-right-arrow) now accepts one word of an autosuggestion #435
* Setting fish as your login shell no longer kills OpenSUSE #367
* Backslashes now join lines, instead of creating multiple commands #347
* echo now implements the -e flag to interpret escapes #337
* When the last token in the user's input contains capital letters, use its case in preference to that of the autosuggestion #335
* Descriptions now have their own muted color #279
* Wildcards beginning with a . (for example, `ls .*`) no longer match . and .. #270
* Recursive wildcards now handle symlink loops #268
* You can now delete history items from the fish_config web interface #250
* The OS X build now weak links `wcsdup` and `wcscasecmp` #240
* fish now saves and restores the process group, which prevents certain processes from being erroneously reported as stopped #197
* funced now takes an editor option #187
* Alternating row colors are available in fish pager through `fish_pager_color_secondary` #186
* Universal variable values are now stored based on your MAC address, not your hostname #183
* The caret ^ now only does a stderr redirection if it is the first character of a token, making git users happy #168
* Autosuggestions will no longer cause line wrapping #167
* Better handling of Unicode combining characters #155
* fish SIGHUPs processes more often #138
* fish no longer causes `sudo` to ask for a password every time
* fish behaves better under Midnight Commander #121
* `set -e` no longer crashes #100
* fish now will automatically import history from bash, if there is no fish history #66
* Backslashed-newlines inside quoted strings now behave more intuitively #52
* Tab titles should be shown correctly in iTerm2 #47
* scp remote path completion now sometimes works #42
* The `read` builtin no longer shows autosuggestions #29
* Custom key bindings can now be set via the `fish_user_key_bindings` function #21
* All Python scripts now run correctly under both Python 2 and Python 3 #14
* The "accept autosuggestion" key can now be configured #19
* Autosuggestions will no longer suggest invalid commands #6
---
# fishfish Beta r2
Bug Fixes
---------
* **Implicit cd** is back, for paths that start with one or two dots, a slash, or a tilde.
* **Overrides of default functions should be fixed.** The "internalized scripts" feature is disabled for now.
* **Disabled delayed suspend.** This is a strange job-control feature of BSD systems, including OS X. Disabling it frees up Control Y for other purposes; in particular, for yank, which now works on OS X.
* **fish_indent is fixed.** In particular, the `funced` and `funcsave` functions work again.
* A SIGTERM now ends the whole execution stack again (resolving #13).
* Bumped the __fish_config_interactive version number so the default fish_color_autosuggestion kicks in.
* fish_config better handles combined term256 and classic colors like "555 yellow".
New Features
------------
* **A history builtin**, and associated interactive function that enables deleting history items. Example usage:
* Print all history items beginning with echo: `history --prefix echo`
* Print all history items containing foo: `history --contains foo`
Credit to @siteshwar for implementation. Thanks @siteshwar!
---
# fishfish Beta r1
## Scripting
* No changes! All existing fish scripts, config files, completions, etc. from trunk should continue to work.
## New Features
* **Autosuggestions**. Think URL fields in browsers. When you type a command, fish will suggest the rest of the command after the cursor, in a muted gray when possible. You can accept the suggestion with the right arrow key or Ctrl-F. Suggestions come from command history, completions, and some custom code for cd; there's a lot of potential for improvement here. The suggestions are computed on a background pthread, so they never slow down your typing. The autosuggestion feature is incredible. I miss it dearly every time I use anything else.
* **term256 support** where available, specifically modern xterms and OS X Lion. You can specify colors the old way ('set_color cyan') or by specifying RGB hex values ('set_color FF3333'); fish will pick the closest supported color. Some xterms do not advertise term256 support either in the $TERM or terminfo max_colors field, but nevertheless support it. For that reason, fish will default into using it on any xterm (but it can be disabled with an environment variable).
* **Web-based configuration** page. There is a new function 'fish_config'. This spins up a simple Python web server and opens a browser window to it. From this web page, you can set your shell colors and view your functions, variables, and history; all changes apply immediately to all running shells. Eventually all configuration ought to be supported via this mechanism (but in addition to, not instead of, command line mechanisms).
* **Man page completions**. There is a new function 'fish_update_completions'. This function reads all the man1 files from your manpath, removes the roff formatting, parses them to find the commands and options, and outputs fish completions into ~/.config/fish/completions. It won't overwrite existing completion files (except ones that it generated itself).
## Programmatic Changes
* fish is now entirely in C++. I have no particular love for C++, but it provides a ready memory-model to replace halloc. We've made an effort to keep it to a sane and portable subset (no C++11, no boost, no going crazy with templates or smart pointers), but we do use the STL and a little tr1.
* halloc is entirely gone, replaced by normal C++ ownership semantics. If you don't know what halloc is, well, now you have two reasons to be happy.
* All the crufty C data structures are entirely gone. array_list_t, priority_queue_t, hash_table_t, string_buffer_t have been removed and replaced by STL equivalents like std::vector, std::map, and std::wstring. A lot of the string handling now uses std::wstring instead of wchar_t *
* fish now spawns pthreads for tasks like syntax highlighting that require blocking I/O.
* History has been completely rewritten. History files now use an extensible YAML-style syntax. History "merging" (multiple shells writing to the same history file) now works better. There is now a maximum history length of about 250k items (256 * 1024).
* The parser has been "instanced," so you can now create more than one.
* Total #LoC has shrunk slightly even with the new features.
## Performance
* fish now runs syntax highlighting in a background thread, so typing commands is always responsive even on slow filesystems.
* echo, test, and pwd are now builtins, which eliminates many forks.
* The files in share/functions and share/completions now get 'internalized' into C strings that get compiled in with fish. This substantially reduces the number of files touched at startup. A consequence is that you cannot change these functions without recompiling, but often other functions depend on these "standard" functions, so changing them is perhaps not a good idea anyways.
Here are some system call counts for launching and then exiting fish with the default configuration, on OS X. The first column is fish trunk, the next column is with our changes, and the last column is bash for comparison. This data was collected via dtrace.
<table>
<tr> <th> <th> before <th> after <th> bash
<tr> <th> open <td> 9 <td> 4 <td> 5
<tr> <th> fork <td> 28 <td> 14 <td> 0
<tr> <th> stat <td> 131 <td> 85 <td> 11
<tr> <th> lstat <td> 670 <td> 0 <td> 0
<tr> <th> read <td> 332 <td> 80 <td> 4
<tr> <th> write <td> 172 <td> 149 <td> 0
</table>
The large number of forks relative to bash are due to fish's insanely expensive default prompt, which is unchanged in my version. If we switch to a prompt comparable to bash's (lame) default, the forks drop to 16 with trunk, 4 after our changes.
The large reduction in lstat() numbers is due to fish no longer needing to call ttyname() on OS X.
We've got some work to do to be as lean as bash, but we're on the right track.
This is style guide for fish contributors. You should use it for any new code
that you would add to this project and try to format existing code to use this
style.
This document provides guidelines for making changes to the fish-shell project. This includes rules for how to format the code, naming conventions, etc. It also includes recommended best practices such as creating a Travis-CI account so you can verify your changes pass all the tests before making a pull-request.
## Formatting
See the bottom of this document for help on installing the linting and style reformatting tools discussed in the following sections.
1. fish uses the Allman/BSD style of indentation.
2. Indent with spaces, not tabs.
3. Use 4 spaces per indent (unless needed like `Makefile`).
4. Opening curly bracket is on the following line:
## Lint Free Code
// ✔:
struct name
{
// code
};
Automated analysis tools like cppcheck and oclint can point out potential bugs. They also help ensure the code has a consistent style and that it avoids patterns that tend to confuse people.
void func()
{
// code
}
Ultimately we want lint free code. However, at the moment a lot of cleanup is required to reach that goal. For now simply try to avoid introducing new lint.
if (...)
{
// code
}
To make linting the code easy there are two make targets: `lint` and `lint-all`. The latter does just what the name implies. The former will lint any modified but not committed `*.cpp` files. If there is no uncommitted work it will lint the files in the most recent commit.
// ✗:
void func() {
// code
}
### Dealing With Lint Warnings
5. Put space after `if`, `while` and `for` before conditions.
You are strongly encouraged to address a lint warning by refactoring the code, changing variable names, or whatever action is implied by the warning.
// ✔:
if () {}
### Suppressing Lint Warnings
// ✗:
if() {}
Once in a while the lint tools emit a false positive warning. For example, cppcheck might suggest a memory leak is present when that is not the case. To suppress that cppcheck warning you should insert a line like the following immediately prior to the line cppcheck warned about:
6. Put spaces before and after operators excluding increment and decrement;
```
// cppcheck-suppress memleak // addr not really leaked
```
// ✔:
int a = 1 + 2 * 3;
a++;
The explanatory portion of the suppression comment is optional. For other types of warnings replace "memleak" with the value inside the parenthesis (e.g., "nullPointerRedundantCheck") from a warning like the following:
// ✗:
int a=1+2*3;
a ++;
```
[src/complete.cpp:1727]: warning (nullPointerRedundantCheck): Either the condition 'cmd_node' is redundant or there is possible null pointer dereference: cmd_node.
```
7. Never put spaces between function name and parameters list.
Suppressing oclint warnings is more complicated to describe so I'll refer you to the [OCLint HowTo](http://docs.oclint.org/en/latest/howto/suppress.html#annotations) on the topic.
// ✔:
func(args);
## Ensuring Your Changes Conform to the Style Guides
// ✗:
func (args);
The following sections discuss the specific rules for the style that should be used when writing fish code. To ensure your changes conform to the style rules you simply need to run
8. Never put spaces after `(` and before `)`.
9. Always put space after comma and semicolon.
```
make style
```
// ✔:
func(arg1, arg2);
before commiting your change. If you've already committed your changes that's okay since it will then check the files in the most recent commit. This can be useful after you've merged someone elses change and want to check that it's style is acceptable.
for (int i = 0; i < LENGTH; i++) {}
If you want to check the style of the entire code base run
// ✗:
func(arg1,arg2);
```
make style-all
```
for (int i = 0;i<LENGTH;i++) {}
### Suppressing Reformatting of the Code
## Documentation
If you have a good reason for doing so you can tell `clang-format` to not reformat a block of code by enclosing it in comments like this:
Document your code using [Doxygen][dox].
```
// clang-format off
code to ignore
// clang-format on
```
1. Documentation comment should use double star notation or tripple slash:
## Fish Script Style Guide
// ✔:
/// Some var
int var;
Fish scripts such as those in the *share/functions* and *tests* directories should be formatted using the `fish_indent` command.
/**
* Some func
*/
void func();
Function names should be all lowercase with undescores separating words. Private functions should begin with an underscore. The first word should be `fish` if the function is unique to fish.
2. Use slash as tag mark:
The first word of global variable names should generally be `fish` for public vars or `_fish` for private vars to minimize the possibility of name clashes with user defined vars.
// ✔:
## C++ Style Guide
/**
* \param a an integer argument.
* \param s a constant character pointer.
* \return The results
*/
int foo(int a, const char *s);
1. The [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) forms the basis of the fish C++ style guide. There are two major deviations for the fish project. First, a four, rather than two, space indent. Second, line lengths up to 100, rather than 80, characters.
## Naming
1. The `clang-format` command is authoritative with respect to indentation, whitespace around operators, etc. **Note**: this rule should be ignored at this time. After the code is cleaned up this rule will become mandatory.
All names in code should be `small_snake_case`. No Hungarian notation is used.
Classes and structs names should be followed by `_t`.
1.All names in code should be `small_snake_case`. No Hungarian notation is used. Classes and structs names should be followed by `_t`.
1. Always attach braces to the surrounding context.
1. Indent with spaces, not tabs and use four spaces per indent.
1. Comments should always use the C++ style; i.e., each line of the comment should begin with a `//` and should be limited to 100 characters. Comments that do not begin a line should be separated from the previous text by two spaces.
## Testing
The source code for fish includes a large collection of tests. If you are making any changes to fish, running these tests is highly recommended to make sure the behaviour remains consistent.
You are also strongly encouraged to add tests when changing the functionality of fish. Especially if you are fixing a bug to help ensure there are no regressions in the future (i.e., we don't reintroduce the bug).
### Local testing
The tests can be run on your local computer on all operating systems.
Running the tests is only supported from the autotools build and not xcodebuild. On OS X, you will need to install autoconf — we suggest using [Homebrew](http://brew.sh/) to install these tools.
autoconf
./configure
make test [gmake on BSD]
### Travis CI Build and Test
The Travis Continuous Integration services can be used to test your changes using multiple configurations. This is the same service that the fish shell project uses to ensure new changes haven't broken anything. Thus it is a really good idea that you leverage Travis CI before making a pull-request to avoid embarrasment at breaking the build.
You will need to [fork the fish-shell repository on GitHub](https://help.github.com/articles/fork-a-repo/). Then setup Travis to test your changes before you make a pull-request:
1. [Sign in to Travis CI](https://travis-ci.org/auth) with your GitHub account, accepting the GitHub access permissions confirmation.
1. Once you're signed in, and your repositories are synchronised, go to your [profile page](https://travis-ci.org/profile) and enable the fish-shell repository.
1. Push your changes to GitHub.
You'll receive an email when the tests are complete telling you whether or not any tests failed.
You'll find the configuration used to control Travis in the `.travis.yml` file.
## Installing the Required Tools
### Installing the Linting Tools
To install the lint checkers on Mac OS X using HomeBrew:
```
brew tap oclint/formulae
brew install oclint
brew install cppcheck
```
To install the lint checkers on Linux distros that use Apt:
```
sudo apt-get install clang
sudo apt-get install oclint
sudo apt-get install cppcheck
```
### Installing the Reformatting Tools
To install the reformatting tool on Mac OS X using HomeBrew:
```
brew install clang-format
```
To install the reformatting tool on Linux distros that use Apt:
```
apt-cache search clang-format
```
That will list the versions available. Pick the newest one available (3.6 for Ubuntu 14.04 as I write this) and install it:
[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
fish is written in a sane subset of C++98, with a few components from C++TR1. It builds successfully with g++ 4.2 or later, and with clang. It also will build as C++11.
fish can be built using autotools or Xcode. autoconf 2.60 or later is required.
fish can be built using autotools or Xcode. autoconf 2.60 or later is required to build from git versions, but is not required for releases.
fish depends on a curses implementation, such as ncurses. The headers and libraries are required for building.
fish requires PCRE2 due to the regular expression support contained in the `string` builtin. A copy is included with the source code, and will be used automatically if it does not already exist on your system.
fish requires gettext for translation support.
Building the documentation requires Doxygen 1.8.7 or newer.
### Autotools Build
autoconf
autoconf [if building from Git]
./configure
make [gmake on BSD]
sudo make install
@@ -42,12 +48,26 @@ 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 PCRE2 due to the regular expression support contained in the `string` builtin. A bundled version will be compiled in automatically at build time if required.
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
Instructions on how to find builds for several Linux distros are at <https://github.com/fish-shell/fish-shell/wiki/Nightly-builds>
@@ -58,7 +78,11 @@ If you wish to use fish as your default shell, use the following command:
chsh -s /usr/local/bin/fish
chsh will prompt you for your password, and change your default shell.
chsh will prompt you for your password, and change your default shell. Substitute "/usr/local/bin/fish" with whatever path to fish is in your /etc/shells file.
Use the following command if you didn't already add your fish path to /etc/shells.
echo /usr/local/bin/fish | sudo tee -a /etc/shells
To switch your default shell back, you can run:
@@ -66,14 +90,12 @@ To switch your default shell back, you can run:
Substitute /bin/bash with /bin/tcsh or /bin/zsh as appropriate.
## Optional Dependencies
## Contributing Changes to the Code
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.
See the [Guide for Developers](CONTRIBUTING.md).
## Contact Us
Questions, comments, rants and raves can be posted to the official fish mailing list at <https://lists.sourceforge.net/lists/listinfo/fish-users> or join us on our IRC channel [#fish at irc.oftc.net](https://webchat.oftc.net/?channels=fish).
Questions, comments, rants and raves can be posted to the official fish mailing list at <https://lists.sourceforge.net/lists/listinfo/fish-users> or join us on our [gitter.im channel](https://gitter.im/fish-shell/fish-shell) or IRC channel [#fish at irc.oftc.net](https://webchat.oftc.net/?channels=fish). Or use the [fish tag on Stackoverflow](https://stackoverflow.com/questions/tagged/fish).
Found a bug? Have an awesome idea? Please open an issue on this github page.
# But signed comparison warnings are way too aggressive
#
CXXFLAGS="$CXXFLAGS -Wall"
CXXFLAGS="$CXXFLAGS -Wall -Wno-sign-compare"
#
# This is needed in order to get the really cool backtraces on Linux
#
if test `uname` != "Darwin"; then
LDFLAGS_FISH="$LDFLAGS_FISH -rdynamic"
fi
AC_MSG_CHECKING([for -rdynamic linker flag])
prev_LDFLAGS="$LDFLAGS"
LDFLAGS="$LDFLAGS -rdynamic"
AC_LINK_IFELSE([AC_LANG_PROGRAM([[]],[[]])],
[
AC_MSG_RESULT([yes])
LDFLAGS_FISH="$LDFLAGS_FISH -rdynamic"
], [
AC_MSG_RESULT([no])
LDFLAGS_FISH="$LDFLAGS_FISH"
])
LDFLAGS="$prev_LDFLAGS"
#
@@ -335,35 +306,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
#
@@ -381,40 +323,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 directory] )
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.
@@ -434,6 +342,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
@@ -445,79 +356,35 @@ AC_DEFINE(
# Check for os dependant libraries for all binaries.
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])] )
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 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\>
-`<bs>`: Render the contents with a preceding backslash. Useful when presenting output.
-`{{` and `}}`: Required when wanting curly braces in regular expression example.
### 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 using universal variables. You can create abbreviations directly on the command line, and they will be saved automatically. Calling `abbr -a` in config.fish will lead to slightly worse startup performance.
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.
Note: fish version 2.1 supported `-a WORD=PHRASE`. This syntax is now deprecated but will still be converted.
\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.
Note that spaces need to be escaped in the call to alias just like in the commandline _even inside the quotes_.
\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:
<pre>function rmi
function rmi
rm -i $argv
end</pre>
end
# This needs to have the spaces escaped or "Chrome.app..." will be seen as an argument to "/Applications/Google":
alias chrome='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome banana'
\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. **Bare `bind` statements in <a href="index.html#initialization">config.fish</a> won't have any effect because it is sourced before the default keybindings are setup.** To save custom keybindings, put the `bind` statements into a function called `fish_user_key_bindings`, which will be <a href="tutorial.html#tut_autoload">autoloaded</a>.
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
- `accept-autosuggestion`, accept the current autosuggestion completely
- `backward-char`, moves one character to the left
- `backward-bigword`, move one whitespace-delimited word to the left
- `backward-delete-char`, deletes one character of input to the left of the cursor
- `backward-kill-bigword`, move the whitespace-delimited word to the left of the cursor to the killring
- `backward-kill-line`, move everything from the beginning of the line to the cursor to the killring
- `backward-kill-path-component`, move one path component to the left of the cursor (everything from the last "/" or whitespace exclusive) 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
- `begin-selection`, start selecting text
- `capitalize-word`, make the current word begin with a capital letter
- `complete`, guess the remainder of the current token
- `complete-and-search`, invoke the searchable pager on completion options
- `delete-char`, delete one character to the right of the cursor
- `downcase-word`, make the current word lowercase
- `end-of-history`, move to the end of the history
- `end-of-line`, move to the end of the line
- `end-selection`, end selecting text
- `forward-bigword`, move one whitespace-delimited word to the right
- `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-bigword`, move the next whitespace-delimited word to the killring
- `kill-line`, move everything from the cursor to the end of the line to the killring
- `kill-selection`, move the selected text to the killring
- `kill-whole-line`, move the line to the killring
- `kill-word`, move the next word to the killring
- `suppress-autosuggestion`, remove the current autosuggestion
- `swap-selection-start-stop`, go to the other end of the highlighted text without changing the selection
- `transpose-chars`, transpose two characters to the left of the cursor
- `transpose-words`, transpose two words to the left of the cursor
- `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.
\subsection special-case-escape Special Case: The escape Character
The escape key can be used standalone, for example, to switch from insertion mode to normal mode when using Vi keybindings. Escape may also be used as a "meta" key, to indicate the start of an escape sequence, such as function or arrow keys. Custom bindings can also be defined that begin with an escape character.
fish waits for a period after receiving the escape character, to determine whether it is standalone or part of an escape sequence. While waiting, additional key presses make the escape key behave as a meta key. If no other key presses come in, it is handled as a standalone escape. The waiting period is set to 300 milliseconds (0.3 seconds) in the default key bindings and 10 milliseconds in the vi key bindings. It can be configured by setting the `fish_escape_delay_ms` variable to a value between 10 and 5000 ms. It is recommended that this be a universal variable that you set once from an interactive session.
Note: fish 2.2.0 and earlier used a default of 10 milliseconds, and provided no way to configure it. That effectively made it impossible to use escape as a meta key.
\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 \c 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 `cd` if the name of a directory is provided (starting with `.`, `/` or `~`, or ending with `/`).
Fish also ships a wrapper function around the builtin `cd` that understands `cd -` as changing to the previous directory. See also <a href="commands.html#prevd">`prevd`</a>. This wrapper function maintains a history of the 25 most recently visited directories in the `$dirprev` and `$dirnext` global variables.
\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.
If the commandline contains
\fish
>_ echo $fl___ounder >&2 | less; and echo $catfish
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 +23,102 @@ 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 command substitutions.
- `DESCRIPTION` is a description of what the option and/or option arguments do.
- `-c COMMAND` or `--command COMMAND` specifies that `COMMAND` is the name of the command.
- `-p COMMAND` or `--path COMMAND` specifies that `COMMAND` is the absolute path of the program (optionally containing wildcards).
- `-e` or `--erase` deletes the specified completion.
- `-s SHORT_OPTION` or `--short-option=SHORT_OPTION` adds a short option to the completions list.
- `-l LONG_OPTION` or `--long-option=LONG_OPTION` adds a GNU style long option to the completions list.
- `-o LONG_OPTION` or `--old-option=LONG_OPTION` adds an old style long option to the completions list (See below for details).
- `-a OPTION_ARGUMENTS` or `--arguments=OPTION_ARGUMENTS` adds the specified option arguments to the completions list.
- `-f` or `--no-files` specifies that the options specified by this completion may not be followed by a filename.
- `-r` or `--require-parameter` specifies that the options specified by this completion always must have an option argument, i.e. may not be followed by another option.
- `-x` or `--exclusive` implies both `-r` and `-f`.
- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the specified command to inherit completions from the wrapped command (See blow for details).
- `-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.
- `-CSTRING` or `--do-complete=STRING` makes complete try to find all possible completions for the specified string.
- `-C` or `--do-complete` with no argument makes complete try to find all possible completions for the current command line buffer. If the shell is not in interactive mode, an error is returned.
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 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').
The options for specifying command name and command path may be used multiple times to define the same completions for multiple commands.
The options for specifying command switches and wrapped commands may be used multiple times to define multiple completions for the command(s) in a single call.
Invoking `complete` multiple times for the same command adds the new definitions on top of any existing completions defined for the command.
When `-a` or `--arguments` is specified in conjunction with long, short, or old style options, the specified arguments are only used as completions when attempting to complete an argument for any of the specified options. If `-a` or `--arguments` is specified without any long, short, or old style options, the specified arguments are used when completing any argument to the command (except when completing an option argument that was specified with `-r` or `--require-parameter`).
Command substitutions found in `OPTION_ARGUMENTS` are not expected to return a space-separated list of arguments. Instead they must return a newline-separated list of arguments, and each argument may optionally have a tab character followed by the argument description. Any description provided in this way overrides a description given with `-d` or `--description`.
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. Note that wrapping only works for completions specified with `-c` or `--command` and are ignored when specifying completions with `-p` or `--path`.
When erasing completions, it is possible to either erase all completions for a specific command by specifying `complete -c COMMAND -e`, or by specifying a specific completion option to delete by specifying either a long, short or old style option.
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 they remember the new information until the next time they use 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, they 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.
\c dirh does not accept any parameters.
`dirh` does not accept any parameters.
Note that the `cd` command limits directory history to the 25 most recently visited directories. The history is stored in the `$dirprev` and `$dirnext` variables.
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 following 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 variations 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):
\section faq-reserved-chars Unicode private-use characters reserved by fish
\htmlonly
Fish reserves the <a href="http://www.unicode.org/faq/private_use.html">Unicode private-use character range</a> from U+F600 thru U+F73F for internal use. Any attempt to feed characters in that range to fish will result in them being replaced by the Unicode "replacement character" U+FFFD. This includes both interactive input as well as any file read by fish (but not programs run by fish).
\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
- `-d` or `--dump` dumps information about the parsed fish commands to stderr
- `-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 `$VISUAL` environment variable is set, it will be used as the program to edit the function. If `$VISUAL` is unset but `$EDITOR` is set, that will be used. 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.
Note that because fish loads functions on-demand, saved functions will not function as <a href="index.html#event">event handlers</a> until they are run or sourced otherwise. To activate an event handler for every new shell, add the function to your <a href="index.html#initialization">shell initialization file</a> instead of using `funcsave`.
\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
and is a regular file, otherwise it will print
<tt>foo.txt and bar.txt do not exist</tt>.
\endfish
The following code will print "foo.txt exists and is readable" if foo.txt is a regular file and readable
\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 nextd nextd - move forward through directory history
\subsection nextd-synopsis Synopsis
<tt>nextd [-l | --list] [POS]</tt>
\fish{synopsis}
nextd [ -l | --list ] [POS]
\endfish
\subsection nextd-description Description
<tt>nextd</tt> moves forwards <tt>POS</tt> positions in the history of visited
directories; if the end of the history has been hit, a warning is printed.
If the <code>-l></code> or <code>--list</code> flag is specified, the current
directory history is also displayed.
`nextd` moves forwards `POS` positions in the history of visited directories; if the end of the history has been hit, a warning is printed.
If the `-l` or `--list` flag is specified, the current directory history is also displayed.
Note that the `cd` command limits directory history to the 25 most recently visited directories. The history is stored in the `$dirprev` and `$dirnext` variables which this command manipulates.
\subsection nextd-example Example
\code
\fish
cd /usr/src
# Working directory is now /usr/src
cd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
prevd
# Working directory is now /usr/src
nextd
# Working directory is now /usr/src/fish-shell</pre>
\section not not - negate the exit status of a job
\subsection not-synopsis Synopsis
<tt>not COMMAND [OPTIONS...]</tt>
\fish{synopsis}
not COMMAND [OPTIONS...]
\endfish
\subsection not-description Description
\c not negates the exit status of another command. If the exit status
is zero, \c not returns 1. Otherwise, \c not returns 0.
`not` negates the exit status of another command. If the exit status is zero, `not` returns 1. Otherwise, `not` returns 0.
\subsection not-example Example
The following code reports an error and exits if no file named spoon can be found.
<pre>
\fish
if not test -f spoon
echo There is no spoon
exit 1
echo There is no spoon
exit 1
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.
