In FAQ:
> I'm seeing weird output before each prompt when using screen. What's wrong?
The command provided is
echo 'function fish_title;end' > ~/.config/fish/config.fish
Using `>` will overwrite current config.fish.
We should use `>>` instead.
With the fix for #365, fish_command_not_found event handlers
receive the command and all of its arguments. But commands
like /usr/lib/command-not-found expect only the command name.
So when invoking an external command, just pass the command
name, not all of the arguments.
Before running a command, we add the command to history, so
that if the command causes us to exit it's still captured in
history. But that command should not be considered part of
history when expanding the history within the command itself.
For example, `echo $history[1]` should be the previously
run command, not `echo $history[1]` itself.
Fixes#2028
For the case
```
bind \et "commandline -i 1" "commandline -i 2"
```
the order of execution of the commands is now in-order.
Note that functions codes are prepended to the queue in reverse order, so they
will be executed in-order. This should allow all bindings of the form
```
bind \et beginning-of-line force-repaint
```
to remain unchanged.
Using builtin `commandline -f`, one would expect to have commands executed in
the order that they were given. This motivates the change to a queue.
Unfortunately, fish internals still need lookahead_list to act as a stack. Add
and rename functions to support both cases and have lookahead_list as
a std::deque internally.
This code is delicate, and we should probably dog-food this in nightly for
a while before the next-minor release.
Fixes#1567
Examples that work as expected (even completions don't get confused):
$ begin true; end;
$ begin if true; end; end
$ begin if true; echo hi; end
The last example correctly expects another 'end' to match 'begin'.
Fixes#1248.
Do not tombstone a function when it is evicted normally from the LRU cache.
This broke changing `fish_function_path`, since that would evict all nodes,
resulting in accidental tombstones, which caused autoloaded functions to
never be reloaded.
See #213.
In 73f344f41b, we allowed autoloaded functions to be deleted.
For some reason, funcsave immediately deletes the function it
creates. This previously did very little, since the function would
immediately be re-autoloaded, but with the fix for 73f344f41b
the function gets tombstoned. So the effect is that funcsave
makes the function disappear! This simply removes the erase call,
which dates back to fish 1.x.
As suggested by @ridiculousfish, when removing autoloaded functions, add them
to a tombstones set. These functions will never be autoloaded again in the
current shell, not even when the timestamp changes.
Tested as per comment 1 of #1033. `~/.config/fish/functions/ls.fish` contains
the function definition. `function -e ls` removes the redefined `ls` (and
reverts back to the built-in command). `touch .../ls.fish` does not cause the
function to be reloaded.
Works also if tok->show_comments (for highlighting and auto completion) and
with multi-line comments:
function my_function
echo "hello" | \
#remove 'l'
#and more
tr -d 'l'
end
$ my_function
heo
Fixes#983
It seems that `ul` can't handle the escape sequences for bold text that `nroff` generates on my system. Fixed by either removing `| ul`, or adding `-c` to the `nroff` command.
Needs testing for old (OSX?) versions of nroff.
Fixes a bug where generating a lot of autoloaded functions from
syntax highlighting would result in evicting nodes on background threads,
resulting in a thread error.
Fixes#1989
Unfortunately, list-unit-files doesn't understand --state=loaded
This needs a new function to explicitly use list-units
This reverts commit 9f521b7694.
e340baf6cc introduced a bug where fish would not exit from job_continue
when receiving a signal like SIGHUP. This means that it would not in turn
deliver SIGHUP to its children, who would therefore never exit. Those
children may attempt to write to stdout, in which case they would receive
EIO; this can cause other weird issues, like telnet using 100% CPU.
Fixes#1958
Valid uses of this environment variable don't really include passing
it to subsequent child processes.
I confirmed the fix with:
function fish_prompt
echo "cmd duration [$CMD_DURATION] "
end
cmd duration [0] sleep 2
cmd duration [2002]
Prior to b0e09303a, simple jobs like `printf "%s\n" $line | read word _`
never hit the call to select() because they were reaped in the SIGCHLD
signal handler. With that commit, the signal handler no longer reaps
children, and a job like that would enter select() and hit the 10000μs
timeout before discovering that the job was already complete.
Fixes#1884.
Remove global array of file descriptors, in
favor of relying on CLO_EXEC exclusively.
Also correctly implement "pipe avoidance" so
that fd redirections do not conflict
with pipes.
- Rename 'events' to 's_event_handlers'
- Stop inspecting the s_event_handlers list upon receiving
a signal. Instead, maintain the set of signals that are observed
in a separate static array. This lets us avoid mucking with
STL data structures in a signal handler, and so avoid blocking signals
in event.cpp
GNU and BSD `mktemp` handle options differently, and it's a useful
utility for tests. As such, define a common `mktemp` function wrapper
for the test suite.
It might actually be nice to expand this for more flags and support it
globally, but that may result in confusion for any users of BSD mktemp
that expect to be running /bin/mktemp.
Update the test runners so they set up their own environment in
test_util.fish. This simplifies the Makefile and paves the way for
adding utility functions for use in the tests themselves.
Support for space-delimited abbreviations was added to the expansion
parser in fbade198; this commit extends that support to the user-facing
tools, and documents the space-separated behaviour. Equals-delimited
abbreviations are expected to be removed before the next release.
Work on #731.
This prevents cases like `cd /usr/e` from tab-completing to
`cd /usr/` (which is the shared prefix of the tab completions).
Things are still sort of confusing with fuzzy matching, e.g.
with files like this:
foo1bar
foo2bar
Then ba<tab> will replace the token with foo. That's surprising,
but not new to this fix.
Fixes#1727
There is no CTRL-C handler for the default mode in the vi bindings. This makes it difficult to say "never mind" and start a new command line like you can do in bash's vi mode.
There were CTRL-C handlers for insert and visual modes that go back to default mode, but nothing happens in default mode. I copy-pasted the CTRL-C handler from the default key bindings file.
The PROCESS_EXIT event takes 3 args: event name, pid, status. However,
when fish is exiting, the PROCESS_EXIT is instead given the status of
whether the last commandline parsed successfully. Change it to use the
same value that fish itself is going to exit with.
When calculating the version, we don't need to test for the presence of
.git before running `git describe`. This lets us work properly in a
detached work tree if GIT_DIR is set.
(Ideally, the behaviour of git could be implemented: pipe the input
through a pager iff the length is > window size and in interactive
mode).
Closes#1076.
Work on #1073.
fish is not exclusively distributed under the GPL version 2; the
canonical reference is doc_src/license.hdr, so use that as the full
description.
[skip ci]
Prior to this fix, a child process may be reaped in one of two ways:
1. By a call to waitpid() within job_continue
2. By a call to waitpid() within the SIGCHLD signal handler
Only the second call was with the WNOHANG option. Thus if the signal
handler fired first, and then the waitpid call fired, we could get a
deadlock because we'd end up waiting on a long-running process. I have
not been able to reproduce this on fish 1.x, though it seems like it
ought to reproduce there too.
This fix migrates the waitpid() call out of the signal handler; the
second class of calls moves to job_reap. This eliminates the possibility
of a race, because we check for job completion before calling waitpid,
and there is no longer the possibility of the job being marked as
complete asynchronously. It also results in a massive conceptual
simplification, since the signal handler is now very simple and easy to
reason about (no more walking jobs lists, etc).
This partially fixes a bug reported in #1273
Wildcard errors are only reported interactively, and they're also not
really errors. Commands with multiple wildcards would in fact continue
executing if at least one wildcard matched, which is quite surprising.
But they would report an error if there is only one wildcard in the
arguments list and the wildcard has no match, even if there are other
remaining arguments.
Given this inconsistency, and given that sh does not stop execution if a
wildcard fails to match, it seems better to allow execution to continue.
This is better from a scripting perspective anyway, as it means
constructs like `set -l paths foo/*.txt` will actually create the
variable (with an empty value) instead of skipping the `set`
altogether and perhaps causing subsequent code to read or modify a
global or universal variable.
Wildcard errors are only supposed to reported when encountered during
interactive use. The old parser also suppressed them if `is_block` was
true. This was lost in the new parser. However, this also suppresses
errors generated from `begin; code_here; end` and other block
constructs.
Instead, check the parser block stack when we hit an error, and suppress
the error if there are any function calls / events / source invocations.
These all indicate that the code being executed came from somewhere
other than the commandline.
Unmatched wildcard errors during parsing are normally only reported when
run interactively. The switch command was unconditionally reporting them
anyway (and not setting the status to 124). Fix it so switch goes
through the same code path as everything else.
Prior to this change, inherited environment variables
would be split on colons, becoming an array. This change
eliminates that behavior. Now environment variables are
always split on the record separator character (ASCII 0x1e),
with the exception of a short whitelist of PATH, MANPATH,
CDPATH. Likewise, exported variables are also exported
delimited by rs, with the exception of the above whitelist.
Fixes#1374, also see #1656
The terminal width magic that __fish_print_help learned doesn't help
when builtin_print_help runs it in a subshell. Instead, add an
undocumented --tty-width flag to __fish_print_help that's used to pass
the terminal width.
As a result of this rewrite, the output now:
* Expands to fit the terminal width, like `man` does
* Preprocesses the manpage with `tbl` just in case, since `man` does
this, even though I doubt any fish manpages use `tbl` formatting.
* Handle bold/underline with the `ul` command as it was designed for
instead of trying to fake it with `sed`.
* Compresses blank lines as `man` does with the default `less -is`
pager.
We can't use $PATHS to test the :-splitting because the global config
file adds extra paths based on /etc/paths and /etc/paths.d.
Ideally fish would have a way to suppress behavior like that, but for
the time being it doesn't.
The usage is still the same, but it's a lot more robust, and also no
longer assumes $fish_user_abbreviations must be a universal variable.
This also fixes the unexpected error output when calling `abbr -a` with
no existing abbreviations.
Calling `abbr -a` with an abbreviation that already exists now silently
overwrites the abbreviation, just like `function` and `bind` do, instead
of complaining.
Re-running ./configure will cause fish.pc to rebuild, in case any of the
paths changed. It looks like this actually won't rebuild the rest of
fish, but figuring out how to handle that is out of scope for this
commit.
More importantly, this will rebuild fish.pc when the version string
changes.
This fixes the issue with nonexistant directories (some Linux
distributions put these for local modules), and also fixes the
issue of dot meaning any character instead of simply dot.
--inherit-variable takes a variable name and snapshots its current
value. When the function is executed, it will have a local variable with
this value already defined. Printing the function source will include
synthesized `set -l` lines for the values.
This is primarily useful for functions that are created on the fly, such
as in `psub`.
ENV_USER is intended to be used when setting any variable whose name is
controlled by the user. The names given to `function -a` certainly
qualifies. This wasn't an issue in practice because the only restriction
ENV_USER imposes is also imposed on ENV_LOCAL, but the rules may change
in the future.
# The first commit's message is:
Simplify default fish_prompt
No need for the set_color caching now that it's a builtin.
Also simplify the 3 classic prompts in fish_config's sample_prompts set.
Remove comment that AFAICT is not true anymore.
Ensure someone setting __fish_active_key_bindings as a universal
variable doesn't screw up the initial keybinding load.
env.cpp sets up $HOME based on the current user, if it's not inherited
from the environment. fishd_get_config should be using the same
calculated value of $HOME. To that end, move universal variable
initialization to after $HOME is set up, and read the value from the
fish environment instead of using getenv().
Fixes#1725.
If $HOME is unset in the environment, fish calculates it with
getpwnam(). However, it wasn't being exported. Just like the $USER
calculation, $HOME should probably be exported, because everyone will
assume that it's an environment variable (as opposed to an unexported
global variable).
Assists other packages in finding the path to install completions: call
`pkg-config --variable=completionsdir fish` or so (like
bash-completion).
As discussed in #1485.
Instead of globally marking the state as "in block" when evaluating
blocks/functions, update the "in block" status when pushing/popping
blocks on the parser stack.
Fixes#1729.
On a side note, `status -b` is actually pretty useless, because it
always returns 0 inside of a function (even without this patch).
Making `true` into a builtin is a significant optimization to `while
true` loops. As long as `true` is a builtin, we may as well make `false`
builtin as well (despite the fact that it's not typically executed in a
loop).
This makes two changes to parse trees:
1. Unmaterialized nodes no longer have an invalid source location
For example, with the code `while false;end` there are no tokens
associated with the while loop's job_list, and therefore it is
unmaterialized. Previously it would have had a SOURCE_OFFSET_INVALID.
But now it has a zero source length, but an offset equal to the end of
the while loop (i.e. the semicolon), and a zero length. Correspondingly,
the has_source function now checks the length instead of the offset.
2. Special (comment and error) nodes have always been "disconnected,"
meaning they are not the child of any other node. However, they now have
their parent offsets set to whatever the top of the node stack was when
the node was encountered. This gives us a sense of which node the
comment is "in", e.g. if we are constructing a job list then the
comment's parent will be the job list. This lets us determine the
comment's indent.
All opam subcommands and descriptions are covered, along with
all the flags that are common to all commands. However, only
`opam config` has complete subsubcommand coverage.
Apparently, in zsh, Meta+H can be used to display the manpage for
the current command. This commit adds this zsh feature to fish shell.
The F1 keybinding is left, although it's now secondary according to
fish help, as some terminal emulators don't let the user press F1 key.
my_wcswidth() was just a wrapper around fish_wcswidth() already.
Instead, add two convenience overrides of fish_wcswidth() to common.h
that make it a drop-in replacement for my_wcswidth().
If a wildcard or completion expands to a file that begins with
one or more dashes, prepend a ./ to it so that it doesn't get
parsed as an option.
Fixes#1519
history_lru_node_t has implicit destructor defined. However, because
it's being deleted as lru_node_t, it's not being actually called, as
lru_node_t doesn't have a virtual destructor.
It seems expect prioritizes the first pattern in the list, instead of
the pattern that matches earliest in the buffer. That seems pretty
stupid, but let's try moving the prompt pattern to the end and see if
that fixes the Travis failures.
Also tweak colored output to reset before the newline instead of after,
so travis behaves better (for some reason reset causes travis to display
the line in black).
Split test_interactive off from test_fishscript and add a new target
test_high_level that tests both.
Add some Makefile magic so the tests can be run serially without using
sub-make, which gets rid of a little noise from the make output.
Rewrite interactive tests to look better.
re: fish-shell/fish-shell@2726712e01
As this is rendering ok in Firefox, this version should pickup the best
fonts for most browser/os variants based on 'font-stretch' support.
`.fish_left_bar` should be condensed, the main body font shouldn't.
Binds with the same sequence in multiple modes was not working right.
Fix up the implementation to propagate modes everywhere as necessary.
This means that `bind` will properly list distinct binds with the same
sequence, and `bind -e` will take mode into account properly as well.
Note that `bind -e seq` now assumes the bind is in the default bind
mode, whereas before it would erase the first binding with that sequence
regardless of mode.
`bind -e -a` still erases all binds in all modes, though `bind -M mode
-e -a` still only erases all binds in the selected mode.
<em> used to represent something else, but as far as I can tell, all
uses of <em> in the documentation today actually represent text that's
supposed to be visibly different. Notably, the documentation on
supported escapes uses <em> to indicate the letters that are a
placeholder for e.g. a hex digit, as opposed to being a literal
character.
U+F8FF is the last character in the private use area, but it's also the
codepoint used for the Apple symbol (), which is typeable on US
keyboards in OS X, and so should actually work.
Use the new `read -z` flag to complete git aliases better. This approach
won't break if an alias contains a newline.
Also fix stash completion, which was broken on BSD sed.
The `--null` flag to `read` makes it split incoming lines on NUL instead
of newlines. This is intended for processing the output of a command
that uses NUL separators (such as `find -print0`).
Fixes#1694.
This font, at least under Kubuntu 14.04 and Firefox I use is rather
ugly. Anti-aliasing is wrong, and the spaces between letters are
rather random. It makes reading the documentation headings and table
of contents harder than it needs to be.
Those issues don't happen with DejaVu Sans.
Directories are completed like commands, because of implicit cd.
However, directories found inside $PATH entries should not be completed,
as implicit cd doesn't work there. Similarly, directories should not be
completed after the `command` builtin.
Fixes#1695.
`exec` removes fish from the shell "stack", so SHLVL needs to be
decremented to match. This means `exec fish` will result in the same
SHLVL in the new fish instance.
Also tweak the SHLVL logic to interpret an environment SHLVL of "3foo"
as garbage instead of as the value "3".
Fixes#1693.
The wrong lock was being taken around the result queue, leading to the
occasional crash when processing interactive input. This didn't seem to
really affect normal day-to-day usage, but it did sometimes cause the
interactive tests to crash.
Fixes#1692.
As far as I know we can't access the build artifacts from Travis, so we
can't check the interactive logs after a test failure. Add an
environment variable that causes the test runner to dump the logs
itself, and set that variable for Travis.
Split `make test` into two targets `make test_low_level` and `make
test_fishscript`, primarily so fishscript tests can be rechecked quickly
after edits.
Reformat the test.fish file and update some of the code to be a little
more straightforward (e.g. `if not cmd` instead of `if cmd; else`).
This includes:
- Fixing some typos and misspellings
- Being consistent with pronouns (she/he)
- Hyphenating "built-in" and "command-line" where appropriate
Widened 'Commands' menu + fish logo
fish logo added to FAQ menu
'Commands' menu content aligned with Docs menu
'FAQ' menu content aligned and made 1st order as all entires are long
and wrap.
Setting a non-existant path component to PATH logs an error to stderr.
This is not appropriate for non-interactive temporary modifications,
like the one done by the `sudo` completion helper function.
Major documentation cleanup and update.
- Fixes Issue #1557
- Moves entire documentation to Markdown format. Much simpler.
- Fully supports Doxygen 1.8.7+
- All documentation targets updated: user_doc, share/man, doc and
doc/refman.pdf.
- Tested across Ubuntu, CentOS and Mac OS.
See doc_src/FORMATTING.md for in depth rationale and style guide.
Doxygen 1.8.6 and lower do not have the \\htmlonly[block] directive
which fixes a multitude of problems in the rendering of the docs. In
Doxygen 1.8.7 the list of understood HTML entities was greatly
increased. I tested earlier versions and many little issues returned.
Completely fixes#1557 and the underlying Doxygen changes that caused
it. Should make fish docs simpler and more robust, more consistent and
generally prettier.
todo:
- trap unmarked text as arguments in context
- test & fix sed portability - see in particular. (so far tested on BSD
(Mac) and GNU sed).
- test Makefile changes
- last round of aesthetic changes and getting that ascii fish in there…
Addresses issue #1557 as well as fixing many typos, HTML errors and
inconsistencies. Also introduces automatic syntax colouring and enables
new documentation to be written in Markdown. TODO fix Tutorial.
Rework for Doxygen >1.8. Moved large parts of the documentation to a
simplified format, making use of Markdown enhancements and fixing bad
long options.
When using `complete -c foo -l bar -e`, all long options for the command
were being erased because it was also comparing the short option, which
was 0.
When $IFS is empty, command substitution no longer splits on newlines.
However we still want to trim off a single trailing newline, as most
commands will emit a trailing newline and it makes it harder to work
with their output.
The screen size is fetched after a SIGWINCH is delivered. The current
implementation has two issues:
* It calls ioctl() from the SIGWINCH signal handler, despite ioctl() not
being a function that is known to be safe to call.
* It's not thread-safe.
Signals can be delivered on arbitrary threads, so we don't know if it's
actually safe to be modifying the cached winsize in response to a
signal. It's also plausible that the winsize may be requested from a
background thread.
To solve the first issue, we twiddle a volatile boolean flag in the
signal handler and defer the ioctl() call until we actually request the
screen size.
To solve the second issue, we introduce a pthread rwlock around the
cached winsize. A rwlock is used because it can be expected that there
are likely to be far more window size reads than window size writes. If
we were using C++11 we could probably get away with atomics, but since
we don't have that (or boost), a rwlock should suffice.
Fixes#1613.
When a key is bound to a fish function, if that function invokes
`commandline`, it gets a stale copy of the commandline. This is because
any keys passed to `self-insert` (the default) don't actually get added
to the commandline until a special character is processed, such as the
R_NULL that gets returned after running a binding for a fish command.
To fix this, don't allow fish commands to be run for bindings if we're
processing more than one key. When a key wants to invoke a fish command,
instead we push the invocation sequence back onto the input, followed by
an R_NULL, and return. This causes the input loop to break out and
update the commandline. When it starts up again, it will re-process the
keys and invoke the fish command.
This is primarily an issue with pasting text that includes bound keys in
it. Typed text is slow enough that fish will update the commandline
between each character.
---
I don't know of any way to write a test for this, but the issue can be
reproduced as follows:
> bind _ 'commandline -i _'
This binds _ to a command that inserts _. Typing the following works:
> echo wat_is_it
But if you copy that line and paste it instead of typing it, the end
result looks like
> _echo wat_isit
With this fix in place, the pasted output correctly matches the typed
output.
expand_variables() is slightly confused about how to handle last_idx. On
input, it expects it to be the index to start processing at, but when
called recursively it always passes the current index. This means that
it may sometimes pass an index 1 past the end of the input string.
Notably, that happens when typing something like
> echo "$foo
(where "foo" is any string that is not a prefix of some existing
variable name)
Fix this by explicitly defining last_idx as being the last processed
index, meaning the next index to process is actually last_idx-1. This
means we should call it with next.size() instead of next.size()-1.
gcc interpretes C99's compound literals more strictly by invalid the
compound literal on implicit to pointer cast (because of automatic
storage duration, 6.5.2.5.6 in C99 standard draft).
This fixes the issue by not using compound literals at all.
In the base config.fish, fish_function_path and fish_complete_path have
$__fish_datadir/{functions,completions} added to them if not already
present. For some reason they were replacing the final path component
instead of being added on to the end.
The new --wraps functionality was breaking aliases of the form
`alias foo='bar baz'`. That is, aliases where the body is multiple
words. Extract the first word of the body and use that instead.
Use better errors for aliases with no name or no body.
Remove the useless ASCII test of the first byte of IFS. We don't split
on the first character, we only use a non-empty IFS as a signal to split
on newlines.
IFS is used for more than just the read builtin. Setting it to the empty
string also disables line-splitting in command substitution, and it's
done this for the past 7 years. Some day we may have a better way to do
this, but for now, document the current solution.
The docs claimed that the $HOME and $USER variables could only be
changed by the root user. This is untrue. They can be changed by
non-root users as well.
Repurpose the ENV_INVALID return value for env_set(), which wasn't
currently used by anything. When a bad value is passed for the 'umask'
key, return ENV_INVALID to signal this and print a good error message
from the `set` builtin.
This makes `set umask foo` properly produce an error.
The span now properly points at the token that was invalid, rather than
the start of the slice.
Also fix the span for `()[1]` and `()[d]`, which were previously
reporting no source location at all.
We can't color the whole argument as an error, since the tokenizer is
responsible for that and doesn't care abou this case, but we can color
the `$foo[` bit as an error.
The backslash-escape wasn't being properly caught by the highlighter.
Also remove the highlighting of `"\'"`, as `\'` is not a valid escape in
double-quotes, and add highlighting for a backslash-escaped newline.
When a variable is parsed as being empty, parse out the slice and
validate the indexes anyway, behaving for slicing purposes as if the
variable had a single empty value.
Besides providing errors when expected, this also fixes the following:
set -l foo
echo "$foo[1]"
This used to print "[1]", now it properly prints nothing.
Double expansions of variables had the following issues:
* `"$$foo"` threw an error no matter what the value of `$foo` was.
* `set -l foo ''; echo $$foo` threw an error because of the expansion of
`$foo` to `''`.
With this change, double expansion always works properly. When
double-expanding a multi-valued variable, in a double-quoted string the
first word of the inner expansion is used for the outer expansion, and
outside of a quoted string every word is used for the double-expansion
in each of the arguments.
> set -l foo bar baz
> set -l bar one two
> set -l baz three four
> echo "$$foo"
one two baz
> echo $$foo
one two three four
The characters ANY_CHAR, ANY_STRING, and ANY_STRING_RECURSIVE are
currently transformed by unescape, but not by escape. Let's try escaping
them. Fixes#1614.
Add the --wraps option to 'complete' and 'function'. This allows a
command to (recursively) inherit the completions of a wrapped command.
Fixes#393.
When evaluating a completion, we inspect the entire "wrap chain" for a
command, i.e. we follow the sequence of wrapping until we either hit a
loop (which we silently ignore) or the end of the chain. We then
evaluate completions as if the wrapping command were substituted with
the wrapped command. Currently this only works for commands, i.e.
'complete --command gco --wraps git\ checkout' won't work (that would
seem to encroaching on abbreviations anyways). It might be useful to
show an error message for that case.
The commandline builtin reflects the commandline with the wrapped
command substituted in, so e.g. git completions (which inspect the
command line) will just work. This sort of command line munging is
also performed by 'complete -C' so it's not totally without precedent.
'alias will also now mark its generated function as wrapping the
'target.
Completely fixes#1557 and the underlying Doxygen changes that caused
it. Should make fish docs simpler and more robust, more consistent and
generally prettier.
todo:
- trap unmarked text as arguments in context
- test & fix sed portability - see in particular. (so far tested on BSD
(Mac) and GNU sed).
- test Makefile changes
- last round of aesthetic changes and getting that ascii fish in there…
- Require all requests to use a session path.
- Use a redirect file to avoid exposing the URL on the command line, as
it contains the session path.
Fix for CVE-2014-2914.
Closes#1438.
- Require all requests to use a session path.
- Use a redirect file to avoid exposing the '/start' URL on the
command line, as it contains the cookie value.
Fix for CVE-2014-2914.
Closes#1438.
- Change fishd_path to std::string
- Warn, rather than exiting with an error, if the universal variable
server path is not available, and provide more useful advice.
- Export the new __fishd_runtime_dir variable.
- Use a secure path for sockets (some code used under license from
tmux).
- Provide the secure path in the environment as $__fish_runtime_dir.
- Link the new path to the old path to ease migration from earlier
versions.
Closes#1359.
After installing fish built from or after this commit, you MUST
terminate all running fishd processes (`killall fishd`, `pkill fishd`
or similar). Distributors are encouraged to do this from within their
packaging scripts. fishd will restart automatically, and no data should
be lost.
Addresses issue #1557 as well as fixing many typos, HTML errors and
inconsistencies. Also introduces automatic syntax colouring and enables
new documentation to be written in Markdown. TODO fix Tutorial.
Rework for Doxygen >1.8. Moved large parts of the documentation to a
simplified format, making use of Markdown enhancements and fixing bad
long options.
Currently fish doesn't recognize toor as special. However, it's likely
that on BSD systems, fish shell will be used on toor, not on root (toor
is an intentionally existing account to use more advanced shell on, like
shell).
This stops unconditionally setting values for HOME and USER,
if we find those values in the environment. It also saves about 16KB
on OS X, which getpwuid allocates.
When running `make test` we want to use the local function definitions,
not the ones installed on the system.
The system config.fish will still insert the system definitions at the
end, but at least ours will take precedence.
Enhance the `read` builtin to support creating an array with the --array
flag. With --array, only a single variable name is allowed and the
entire input is tokenized and placed into that variable as an array.
Also add custom behavior if IFS is empty or unset. In that event, split
the input on every character, instead of the previous behavior of doing
no splitting at all.
One of the tests was using `>/dev/null` to suppress the `type` output.
That needs to be `^/dev/null` now, but instead just go ahead and use the
new `-q` flag.
Use `functions -q` instead of searching the `functiosn -na` list for the
provided word. This may result in an automatically-loaded function being
sourced, but that happens anyway with the default output.
This change means the results of `test -q foo` can be relied upon to
indicate whether `foo` can actually be invoked. Previosly, if `foo` was
the name of an automatically-loaded function file but did not actually
define a function `foo`, and there was no execuable `foo`, then `type -q
foo` would lie and say `foo` can be invoked when it can't.
The --quiet flag is useful when only the exit status matters.
Fix the documentation for the -t flag to no longer claim that `type` can
print "keyword", as it never does that.
Stop printing a blank line for functions/builtins when the -p flag has
been passed. It's just not useful.
Track whether -a and -f have been supplied separately. That way both
`type -a -f command` and `type -f -a command` behaves correctly, as does
`type -a -f foo` where there are multiple executables named `foo` in the
$PATH.
Stop using getopt to parse flags. It's far more expensive than
necessary, and results in long flags not being parsed on OS X. This also
allows args starting with - after the options list to be properly
interpreted as a value to test.
Print the error message to stderr as is appropriate.
Use the new `command -p` functionality when the -a flag has not been
provided (`command` does not have any equivalent to the -a flag),
instead of using `which`. This is faster and also avoids any possible
disagreement between `which` and what fish thinks is valid.
Stop testing every path to see if it's executable, that test has already
been done by `which` or `command -p`.
The end result is `type -P ls` is roughly 250% faster, according to
profiling, on my OS X machine.
Instead of introducing a new local scope at the point of `set`, merely
push a new local scope at the end of env_init(). This means we have a
single toplevel local scope across the lifetime of the fish process,
which means that
set -l foo bar
echo $foo
behaves as expected, without modifying the global environment.
The mode restricts the scope in which the variable is searched for.
Use this new restricted scope functionality in the `set` builtin. This
fixes `set -g` to not show local shadowing variable values, and also
allows for scoped erasing of slices.
When attempting to set a readonly or electric variable in the local or
universal scopes, print an appropriate error. Similarly, print an error
when setting an electric variable as exported. In most cases this is
simply a nicer error instead of the 'read-only' one, but for the 'umask'
variable it prevents `set -l umask 0023` from silently changing the
global value.
They're dynamically calculated, so they qualify. This also removes them
from the list of exported global variables, because they're actually not
exported.
When using the `set` command with the -l flag, if we're at the top
level, create a temporary local scope. This makes query/assignment
behavior be consistent with the value-printing behavior.
This works by marking the current block as needing to pop the
environment if a local scope was pushed. I assume this is safe to do. I
also assume the current block is the right one to modify, rather than
trying to walk up the stack to the root.
env_exists() wasn't properly handling multiple scopes in some cases,
notably with readonly/electric variables. Rewrite it to operate in a
more straightforward fashion.
When initializing fish, ignore any inherited environment variables that
match any of the readonly or electric variable names.
This prevents really weird behavior when e.g. fish is launched with
COLUMNS already set to something. In that case, testing $COLUMNS within
fish behaves normally, but any subprocesses get the value that fish
itself had inherited.
The inotify notifier is fragile, fails on travis, and fails to compile
on certain Linux kernels. It doesn't appear to work as well as the named
pipe mechanism. Best to just get rid of it.
In the new mode (not yet enabled), universal variables are set by reading and writing the fishd file directly, with some file locking for synchronization. This enables forwards and backwards compatibility. However there is no compatibility with simultaneous edits. Changes may be lost if fishd and the new mechanisms both attempt writes.
fishd is still enabled by default for now; it will be disabled in a future commit. You can opt into the new mechanism (disabling fishd) by setting the environment variable fish_use_fishd to 0 before starting fish. This cannot itself be a universal variable, because of bootstrapping: the value is needed to determine how we read universal variables in the first place.
Universal variable change notifications (i.e. reacting immediately to live edits) are tricky. Checking for changes is simple and relatively inexpensive (just a stat()), but relying solely on that would require frequent wakeups, and show up in fs_usage. So how do we get change notifications into an fd that we can monitor via select()? We support a few strategies, expressed as universal_notifier_t::notifier_strategy_t. By default we use notifyd on OS X and a named pipe on Linux / everywhere else. This is also configurable at runtime via the fish_universal_notifier variable.
* use $XDG_CACHE_HOME for __fish_print_packages completion caches
* when starting fishd, redirect fishd output to /dev/null, not a
predictable path
Fix for CVE-2014-3219.
Closes#1440.
Currently it contains strange code like using `do` loop in order to
avoid `goto`s (they aren't evil, honestly), the pointless `if (mem)`
conditional which doesn't even work (had semicolon for some reason).
You may think this code had a bug where the code didn't check for
the pointer to be null before calling `free`, but this is not the case,
as according to C and C++ standard, `free` should allow `NULL` pointers,
and ignore them.
When you chroot in Debian, bash shows the chroot environment in the prompt:
```bash
...
if [ -z "${debian_chroot:-}" ] && [ -r /etc/debian_chroot ]; then
debian_chroot=$(cat /etc/debian_chroot)
fi
PS1='${debian_chroot:+($debian_chroot)}\u@\h:\w\$ '
...
```
This is the effect:
```
(chroot_env) user@host:~#
```
It is useful when chrooting, since usually the hostname remains the same and thus you can't distinguish where you are.
This removes undefined behavior in the previous code by properly
checking for miliseconds (actually typing proper names, not abusing
pointer arithmetics).
Now fish shell stores version is a small file called by other files.
This means that a slight change which modifies one file won't cause
many of files to recompile.
The compilation unit is intentionally small, this is by design. The
smaller it is, the faster it will recompile, and it will be compiled
a lot.
This makes white work properly in white terminals when used for
`fish_color_*` variables. It's probably silly thing this small
mistake breaks, to be honest, but it's still a bug.
Fix for CVE-2014-2906.
Closes a race condition in funced which would allow execution of
arbitrary code; closes a race condition in psub which would allow
alternation of the data stream.
Note that `psub -f` does not work (#1040); a fix should be committed
separately for ease of maintenance.
Closes#1437
Fix for CVE-2014-2906.
Closes a race condition in funced which would allow execution of
arbitrary code; closes a race condition in psub which would allow
alternation of the data stream.
Note that `psub -f` does not work (#1040); a fix should be committed
separately for ease of maintenance.
The if statement checking the output of hg bookmarks uses two conditions
joined by the or keyword. However, only the first part was being used.
Wrapping the two statements with begin and end properly combines them.
At some point the non-verbose, non-informative variant of the prompt
(e.g. the variant that looks like the bash prompt) was modified to try
and show the behind/ahead counts the same way the informative prompt
does. Besides being wrong, it also didn't work because behind/ahead
weren't defined.
configure will no longer check for the existence of extra include, lib
and bin directories in /usr/pkg /sw /opt /opt/local /usr/local.
The check was not done in a particularly sensible manner and there are
now no mandatory dependencies that not shipped in the main system trees
on virtually every system in existence.
If building with Fink, follow these directions as suggested by the fink
project:
http://www.finkproject.org/faq/usage-general.php#compile-myselfCloses#1185, and closes#1186.
This change replaces fish's execution model, and obviates much of
parser_t. Instead of parsing fish code into a sequence of
commands-arguments, this reifies syntactic constructs into a grammar,
builds a parse tree, and executes that. This provides a big
simplification and (sometimes) performance boost. fish while loops
become C++ while loops, etc.
There are some known regressions in error reporting, which ought to be
fixed in the soon-to-be-merged parser_cleanup branch. There's also
legitimate changes in edge cases. For example, `command builtin ...` now
executes a command called "builtin" instead of doing something else
weird. The most significant change is that syntactic elements must be
unexpected: for example, single quoting 'command' will now cause it to
not be recognized. This should be fixed soon.
Please open issues for any regressions you find!
parse_error_list_t through all of the expand functions, enabling them to
report errors more directly. Improve aspects of error reporting for
expansion failures.
Conditionally uninitialized:
- builtin_commandline.cpp:577
- expand.cpp:869
- parse_util.cpp:1036
Initialization of POD structs:
- event.cpp:61
- autoload.cpp:22
References used with va_start:
- common.cpp:608:18
Found with clang-3.4's awesome -Wconditional-uninitialized,
-Wmissing-field-initializers and -Wvarargs.
Before this change, fish config used 0 as its address. However, this
isn't a good idea from security point of view, as web service can be
accessed from everywhere, and do anything on the account it was ran on.
This also deals with firewalls which block the access to 0 even from
the host machine itself. It possibly might fix#673, but I'm not sure.
Previously, fish's command_not_found handler would be installed in
__fish_config_interactive. Errors that occured early in startup (e.g. in
config.fish) or in non-interactive mode would therefore not be reported.
With this change, fish now exposes its default cnf handler as
__fish_default_command_not_found_handler . config.fish then installs a
cnfh that invokes the default. When fish goes interactive, the initial
cnfh is overwritten with a fancier one, that may in turn fall back to
invoking the default.
promote it to a decoration (like 'command' or 'builtin'). This makes tab
completion and syntax highlighting treat exec's first argument as a
command and is otherwise a nice simplification. Fixes#1300
is specified before Y, then Y will never be invoked because X will
always get there first. Now instead we order bindings in descending
order by length, so that we always test the binding before any others that
prefixes it. Fixes#1283.
commit d81ae2665f
Author: Max Gonzih <gonzih@gmail.com>
Date: Sun Feb 2 16:22:18 2014 +0300
Check for command-not-found command on suse
commit 004b794c82
Author: Max Gonzih <gonzih@gmail.com>
Date: Sun Feb 2 14:04:41 2014 +0300
Fix cnf handler for Suse and Fedora
fixes#1208
Presently, `isatty` only works on a handful of keywords. Here it
is rewritten to be able to take any path, device or fd number as
an argument, and eliminates errors printed to stdout.
Per discussion in #1228, using `builtin test -c` within a pipe to
test special file descriptors is not viable, so this implementation
specifcially uses `command test`. Additionally, a note has been
added to the documentation of `test` regarding this potential
aberration from the expected output of the test utility under the
'Standards' section.
Note: if you have previously cloned the repository, the tags for
previous versions have been edited. Use `git fetch --tags` to
synchronise your local copy.
Comment out 'o' binding
Add '['/']' bindings to navigate current token history
Fix 'P' to paste indeed
Add "*P/"*p to insert current selection clipboard using xsel
These options will be passed to the bind command.
Now it's possible to call
fish_default_key_bindings -M insert
to set all original bindings to the insert mode
The following normal mode bindings are added:
o, I, A, gg, G, g^, g$, x, X, backspace, d*, D, s, S, c*, C, ~, gu,
gU, J, K, y*, Y, p, P
I was not able to add binding for 'O'
dd now deletes the whole line as vim, while D deletes the line to the
end. c, s, y act the same way
The parser here is a LL(2) parser, which is handwritten (to avoid complicating the build process and to maintain good control over error reporting, thread safety, etc). Later it's worth exploring using parser generators (lemon, etc) or other tools to simplify things.
This commit enables the new parser for syntax highlighting, completions, and abbreviations. Syntax highlighting retains the old implementation (disabled), which will be removed shortly. There is also support for a new execution model, based on the new parser, but it is disabled by default (can be enabled by setting the fish_new_parser variable to 1).
There's also lots of new tests, and some machinery for selecting which tests to run.
After living on this commit for a while, we'll enable the new execution model by default, and then begin to tear down the machinery of the old one (the block types, builtin_end, the parser_t junk, etc.). After that we can pursue even more exotic execution models, like multithreaded ones.
(The branch name is really a misnomer - the tree here is a parse tree, or concrete syntax tree, not an abstract one.)
Fixes#557
It would be nice if this would work without this hack,
but until then, this has to work. Requires you to reinstall
the prompt using fish configuration system.
in reader_shell_test, so that there's always a statement terminator.
Otherwise commands like 'echo |' would not be considered an error (just
incomplete).
Continuation of https://github.com/fish-shell/fish-shell/pull/1195/.
Removes use of --delimiter and --fields with cut(1) as these are GNU
extensions.
Note that a number of completions use these options, but as they are
only for GNU/Linux-specific tools have remained unmodified.
Issue #1108: If there are special characters like '{' in the
completion suggestions, then we fail to parse it successfully
as we are passing an unescaped version of the character to
parser_t::eval_args(...).
This causes us to retun w/o completion suggestions.
This bug was discovered while implementing 'git stash' completion
as the suggestion contained strings like 'stash@\{0\}'.
Th fix is to properly escape the string before parsing it.
This was a really stupid change that I should have tested more
before pushing. It broke any non-interactive usage, such as SSH,
fish config, or parsing the script output, as config.fish is
loaded for everything.
There are no issues with different terminal emulators, so this
change will be pushed in the future, but only running in interactive
mode. I apologize for any issues caused by this commit.
This reverts commit d61adfbc53.
Some people like to have their terminals claim UTF-8 support when
their terminals actually are set to another encoding. As nobody
appears to understand this, I have made a change to automatically
fix the encoding problems if possible. This uses ISO 2022 sequences
in order to dynamically change the encoding.
Fixes#692. Fixes#895. Fixes possible future issues about this.
* Show color scheme title in preview box
* Show information about setting terminal background color on Apply
button mouse hover
* Added text_color_for_color method in colors controller scope
Removes some unused variables and out-of-date references.
Wraps some tests in quotes to avoid expansion errors.
Removes the fish.spec generated file as it is out of date and is
arguably better maintained by downstream packagers.
See http://github.com/zanchey/fish-build/ for a better RPM spec file.
This stops fish from accessing the `bool ok[UCHAR_MAX + 1]` table
beyond allocated space potentially accessing memory that doesn't
belong to fish, and crashing.
It appears that Intel C compiler doesn't recognize unsigned wchar_t,
however it doesn't appear to be important (the conversion function is
unused, and in other cases it doesn't appear to be needed).
Closes: https://github.com/fish-shell/fish-shell/issues/1060
'ansi' should always be present (tested on Solaris, Linux, FreeBSD,
Darwin).
Also overrides TERM so that other programs behave consistently e.g.
fish_pager.
The error message makes no specific mention of terminfo or termcap as
these vary across operating systems.
(r+ @ridiculousfish with thanks)
The intention of the block removed appears to be to indent wrapped lines to the column the line started at. What actually happens is that all wrapped lines wrap to column 0.
After adding the sticky short prompt feature, the block removed caused a bug with wrapping wide characters in addition to not appearing to change anything else.
Wide characters would change between wrapping to column 0 and the column the command started at, depending on what column the wide character was at before wrapping.
I am keeping the existing behavior rather than restoring the block's original intention. If the original intention should be restored, it should be on a different branch.
From the Python webbrowser documentation:
"If text-mode browsers are used, the calling process will block until the user exits the browser."
Running fish_config on an ssh server with no GUI browser will open a CLI browser which blocks and stops the server from handling requests.
Using multiprocess to run the server in the background lets CLI browsers access the page, but the page is unusable.
For now, disable CLI browsers and recommend opening the page in a graphical browser.
In the future, maybe write a CLI utility to change prompts and delete history items.
printf expects unsigned long (%lu) argument, however, size_t doesn't
have to be declared as such. As %zu is C99 (but not C++), it shouldn't
be used directly. Instead, I have to cast value to the correct type.
When launching the first instance of fish and fishd is not launched already, this should not be considered an error as long as it can be launched. So ignore the first failure of connect(), as the calling function get_socket() will try again. May need a bit of cleanup.
Prefer the standard library lzma module if available. This change prevents
using the backports-lzma when it is installed for a version of Python that
already has the lzma module in its standard library.
- expunge LIBS_COMMON, it doesn't get used anywhere
- don't reset LIBS to empty
- move the gettext test as every binary depends on it
- only include one set of libraries
They cannot be used as arguments (Perl thinks it's version check, but
version checks are pointless for oneliners), and Debian puts path
containing version depending directories (like 5.14.2) in Perl path.
There is no need to explicitly check for two arguments and set --bold.
Instead the user can simply "set __fish_git_prompt_color_flags --bold
red".
The current check violates the expectation set by the documentation
that you can use any set_color argument as the current code interprets
"--bold red" as "--bold --bold" instead.
Plus, by passing the full contents of the variable directly, the user
can do more adventurous things like set the background as well.
git.git's git-prompt may not contain a configurable prefix, but it
does display a space before the upstream information when displaying
verbose information. Rather than using a space always or never,
default to a space whenever verbose is in showupstream.
Adds a "name" option to __fish_git_prompt_showupstream that shows an
abbreviated branch name when the upstream type is verbose.
Based on git.git 1f6806c: git-prompt.sh: optionally show upstream
branch name
Per my understanding this is not undefined behavior. No ABI depends on the called function reading
variadic arguments, nor does any standard require it. So if this is crashing something else must be going
on.
This reverts commit 22d22f6aa8.
Having function that takes arbitrary number of arguments without
actually reading them is undefined behavior, as it could cause stack
to be in the corrupted state. Now arguments after token are parsed,
even if they aren't needed.
See also: http://asciinema.org/a/5904
Add support for bzip2 and lzma/xz compressed man pages. Support for bzip2 is
part of the Python standard library (at least for 2.7 and >=3.2), while lzma/xz
is only in Python >=3.3; however, there is a backports module for Python 2.7 and
3.2.
1. Use Bash-like expansion for empty searches (when you just use a '%' by
itself).
'%' will now *only* match the last valid backgrounded process.
If there are no such processes, an expansion error will be generated.
'%' by itself would previously match either *all* backgrounded
processes, or failing that, all processes owned by your user. If you
ever tried to run `kill -9 %`, it would either kill all backgrounded
processes or *all* of your processes. I'm not sure why anyone would ever
want that to be a single keystroke away. You could almost typo it.
As a result, `fg %`, `bg %`, `kill %`, etc will all operate on the last
process touched by job control.
2. Don't run 'by-name' matches when the search term is numeric.
This prevents you from running a command like `kill %1` and accidentally
killing a process named something like "1Command". Overloaded behavior
can be dangerous, and we probably shouldn't play fast and loose with
expansion characters that generate process IDs.
Closes#479 by piping STDERR to /dev/null.
Also does much less manipulation of the package list; there are no
packages in any of the archives containing the names that are stripped
out as far as I can see.
Include config.h.in as well as configure.
Also sets correct owner, group and mode for all appended files.
Update the mtime of all appended files so that configure and config.h.in
are always newer than configure.ac.
(Fixes many problems introduced by 5023ade7, and makes the commit
message actually true.)
For the next release, this means that `autoconf` is no longer required
if building from the tarball. The website and documentation should be
updated accordingly at that time.
When the completion list includes the exact typed string with other
candidates, i.e. completion_t.match.type == fuzzy_match_exact,
the other candidates will be removed from the list, as they are not
the "best type". This is inconvenient for the user who wants to
type and complete commands in the other candidates.
The commit is to make the best_type to fuzzy_match_prefix as highest
priority, also, when comparing to best_type, the same or higher
priority completions can both match.
With this change, jobs only track their block-level redirections. Process level redirections are correctly associated with the process, and at exec time we stitch them together (block, pipe, and process redirects).
This fixes the weird issues where redirects bleed across pipelines (like #877), and also allows us to play with the order in which redirections are applied, since the final list is constructed right before it's needed. This lets us put pipes after block level redirections but before process level redirections, so that a 2>&1-type redirection gets picked up after the pipe, i.e. it should fix https://github.com/fish-shell/fish-shell/issues/110
This is a significant change. The tests all pass. Cross your fingers.
It's rather hacky, but it sort of works. (but then, this makes fish
compare to PHP (but PHP doesn't put that newline), so perhaps I
shouldn't do that - http://git.io/GFurbg)
m4_esyscmd_s is a macro only available in Autoconf 2.64, which despite
being released in 2009 is not available on a number of build targets for
the project (specifically CentOS/RHEL 6).
ca8e4c08a7 tries to remove the error produced with m4_pattern_allow,
but that just silences the sanity check.
Instead, replace m4_esyscmd_s with m4_esyscmd + manual removal of
newlines.
I break compatibility with Mac OS X again, that I don't have access
to. Result: Stuff break, and I have to fix it, so it will perhaps
work. At least, I hope it will work.
Yes, it's an awful hack, but IPC support (and fork support as well -
even FAQ mentions that, and suggests "restarting process" to solve the
problem (http://cygwin.com/faq/faq.html#faq.using.fixing-fork-failures),
but let's ignore that for now) is simply broken in Cygwin. Having to try
to do exactly same thing in Cygwin, just so perhaps it will work is a
completely normal thing (not). I love Windows.
I commited executables in previous commit (removed using git push
--force - sorry, I wouldn't want to waste space in git repository), so I
think *.exe files should be forbidden to avoid any problems (there is no
reason to ever commit them)
Yes, hostname is broken under Cygwin, but for fish it's an issue, as it
makes fish_config more buggy than it needs to be (by making UTF-8 errors
according to Python).
Note that this will NOT get updated on every run - even if autoconf is run manually, the value may be cached. The PACKAGE_VERSION variable/symbol will not be reliable. Use FISH_BUILD_VERSION instead.
This commit hooks the Makefile up to generate a FISH_BUILD_VERSION
symbol and kills off PACKAGE_VERSION in .cpp files.
It also modifies the tarball generation script to add the necessary
version file for releases.
git.git's __git_ps1 doesn't have an upstream prefix. I'm not sure why
one was added to our __fish_git_prompt, but it certainly shouldn't
default to a space.
It reuses $__fish_git_prompt_char_stateseparator, since it has a
similar meaning and goes otherwise unused when
$__fish_git_prompt_show_informative_status is set.
This changes the defaults for several characters when
$__fish_git_prompt_show_informative_status is set so that the prompt
looks more like the typical informative prompt.
Before: (master >1<2|+3#4*5%6)
After: (master↑1↓2|●3✖4✚5…6)
The defaults were taken from magicmonty/bash-git-prompt
This makes $__fish_git_prompt_show_informative_status imply
$__fish_git_prompt_showupstream = "informative", while adding a none
option for showupstream to disable it if desired.
plus speling in documentation for bind.
Note that this commit does not re-enable the generation of the manpage for
test, which will therefore still fall through to the system manual page with
`man test`.
(Closes#91, #932)
Currently, control-E is bound to `end-of-line`.
This patch modifes the `end-of-line` procedure so that, if it is invoked when
the cursor is at the end of a command and there is pending completion text,
it will accept the completion text and move to the end. The behavior of
`end-of-line` will not otherwise be altered.
A few characters and colors got added without being added to the event
list for repainting.
Also sort and re-align list of characters in validate_chars.
The code invoked `git rev-parse` several times when the required
information could be collected all at once.
This is based on the following commits from git.git:
efaa0c1: bash prompt: combine 'git rev-parse' executions in the main code path
e3e0b93: bash prompt: combine 'git rev-parse' for detached head
0f37c12: bash prompt: use bash builtins to check for unborn branch for dirty state
dd0b72c: bash prompt: use bash builtins to check stash state
It's a one line function called in a single place. I suspect it only
existed because the bash equivalent __gitdir existed (it was more
complex), but that function no longer exists either, as of git.git
511ad15: "bash prompt: run 'git rev-parse --git-dir' directly instead
of __gitdir()"
Simply using cut duplicates (poorly) `git rev-parse --short`
This also restores the ... printed after the abbreviation which
__fish_git_prompt had been missing.
Based on git.git e8f21ca: "bash prompt: print unique detached HEAD
abbreviated object name"
Unlike the rest of the __fish_git_prompt_char_* variables, it does not
have its own color because the most likely values are a space and
nothing.
based on git.git 15a54fb: prompt: introduce GIT_PS1_STATESEPARATOR
Adds a progress indicator to the rebase messages. (e.g. |REBASE 2/5)
based on the git-prompt portion of git.git b71dc3e: "bash-prompt.sh:
show where rebase is at when stopped"
git revert was taught to revert multiple commits, and it stores it
branch information in REVERT_HEAD just like the other *_HEAD files.
based on git.git 3ee4452: bash: teach __git_ps1 about REVERT_HEAD
Based on GIT_PS1_SHOW_COLORHINTS, it introduces more color by default
and also changes the color of the branch name based on if it is a real
branch or detached.
Based on the following commits from git.git:
9b7e776: show color hints based on state of the git tree
9b3aaf8: Fix up colored git-prompt
76c36c0: coloured git-prompt: paint detached HEAD marker in red
This is mostly useful for the next commit that will have different
colors default to different values, but it has one immediate change:
all __fish_git_prompt_color_* variables now default to
__fish_git_prompt_color instead of to nothing, as they used to.
* The original __git_ps1 function has split from the rest of
git-completion as of git.git af31a45
* Use the description for GIT_PS1_DESCRIBE_STYLE (added in git.git
50b03b0) for __fish_git_prompt_describe_style
* Update the description of __fish_git_prompt_showupstream to include
the meaning of '=' based on git.git f9db192: "Improve the
description of GIT_PS1_SHOWUPSTREAM"
* Note that the PROMPT_COMMAND versions of the command with extra
arguments don't work, in case someone used to the bash version is
looking for it.
* Note that I am updating the script so Kevin Ballard doesn't get
blamed for anything I break.
Operation and branch detection are merged together in the original
because branch information may come from different places depending on
the operation.
Merging the bare helper in helps avoid testing for the working
directory and bare status twice, both of which requires forking a new
process.
Also helps the code match the original more, which will make adding
new features easier.
Squashed commit of the following:
commit c208bc30b7747b3743212483b3dd7e3f90819f49
Merge: 97bea942633372
Author: Konrad Borowski <glitchmr@myopera.com>
Date: Fri Jul 19 09:56:12 2013 +0200
Merge branch 'command-not-found' of git://github.com/GlitchMr/fish-shell into command-not-found
commit 26333721b9
Author: Konrad Borowski <glitchmr@myopera.com>
Date: Fri Jul 19 09:55:13 2013 +0200
Fix command_not_found when not found
commit db34460bb5
Author: Konrad Borowski <glitchmr@myopera.com>
Date: Wed Jul 17 13:41:57 2013 +0200
Avoid showing standard command not found message when possible
In bash, command-not-found handler causes the standard messages to
not appear. Because of events model in fish, it isn't really an
option, so I moved the standard command not found message to
fish function. This way, the messages aren't repeated, and the
standard command not found message appears only when handler
couldn't be found.
* Added FreeBSD's pkg to __fish_print_packages
* Portmaster completes on installed packages and ports
* Options list as per fish_generate_completions, needs to be tidied
up further but will suffice for now
$git_dir was never set in __fish_git_prompt_current_branch, but used
in the case of a detached HEAD. This caused `cut -c1-7 $git_dir/HEAD`
to expand to `cut -c1-7` which then waited for input.
The code in question displays GIT_DIR! if the user is inside the .git
directory of a repository that has a working directory. Several git
commands won't work in that situation, so it's useful to warn the
user.
Normally I wouldn't bother, but it was difficult to follow the nested
if statements. Most of the file used tabs, so replaced all leading
spaces with the appropriate amount of tabs.
Relevant section lifted from scp.fish
Silenced SSH output to squash banners and failed connections
Erroneous 'and true' removed
echo (commandline -ct) is exactly the same as commandline -ct
commit 5a577d970a293afe320b6c3280c10c2bd8a1ff50
Merge: 908b07596941b3
Author: ridiculousfish <corydoras@ridiculousfish.com>
Date: Sat Jun 1 22:59:16 2013 -0700
Merge branch 'dotdir-two-chars' of git://github.com/GlitchMr/fish-shell into GlitchMr-dotdir-two-chars
commit 96941b3a92
Author: Konrad Borowski <glitchmr@myopera.com>
Date: Sat May 25 09:55:43 2013 +0200
Support BSD sed
commit 60652c2bd2
Author: Konrad Borowski <glitchmr@myopera.com>
Date: Sun May 19 10:58:40 2013 +0200
Show first two characters for dotdirs. Fixes#754.
I haven't noticed that because I tested ack in directory with one file.
After @gfxmonk sent issue #797, I have noticed the problem. This patch
fixes#797 by escaping question mark.
I recently switch from ZSH to Fish shell and noticed that this theme is slightly different to the one provided by ZSH. I edited my own using funced but thought it might be useful for other people who are used to the ZSH interface.
commit 4a9595845111bcc8d45419241f8f49bc3e8b3445
Author: Harm Aarts <harmaarts@gmail.com>
Date: Fri May 24 10:45:58 2013 +0200
use the new functions
commit 1c934ebbe65a82e92079952b15f31d3a92bc5e8f
Author: Harm Aarts <harmaarts@gmail.com>
Date: Fri May 24 10:45:21 2013 +0200
moves formatting code to the bottom in order to get it out of the way of all the colour handling
commit c62f827143c30f6810026c7e4a3d8b77178cd9a4
Author: Harm Aarts <harmaarts@gmail.com>
Date: Fri May 24 10:44:12 2013 +0200
adds helper returning whether or not there are staged files
commit 624e47cb85a7579bf284a6a7f0c9165dfa38b0ce
Author: Harm Aarts <harmaarts@gmail.com>
Date: Fri May 24 10:43:41 2013 +0200
adds helper returning whether or not the current branch is dirty
commit efc270da7b0998f564a7d2ae4ea3013ed6910e58
Author: Harm Aarts <harmaarts@gmail.com>
Date: Fri May 24 10:42:48 2013 +0200
adds helper returning whether or not a repo is bare
commit 0da668316cedb8e3fa166977be82c917ef67ad86
Author: Harm Aarts <harmaarts@gmail.com>
Date: Fri May 24 10:41:55 2013 +0200
adds helper returning current branch
commit 15cbcedc77199aea1868faee5d178d9547a4d541
Author: Harm Aarts <harmaarts@gmail.com>
Date: Fri May 24 10:41:10 2013 +0200
adds helper returning current operation
commit c3352d3e9e60bf94fd4bf412ad85d62bba4cbff8
Author: Harm Aarts <harmaarts@gmail.com>
Date: Fri May 24 10:40:20 2013 +0200
adds helper returning the git dir
commit f346e52b7814ebf1eed55f006c3bedc8ece38e3b
Author: Harm Aarts <harmaarts@gmail.com>
Date: Mon May 20 18:52:19 2013 +0200
use the fish_git_prompt_char_* variables
Large list of changes, including formatting and typos for most commands.
More substantive changes have been made to alias, bind, block, break,
builtin, case, cd, commandline, count, else, emit, fish_config, funced,
function, functions, history, math, mimedb, nextd, not, popd, prevd,
pushd, pwd, random, read, set, set_color, switch, test, trap, type,
ulimit, umask, and while.
Since set_color was changed to a built-in command, the entire shell will
exit in the event that setupterm() fails for some reason since ncurses
does an exit() if an errret was not passed in.
setupterm() can fail if the TERM environment variable is not set. This can
cause the shell to die prematurely if set_color is called from a startup
file like config.fish (such as vi-mode.fish which caches the results of
set_color when it is loaded) and fish is started without a TERM set
(e.g. when started from .xsession, or when being used as a remote shell
by a command such as rsync, scp or git)
A simple repro case for this issue is:
ian@delenn~ [i]> echo set_color normal > ~/.config/fish/config.fish
ian@delenn~ [i]> scp localhost:test .
TERM environment variable not set.
ian@delenn~ [i]>
This patch passes in an errret variable to setupterm(), which causes
ncurses to return the error to builtin_set_color() rather than calling
exit():
ian@delenn~ [i]> scp localhost:test .
test 100% 0 0.0KB/s 00:00
ian@delenn~ [i]>
Signed-off-by: Ian Munsie <darkstarsword@gmail.com>
- Clarify wording in functions section
- Use the term aliases rather than wrappers
- Clarification of concepts and better? examples in variable expansion
- Likewise in environment variables
- Using the phrase builtin commands rather than builtins
- Tidy up keybindings a bit
- Another example in the history section
- Remove TODO section in favour of mailing list, GitHub and IRC link
The compiled-in path to bin dir was not correct; it made the
common assumption that `$(prefix)` == `$(prefix)/bin` which is
usually true, but not in all cases.
1. [machine specific files](http://www.gnu.org/prep/standards/html_node/Directory-Variables.html#index-exec_005fprefix)
should use `$(exec_prefix)` (`@exec_prefix@` in Makefile.in)
instead of the usual `$(prefix)`.
2. [executable programs](http://www.gnu.org/prep/standards/html_node/Directory-Variables.html#index-bindir)
should use the more-specific `$(bindir)` (`@bindir@` in Makefile.in)
instead of assuming `$(exec_prefix)/bin` as this allows the
executable install location to be changed with the
`--bindir=_foo_` option to `./configure`.
Fortunately, the makefile is mostly correct and *installs* the
executable in the correct location. The problem shows up later
such as during tab-completion, when fish_pager is run - the
compiled-in path it uses was the incorrect `$(prefix)/bin`
resulting in an "Unknown command" error, which only required
this small fix.
Using arg completion
Context-based completion for most of commands (i.e. only installed
packages for upgrade or remove, only outdated for upgrade and so on)
Valid DNS names cannot have a | character and hashed ssh hosts
always begin with the | character. Therefore we ignore lines that
begin with |.
Signed-off-by: Greg Dietsche <Gregory.Dietsche@cuw.edu>
On FreeBSD, compilation complains that "this file includes
<sys/termios.h> which is deprecated, use <termios.h> instead". On Linux
and FreeBSD, <sys/termios.h> literally just pulls in <termios.h>. On OS
X and Solaris, <termios.h> pulls in <sys/termios.h>.
<termio.h> doesn't exist on FreeBSD or Mac OS X, and on Linux is marked
as deprecated and just includes <termios.h>. It does exist on Solaris,
but no `struct termio` is ever actually used in the codebase.
When dulicate_prepend prepend copies of block_io elements to j->io, the
removing simply does nothing. Now that the same pointers are prepended to
j->io, don't remove them.
This flag is used for the backtrace() function. It provides more information
for the backtrace on Linux, but is useless on OSX.
Signed-off-by: lledey <lledey@gmail.com>
Try to import parse_qs from the cgi module, and simplejson instead of json.
Use old string formatting. str.format() was backported from Python 3
to 2.6 and isn't available in 2.5.
The previous command outputs a lot of junk, does not strip after the
white-space in OSX (10.8.2).
Tried out the new command on both Ubuntu (12.04.1) and OSX (10.8.2)
- Fix branch for older git version (--short for symbolic-ref was not
available on git 1.7.9.5)
- Use index (git status) for checking if staged
- Add status indication for copied
- Remove variables for statuses (less litter in the variables)
- Remove usage of eval to echo and set_color
- Replace printf where possible with echo -n
After updating, fish would immediately die when started in an xterm from
my window manager (wmii) with a message like:
fish: builtin.cpp:3357: int builtin_end(parser_t&, wchar_t**): Assertion `false' failed.
fish: Job 1, “~/code/fish-shell/fish” terminated by signal SIGABRT (Abort)
Starting fish from an existing shell worked, and running it on other
machines that I was only SSHing into worked as well. I did discover that
on one machine starting git from one specific directory
(/home/ian/bml/kernel) would cause this failure, but starting from any
other directory worked as normal. I'm not entirely sure what
circumstances contribute to this failure - starting from a copy of the
kernel directory works fine.
The failure only started with the following commit, which introduced the
assert(false):
commit d788c84440
Made type property of block_t constant and private
Further work towards cleaning up block_t hierarchy
Looking at this fail in gdb:
(gdb) r
Starting program: /home/ian/code/fish-shell/fish
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
fish: builtin.cpp:3357: int builtin_end(parser_t&, wchar_t**): Assertion `false' failed.
Program received signal SIGABRT, Aborted.
0x00007ffff6c82475 in *__GI_raise (sig=<optimized out>) at ../nptl/sysdeps/unix/sysv/linux/raise.c:64
64 ../nptl/sysdeps/unix/sysv/linux/raise.c: No such file or directory.
(gdb) bt
function=0x548520 "int builtin_end(parser_t&, wchar_t**)") at assert.c:81
(gdb) up 3
3357 assert(false); //should never get here
(gdb) p parser.current_block->type()
$1 = FAKE
So this happens when we run an end command for a FAKE block.
The below patch adds an empty case for FAKE blocks to avoid hitting the
assert. I would need to study the code in more detail to understand if
we should even be executing this code if we are in a FAKE block, but
this patch seems to solve the issue for me.
Signed-off-by: Ian Munsie <darkstarsword@gmail.com>
In both in python2 and python3 parse_qs expects str object. In
python2 it worked ok, because self.rfile was open in binary mode and
str in python2 is actually a string of bytes. However in python3 str is
actually string of unicode literals, not bytes and file was still open
in binary mode. Thus, deleting any file with non-ascii byte inside
filename failed in python3.
Also, cgi.parse_qs is deprecated and shouldn't be used.
The __fish_git_prompt_show_upstream helper function was inadvertently
looking at the misnamed variable __fish_git_prompt_show_upstream in some
cases, including when implementing the bash.showUpstream override.
Fixing the script to use __fish_git_prompt_showupstream triggered an
infinite loop because the --on-variable hook does not distinguish
between local and global variables.
Update the script to set a completely different local variable to
__fish_git_prompt_showupstream and to override this local variable for
bash.showUpstream.
Also update the code that looks at bash.showUpstream to also read
bash.showupstream, because the bash script appears to have a bug where
it looks for bash.showupstream despite documenting bash.showUpstream.
Git-svn remotes can have a prefix for their remotes. If I set a prefix
of 'svn/' then my remote trunk branch is called svn/trunk. Update the
script to use the svn-remote.*.fetch key to figure out how the 'trunk'
branch is mapped into the remotes namespace and apply this to the
current branch. This assumes branches are mapped into the same
namespace, which is likely. It also doesn't work for tags, but neither
did the old code.
- etc/config.fish and share/config.fish are now "universal" and no longer reference install paths or need to be touched by autotools. They've been removed from config.fish.in to config.fish.
- fish now attempts to determine __fish_datadir and __fish_sysconfdir relative to the path of the fish executable itself (typically by walking up one directory). This means that you can copy the directory hierarchy around and things will still work. The compiled-in paths are used as a backup.
- The fish Xcode project now can build fish natively, without needing autotools.
- Version bumped to 2.0
Fish now doesn't join the fish_prompt output. This breaks the default
fish_prompt. Make default fish_prompt single-line. Fixes#203.
Add -l flag to 'read' documentation. Remove ambiguous '-x' description.
Fixes#157.
Builtin 'set' now can set variable index ranges:
set test[1..3] a b c #works
set test[-1..-3] a b c #works if variable have enough elements
set test[2..-2] a b c #works
set test[1..3 -1..-2] a b c b b #works
Expand now can parse index ranges. But not handle for now.
TODO:
* Add variable substitution index ranges: echo $PATH[-1..1]
* Add command substitution index range: echo (seq 10)[-1..-4]
* Add process substitution indexes and ranges: echo %vim[-1]
Fish now doesn't join the fish_prompt output. This breaks the default
fish_prompt. Make default fish_prompt single-line. Fixes#203.
Add -l flag to 'read' documentation. Remove ambiguous '-x' description.
Fixes#157.
Remove the case statements, which were handled by the sed blocks anyway
Move around the '/' character in the regex, so only one regex is needed
Fix a bug where '/' is output as '//'
The following expression now works:
```sh
switch '\\'
case '\\'
echo 1
end
```
Due to ambiguity, the following expression also works:
```sh
switch '\a'
case '\\a'
echo 1
end
```
By the way, the following expression now doesn't work, which was not the
case before, because of wrong escaping:
```sh
switch 'nn'
case '\n'
echo 1
end
```
* case no properly handles -h and --help flags, i.e. treats it as
pattern
* fixed case escaping:
The following expressions now work correctly:
switch '*'
echo '*'
echo Match any string
end
switch '*'
echo '\*'
echo Match asterix
end
switch '\\'
echo '\\\\'
echo Match slash
end
The same for '?' sign
Autosuggestion will be automatically re-enabled next time a character is
inserted. An alternative implementation would require another command to
explicitly re-enable it.
Signed-off-by: Ian Munsie <darkstarsword@gmail.com>
This can be demonstrated with something like:
echo howdy hi<control-w>
echo howdy I<alt-b>
Previousely this would delete/move all the way to the start of 'howdy',
rather than just the word 'hi'/'I'.
It seems that the code to ignore the character under the cursor was
redundant, as all the cases I've tried with it removed seem to do the
right thing.
Signed-off-by: Ian Munsie <darkstarsword@gmail.com>
* Editor mode is no the default
* Use -i or --interactive or -e fish to edit function in interactive
mode
* tmpname is now created with random number added and check that file
do not already exist
* check $TMPDIR existence and put /tmp if it does not exist
* There is an undocumented feature to use functions, started with dash.
Introduce necessary changes to funced, functions, def_function()
in order to make it work properly.
* Delete editor guessing. Use $EDITOR variable or -e key
fish_pager_color_secondary to set background of every second completion
line. It simplifies finding the options corresponding to given
description. Default color is 151515.
With the switch bug fixed, __fish_git_prompt can be very slightly
simplified by not recording the exit status of every case in the
describe style switch individually.
The echo command to print the last path segment got a couplel of fixes,
but these fixes were only applied to the non-Darwin version. Copy these
fixes over to the Darwin version. Notably, this makes `/` stop
displaying as `//`.
When $PWD is "/private", the prompt was printing "rivate". Skip the
"/private" stripping if there's nothing after it.
Prevent "/private" from being stripped anywhere but the beginning of the
PWD.
Fixes#173
__fish_config_interactive.fish uses the presence of __fish_init_1_50_0
to decide whether it should perform a one-time initialization of
universal variables. Unfortunately, it sets the variable
__fish_init_1_23_0. Fix this to set __fish_init_1_50_0 instead.
__fish_git_prompt.fish is a complete port of the __git_ps1 function from
git-completion.bash, with the relevant configuration variables changed
and some extra configuration added (namely, control over individual
colors and the status indicator characters).
* Seems that writestr( L"\x1b];" ); doesn't work in tmux and
screen. As discussed in fish-shell/fish-shell#47 the 2 was
removed. This commit adds the zero (L"\x1b]0;").
* Tested in screen,tmux,iTerm and xterm.
If doxygen isn't installed, an empty file called user_doc will be created.
If doxygen is later installed, the documentation will not generate correctly.
- Was an opening tag, should have been a closing tag
- Confused Doxygen 1.8.1.1 on my machine (OS X 10.7), resulting in the fish man pages not being installed at all
Renamed autosuggest_handle_special to autosuggest_special_validate_from_history
Began work to factor autosuggest_special_validate_from_history together with autosuggest_suggest_special
This should fix the bug where output from commands and builtins gets incorrectly interleaved.
I think this is a very long-standing bug that predates my work on the 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/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/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/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 depends on a curses implementation, such as ncurses. The headers and libraries are required for building.
fish requires gettext for translation support.
Building the documentation requires Doxygen 1.8.7 or newer.
### Autotools Build
autoconf
./configure
make [gmake on BSD]
sudo make install
### Xcode Development Build
* Build the `base` target in Xcode
* Run the fish executable, for example, in `DerivedData/fish/Build/Products/Debug/base/bin/fish`
### Xcode Build and Install
xcodebuild install
sudo ditto /tmp/fish.dst /
## Help, it didn't build!
If fish reports that it could not find curses, try installing a curses development package and build again.
fish requires a curses implementation, such as ncurses, to run.
fish requires a number of utilities to operate, which should be present on any Unix, GNU/Linux or OS X system. These include (but are not limited to) hostname, grep, awk, sed, which, and getopt. fish also requires the bc program.
Translation support requires the gettext program.
Some optional features of fish, such as the manual page completion parser and the web configuration tool, require Python.
In order to generate completions from man pages compressed with either lzma or xz, you may need to install an extra Python package. Python versions prior to 2.6 are not supported. For Python versions 2.6 to 3.2 you need to install the module `backports.lzma`. How to install it depends on your system and how you installed Python. Most Linux distributions should include it as a package named `backports-lzma` (or similar). From version 3.3 onwards, Python already includes the required module.
## Packages for Linux
Instructions on how to find builds for several Linux distros are at <https://github.com/fish-shell/fish-shell/wiki/Nightly-builds>
## Switching to fish
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.
To switch your default shell back, you can run:
chsh -s /bin/bash
Substitute /bin/bash with /bin/tcsh or /bin/zsh as appropriate.
## 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).
Found a bug? Have an awesome idea? Please open an issue on this github page.
// Note that we record the last checked time after the call, on the assumption that in a slow filesystem, the lag comes before the kernel check, not after.
/* Mark that we're loading this. Hang onto the iterator for fast erasing later. Note that std::set has guarantees about not invalidating iterators, so this is safe to do across the callouts below. */
/* Note that we are NOT locked in this function! */
boolreloaded=0;
/* Try using a cached function. If we really want the function to be loaded, require that it be really loaded. If we're not reloading, allow stale functions. */
{
boolallow_stale_functions=!reload;
/* Take a lock */
scoped_locklocker(lock);
/* Get the function */
autoload_function_t*func=this->get_node(cmd);
/* Determine if we can use this cached function */
/* Remove any loaded command because we are going to reload it. Note that this will deadlock if command_removed calls back into us. */
if(func&&func->is_loaded)
{
command_removed(cmd);
func->is_placeholder=false;
}
/* Mark that we're reloading it */
reloaded=true;
}
/* Create the function if we haven't yet. This does not load it. Do not trigger eviction unless we are actually loading, because we don't want to evict off of the main thread. */
Autoload the specified file, if it exists in the specified path. Do
not load it multiple times unless its timestamp changes or
parse_util_unload is called.
Autoloading one file may unload another.
\param cmd the filename to search for. The suffix '.fish' is always added to this name
\param on_unload a callback function to run if a suitable file is found, which has not already been run. unload will also be called for old files which are unloaded.
\param reload wheter to recheck file timestamps on already loaded files
*/
intload(constwcstring&cmd,boolreload);
/** Check whether we have tried loading the given command. Does not do any I/O. */
boolhas_tried_loading(constwcstring&cmd);
/**
Tell the autoloader that the specified file, in the specified path,
is no longer loaded.
\param cmd the filename to search for. The suffix '.fish' is always added to this name
\param on_unload a callback function which will be called before (re)loading a file, may be used to unload the previous file.
\return non-zero if the file was removed, zero if the file had not yet been loaded
*/
intunload(constwcstring&cmd);
/**
Unloads all files.
*/
voidunload_all();
/** Check whether the given command could be loaded, but do not load it. */
echo >&2"Could not find input directory '${INPUTDIR}'"
exit1
fi
# Make sure doxygen is found
DOXYGENPATH=`command -v doxygen`
iftest -z "$DOXYGENPATH";then
for i in /usr/local/bin/doxygen /opt/bin/doxygen /Applications/Doxygen.app/Contents/Resources/doxygen ~/Applications/Doxygen.app/Contents/Resources/doxygen ;do
iftest -f "$i";then
DOXYGENPATH="$i"
break
fi
done
fi
iftest -z "$DOXYGENPATH";then
echo >&2"doxygen is not installed, so documentation will not be built."
exit0
fi
# Check we have the lexicon filter
iftest -z "$INPUT_FILTER";then
echo >&2"Lexicon filter is not available. Continuing without."
INPUTFILTER=''
fi
# Determine where our output should go
if ! mkdir -p "${OUTPUTDIR}";then
echo"Could not create output directory '${OUTPUTDIR}'"
fi
# Make a temporary directory
TMPLOC=`mktemp -d -t fish_doc_build_XXXXXX`||{echo >&2"Could not build documentation because mktemp failed";exit 1;}
# Copy stuff to the temp directory
for i in "$INPUTDIR"/*.txt;do
INPUTFILE=$TMPLOC/`basename $i .txt`.doxygen
echo"/** \page"`basename $i .txt` > $INPUTFILE
cat $i >>$INPUTFILE
echo"*/" >>$INPUTFILE
done
# Make some extra stuff to pass to doxygen
# Input is kept as . because we cd to the input directory beforehand
# This prevents doxygen from generating "documentation" for intermediate directories
This is the_ridiculous'fish s delightful fork of, fish friendly interactive shell. For more information, visit http://ridiculousfish.com/shell/ .
This installer will install fish, but will not modify your /etc/shells file or your default shell. I trust you know how to do that yourself if you care to!
\f0\fs30 \cf0 The fish shell is a smart and user friendly command line shell. For more information, visit {\field{\*\fldinst{HYPERLINK "http://fishshell.com"}}{\fldrslt http://fishshell.com}}.\
/* completion_apply_to_command_line will append a space unless COMPLETE_NO_SPACE is set. We don't want to set COMPLETE_NO_SPACE because that won't close quotes. What we want is to close the quote, but not append the space. So we just look for the space and clear it. */
/* The input data is meant to be something like you would have on the command line, e.g. includes backslashes. The output should be raw, i.e. unescaped. So we need to unescape the command line. See #1127 */
/* Escape sequence must be done. Complain if we didn't get anything */
if(esc_length==0)
{
this->fatal_error(_(L"Missing hexadecimal number in Unicode escape"));
}
break;
}
uni_value=uni_value*16+hex_to_bin(*p);
p++;
}
/* PCA GNU printf respects the limitations described in ISO N717, about which universal characters "shall not" be specified. I believe this limitation is for the benefit of compilers; I see no reason to impose it in builtin_printf.
If __STDC_ISO_10646__ is defined, then it means wchar_t can and does hold Unicode code points, so just use that. If not defined, use the %lc printf conversion; this probably won't do anything good if your wide character set is not Unicode, but such platforms are exceedingly rare.
*/
if(uni_value>0x10FFFF)
{
this->fatal_error(_(L"Unicode character out of range: \\%c%0*x"),esc_char,(esc_char==L'u'?4:8),uni_value);
/* Combining expression. Contains a list of AND or OR expressions. It takes more than two so that we don't have to worry about precedence in the parser. */
/* Evaluate our lists, remembering that AND has higher precedence than OR. We can visualize this as a sequence of OR expressions of AND expressions. */
assert(combiners.size()+1==subjects.size());
assert(!subjects.empty());
size_tidx=0,max=subjects.size();
boolor_result=false;
while(idx<max)
{
if(or_result)
{
/* Short circuit */
break;
}
/* Evaluate a stream of AND starting at given subject index. It may only have one element. */
/* IEEE 1003.1 says nothing about what it means for two strings to be "algebraically equal". For example, should we interpret 0x10 as 0, 10, or 16? Here we use only base 10 and use wcstoll, which allows for leading + and -, and leading whitespace. This matches bash. */
casetest_fileperm_u:// "-u", whether file is setuid
return!wstat(arg,&buf)&&(S_ISUID&buf.st_mode);
casetest_fileperm_w:// "-w", whether file write permission is allowed
return!waccess(arg,W_OK);
casetest_fileperm_x:// "-x", whether file execute/search is allowed
return!waccess(arg,X_OK);
casetest_string_n:// "-n", non-empty string
return!arg.empty();
casetest_string_z:// "-z", true if length of string is 0
returnarg.empty();
default:
errors.push_back(format_string(L"Unknown token type in %s",__func__));
returnfalse;
}
}
};
/*
* Evaluate a conditional expression given the arguments.
* If fromtest is set, the caller is the test or [ builtin;
* with the pointer giving the name of the command.
* for POSIX conformance this supports a more limited range
* of functionality.
*
* Return status is the final shell status, i.e. 0 for true,
* 1 for false and 2 for error.
*/
intbuiltin_test(parser_t&parser,wchar_t**argv)
{
usingnamespacetest_expressions;
/* The first argument should be the name of the command ('test') */
if(!argv[0])
returnBUILTIN_TEST_FAIL;
/* Whether we are invoked with bracket '[' or not */
constboolis_bracket=!wcscmp(argv[0],L"[");
size_targc=0;
while(argv[argc+1])
argc++;
/* If we're bracket, the last argument ought to be ]; we ignore it. Note that argc is the number of arguments after the command name; thus argv[argc] is the last argument. */
if(is_bracket)
{
if(!wcscmp(argv[argc],L"]"))
{
/* Ignore the closing bracketp */
argc--;
}
else
{
builtin_show_error(L"[: the last argument must be ']'\n");
/* Useful macro for asserting that a lock is locked. This doesn't check whether this thread locked it, which it would be nice if it did, but here it is anyways. */
/** Our crappier versions of debug which is guaranteed to not allocate any memory, or do anything other than call write(). This is useful after a call to fork() with threads. */
/* Compare two completions. No operating overlaoding to make this always explicit (there's potentially multiple ways to compare completions). */
/* "Naturally less than" means in a natural ordering, where digits are treated as numbers. For example, foo10 is naturally greater than foo2 (but alphabetically less than it) */
/** Find all completions of the command cmd, insert them into out.
*/
voidcomplete(constwcstring&cmd,
std::vector<completion_t>&comp,
completion_request_flags_tflags);
/**
Find all completions of the command cmd, insert them into out. The
caller must free the variables returned in out. The results are
returned in the array_list_t 'out', in the format of wide character
strings, with each element consisting of a suggested completion and
a description of what kind of object this completion represents,
separated by a separator of type COMPLETE_SEP.
Print a list of all current completions into the string.
Values returned by this function should be freed by the caller.
\param out The string to write completions to
*/
voidcomplete(constwchar_t*cmd,array_list_t*out);
/**
Print a list of all current completions into the string_buffer_t.
\param out The string_buffer_t to write completions to
*/
voidcomplete_print(string_buffer_t*out);
voidcomplete_print(wcstring&out);
/**
Tests if the specified option is defined for the specified command
*/
intcomplete_is_valid_option(constwchar_t*str,
constwchar_t*opt,
array_list_t*errors );
intcomplete_is_valid_option(constwcstring&str,
constwcstring&opt,
wcstring_list_t*inErrorsOrNull,
boolallow_autoload);
/**
Tests if the specified argument is valid for the specified option
and command
*/
intcomplete_is_valid_argument(constwchar_t*str,
constwchar_t*opt,
constwchar_t*arg);
boolcomplete_is_valid_argument(constwcstring&str,
constwcstring&opt,
constwcstring&arg);
/**
@@ -241,22 +247,32 @@ int complete_is_valid_argument( const wchar_t *str,
with internal dependencies.
\param cmd the command for which to load command-specific completions
\param reload should the commands completions be reloaded, even if they where previously loaded. (This is set to true on actual completions, so that changed completion are updated in running shells)
\param reload should the commands completions be reloaded, even if they where
previously loaded. (This is set to true on actual completions, so that
changed completion are updated in running shells)
*/
voidcomplete_load(constwchar_t*cmd,intreload);
voidcomplete_load(constwcstring&cmd,boolreload);
/**
Create a new completion entry
\param context The halloc context to use for allocating new memory
\param completions The array of completions to append to
/* Support for "wrap targets." A wrap target is a command that completes liek another command. The target chain is the sequence of wraps (A wraps B wraps C...). Any loops in the chain are silently ignored. */
The fish documentation has been updated to support Doxygen 1.8.7+, and while the main benefit of this change is extensive Markdown support, the addition of a fish lexicon and syntax filter, combined with semantic markup rules allows for automatic formatting enhancements across the HTML user_docs, the developer docs and the man pages.
Initially my motivation was to fix a problem with long options ([Issue #1557](https://github.com/fish-shell/fish-shell/issues/1557) on GitHub), but as I worked on fixing the issue I realised there was an opportunity to simplify, reinforce and clarify the current documentation, hopefully making further contribution easier and cleaner, while allowing the documentation examples to presented more clearly with less author effort.
While the documentation is pretty robust to variations in the documentation source, adherence to the following style guide will help keep the already excellent documention in good shape moving forward.
## Line breaks and wrapping
Contrary to the rest of the fish source code, the documentation greatly benefits from the use of long lines and soft wrapping. It allows paragraphs to be treated as complete blocks by Doxygen, means that the semantic filter can see complete lines when deciding on how to apply syntax highlighting, and means that man pages will consistently wrap to the width of the users console in advanced pagers, such as 'most'.
## Doxygen special commands and aliases
While Markdown syntax forms the basis of the documentation content, there are some exceptions that require the use of Doxygen special commands. On the whole, Doxygen commands should be avoided, especially inline word formatting such as \\c as this would allow Doxygen to make unhelpful assumptions, such as converting double dashes (\--) to n-dashes (–).
### Structure: \\page, \\section and \\subsection
Use of Doxygen sections markers are important, as these determine what will be eventually output as a web page, man page or included in the developer docs.
Currently the make process for the documentation is quite convoluted, but basically the HTML docs are produced from a single, compiled file, doc.h. This contains a number of \\page markers that produce the various pages used in the documentation. The format of a \\page mark is:
\page universally_unique_page_id Page title
The source files that contain the page markers are currently:
- __index.hdr.in__: Core documentation
- __commands.hdr.in__: Individual commands
- __tutorial.hdr__: Tutorial
- __design.hdr__: Design document
- __faq.hdr__: Frequently Asked Questions
- __license.hdr__: Fish and 3rd party licences
Unless there is a _VERY_ good reason and developer consensus, new pages should never be added.
The rest of the documentation is structured using \\section and \\subsection markers. Most of the source files (listed above) contain their full content, the exception being commands, which are separated out into source text files in the doc_src directory. These files are concatenated into one file, so each one starts with a \\section declaration. The synopsis, description and examples (if present) are declared as \\subsections. The format of these marks is practically identical to the page mark.
\section universally_unique_section_id Section title
\subsection universally_unique_subsection_id Subsection title
Each page, section and subsection id _must_ be unique across the whole of the documentation, otherwise Doxygen will issue a warning.
### Semantic markup: the \\fish .. \\endfish block
While Doxygen has support for \\code..\\endcode blocks with enhanced markup and syntax colouring, it only understands the core Doxygen languages: C, C++, Objective C, Java, PHP, Python, Tcl and Fortran. To enhance Fish's syntax presentation, use the special \\fish..\\endfish blocks instead.
Text placed in this block will be parsed by Doxygen using the included lexicon filter (see lexicon_filter.in) as a Doxygen input filter. The filter is built during make so that it can pick up information on builtins, functions and shell commands mentioned in completions and apply markup to keywords found inside the \\fish block.
Basically, preformatted plain text inside the \\fish block is fed through the filter and is returned marked up so that Doxygen aliases can convert it back to a presentable form, according to the output document type.
For instance:
`echo hello world`
is transformed into:
`@cmnd{echo} @args{hello} @args{world}`
which is then transformed by Doxygen into an HTML version (`make user_doc`):
And a simple HTML version for the developer docs (`make doc`) and the LATEX/PDF manual (`make doc/refman.pdf`):
`echo hello world`
### Fonts
In older browsers, it was easy to set the fonts used for the three basic type styles (serif, sans-serif and monospace). Modern browsers have removed these options in their respective quests for simplification, assuming the content author will provide suitable styles for the content in the site's CSS, or the end user will provide overriding styles manually. Doxygen's default styling is very simple and most users will just accept this default.
I've tried to use a sensible set of fonts in the documentation's CSS based on 'good' terminal fonts and as a result the firt preference font used throughout the documentation is '[DejaVu](http://dejavu-fonts.org)'. The rationale behaind this is that while DejaVu is getting a little long in the tooth, it still provides the most complete support across serif, sans-serif and monospace styles (giving a well balanced feel and consistent [x-height](http://en.wikipedia.org/wiki/X-height)), has the widest support for extended Unicode characters and has a free, permissive licenses (though it's still incompatible with GPLv2, though arguably less so than the SIL Open Font license, though this is a moot point when using it solely in the docs).
#### Fonts inside \\fish blocks and \`backticks\`
As the point of these contructs is to make fish's syntax clearer to the user, it makes sense to mimic what the user will see in the console, therefore any content is formatted using the monospaced style, specifically monospaced fonts are chosen in the following order:
1.__DejaVu Sans Mono__: Explained above. [[↓](http://dejavu-fonts.org)]
2.__Source Code Pro__: Monospaced code font, part of Adobe's free Edge Web Fonts. [[↓](https://edgewebfonts.adobe.com)]
5.__Consolas__: Modern Microsoft supplied console font.
6.__Monaco__: Apple supplied console font since 1984!
7.__Lucida Console__: Generic mono terminal font, standard in many OS's and distros.
8.__monospace__: Catchall style. Chooses default monospaced font, often Courier.
9.__fixed__: As above, more often used on mobile devices.
#### General Fonts
1.__DejaVu Sans__: As above.[[↓](http://dejavu-fonts.org)]
2.__Roboto__: Elegant Google free font and is Doxygen's default [[↓](http://www.google.com/fonts/specimen/Roboto)]
3.__Lucida Grande__: Default Apple OS X content font.
4.__Calibri__: Default Microsoft Office font (since 2007).
5.__Verdana__: Good general font found in a lot of OSs.
6.__Helvetica Neue__: Better spaced and balanced Helvetica/Arial variant.
7.__Helvetica__: Standard humanist typeface found almost everywhere.
8.__Arial__: Microsoft's Helvetica.
9.__sans-serif__: Catchall style. Chooses default sans-serif typeface, often Helvetica.
The ordering of the fonts is important as it's designed to allow the documentation to settle into a number of different identities according to the fonts available. If you have the complete DejaVu family installed, then the docs are presented using that, and if your Console is set up to use the same fonts, presentation will be completely consistent.
On OS X, with nothing extra installed, the docs will default to Menlo and Lucida Grande giving a Mac feel. Under Windows, it will default to using Consolas and Calibri on recent versions, giving a modern Windows style.
#### Other sources:
- [Font Squirrel](http://www.fontsquirrel.com): Good source of open source font packages.
### Choosing a CLI style: using a \\fish{style} block
By default, when output as HTML, a \\fish block uses syntax colouring suited to the style of the documentation rather than trying to mimic the terminal. The block has a light, bordered background and a colour scheme that 'suggests' what the user would see in a console.
Additional stying can be applied adding a style declaration:
\fish{additional_style [another_style...]}
...
\endfish
This will translate to classes applied to the `<div>` tag, like so:
<div class="fish additional_style another_style">
...
</div>
The various classes are defined in `doc_src/user_doc.css` and new style can be simply added
The documentation currently defines a couple of additional styles:
- __cli-dark__: Used in the _tutorial_ and _FAQ_ to simulate a dark background terminal, with fish's default colours (slightly tweaked for legibility in the browser).
- __synopsis__: A simple colour theme helpful for displaying the logical 'summary' of a command's syntax, options and structure.
## Markdown
Apart from the exceptions discussed above, the rest of the documentation now supports the use of Markdown. As such the use of Doxygen special commands for HTML tags is unnecessary.
There are a few exceptions and extensions to the Markdown [standard](http://daringfireball.net/projects/markdown/) that are documented in the Doxygen [documentation](http://www.stack.nl/~dimitri/doxygen/manual/markdown.html).
### \`Backticks\`
As is standard in Markdown and 'Github Flavoured Markdown' (GFM), backticks can be used to denote inline technical terms in the documentation, `like so`. In the documentation this will set the font to the monospaced 'console' typeface and will cause the enclosed term to stand out.
However, fenced code blocks using 4 spaces or 3 backticks (\`\`\`) should be avoided as Doxygen will interpret these as \\code blocks and try to apply standard syntax colouring, which doesn't work so well for fish examples. Use `\fish..\endfish` blocks instead.
### Lists
Standard Markdown list rules apply, but as Doxygen will collapse white space on output, combined with the use of long lines, it's a good idea to include an extra new line between long list items to assist future editing.
## Special cases
The following can be used in \\fish blocks to render some fish scenarios. These are mostly used in the tutorial when an interactive situation needs to be displayed.
### Custom formatting tags
-`<s>`: auto\<s\>suggestion\</s\>.
-`<m>`: \<m\>Matched\</m\> items, such as tab completions.
-`<sm>`: Matched items \<sm\>searched\<sm\> for, like grep results.
-`<error>`: \<error\>This would be shown as an error.\</error\>
-`<asis>`: \<asis\>This test will not be parsed for fish markup.\</asis\>
-`<outp>`: \<outp\>This would be rendered as command/script output.\</outp\>
### Prompts and cursors
-`>_`: Display a basic prompt.
-`~>_`: Display a prompt with a the home directory as the current working directory.
-`___` (3 underscores): Display a cursor.
### Keyboard shortcuts: @key{} and @cursor_key{}
Graphical keyboard shortcuts can be defined using the following special commands. These allow for the different text requirements across the html and man pages. The HTML uses CSS to create a keyboard style, whereas the man page would display the key as text.
-`@key{lable}`
Displays a key with a purely textual lable, such as: 'Tab', 'Page Up', 'Page Down', 'Home', 'End', 'F1', 'F19' and so on.
-`@key{modifier,lable}`
Displays a keystroke requiring the use of a 'modifier' key, such as 'Control-A', 'Shift-X', 'Alt-Tab' etc.
-`@key{modifier,entity,lable}`
Displays a keystroke using a graphical entity, such as an arrow symbol for cursor key based shortcuts.
-`@cursor_key{entity,lable}`
A special case for cursor keys, when no modifier is needed. i.e. `@cursor_key{↑,up}` for the up arrow key.
Some useful Unicode/HTML5 entities:
- Up arrow: `↑`
- Down arrow: `↓`
- Left arrow: `←`
- Right arrow `→`
- Shift: `⇧`
- Tab: `⇥`
- Mac option: `⌥`
- Mac command: `⌘`
## Notes
### Doxygen
Tested on:
- Ubuntu 14.04 with Doxygen 1.8.8, built from [GitHub source](https://github.com/doxygen/doxygen.git).
- CentOS 6.5 with Doxygen 1.8.8, built from [GitHub source](https://github.com/doxygen/doxygen.git).
- Mac OS X 10.9 with Homebrew install Doxygen 1.8.7 and 1.8.8.
Graphviz was also installed in all the above testing.
Doxygen 1.8.6 and lower do not have the \\htmlonly[block] directive which fixes a multitude of problems in the rendering of the docs. In Doxygen 1.8.7 the list of understood HTML entities was greatly increased. I tested earlier versions and many little issues returned.
As fish ships with pre-built documentation, I don't see this as an issue.
### Updated Configure/Makefile
- Tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9.
- Makefile has GNU/BSD sed/grep detection.
### HTML output
- The output HTML is HTML5 compliant, but should quickly and elegantly degrade on older browsers without losing basic structure.
- The CSS avoids the use or browser specific extenstions (i.e. -webkit, -moz etc), using the W3C HTML5 standard instead.
- It's been tested in Chrome 37.0 and Firefox 32.0 on Mac OS X 10.9 (+Safari 7), Windows 8.1 (+Internet Explorer 11) and Ubuntu Desktop 14.04.
- My assumption is basically that if someone cares enough to want to install fish, they'll be keeping a browser current.
### Man page output
- Tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9.
- Output is substantially cleaner.
- Tested in cat, less, more and most pagers using the following fish script:
```
function manTest --description 'Test manpage' --argument page
set -l pager
for i in $argv
switch $i
case "-l"
set pager -P '/usr/bin/less -is'
case "-m"
set pager -P '/usr/bin/more -s'
case "-c"
set pager -P '/bin/cat'
end
end
man $pager ~/Projects/OpenSource/fish-shell/share/man/man1/$page.1
end
# Assumes 'most' is the default system pager.
# NOT PORTABLE! Paths would be need to be updated on other systems.
```
### Developer docs and LATEX/PDF output
- HTML developer docs tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9.
- LATEX/PDF reference manual tested on Mac OS X 10.9 using MacTEX. PDF production returns an error (due to Doxygen's use of an outdated 'float' package), but manual PDF output is ok.
### Future changes
1. The documentation creation process would be better if it could be modularised further and moved out of the makefile into a number of supporting scripts. This would allow both the automake and Xcode build processes to use the documentation scripts directly.
2. Remove the Doxygen dependency entirely for the user documentation. This would be very acheivable now that the bulk of the documentation is in Markdown.
3. It would be useful to gauge what parts of the documentation are actually used by users. Judging by the amount of 'missing comment' errors during the developer docs build phase, this aspect of the docs has been rather neglected. If it is not longer used or useful, then this could change the future direction of the documentation and significantly streamline the process.
#### Author: Mark Griffiths [@GitHub](https://github.com/MarkGriffiths)
`abbr` manipulates the list of abbreviations that fish will expand.
Abbreviations are user-defined character sequences or words that are replaced with longer phrases after they are entered. For example, a frequently-run command such as `git checkout` can be abbreviated to `gco`. After entering `gco` and pressing @key{Space} or @key{Enter}, the full text `git checkout` will appear in the command line.
Abbreviations are stored, by default, in a universal variable.
The following parameters are available:
- `-a WORD PHRASE` or `--add WORD PHRASE` Adds a new abbreviation, where WORD will be expanded to PHRASE.
- `-s` or `--show` Show all abbreviated words and their expanded phrases in a manner suitable for export and import.
- `-l` or `--list` Lists all abbreviated words.
- `-r WORD` or `--remove WORD` Remove the abbreviation WORD.
\subsection abbr-example Examples
\fish
abbr -a gco git checkout
\endfish
Add a new abbreviation where `gco` will be replaced with `git checkout`.
\fish
abbr -r gco
\endfish
Remove the `gco` abbreviation.
\fish
ssh another_host abbr -s | source
\endfish
Import the abbreviations defined on another_host over SSH.
Alias is a shellscript wrapper around 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>.
`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>.
Alias does not keep track of which functions have been defined using
alias, nor does it allow erasing of aliases.
`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 function to define
- DEFINITION is the body of the function. The string " $argv" will be appended to the body.
- `NAME` is the name of the alias
- `DEFINITION` is the actual command to execute. The string `$argv` will be appended.
You cannot create an alias to a function with the same name.
\subsection alias-example Example
The following code will create `rmi`, which runs `rm` with additional arguments on every invocation.
\fish
alias rmi "rm -i"
# This is equivalent to entering the following function:
\section and and - conditionally execute a command
\subsection and-synopsis Synopsis
<tt>COMMAND1; and COMMAND2</tt>
\fish{synopsis}
COMMAND1; and COMMAND2
\endfish
\subsection and-description Description
The \c and builtin 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.
The and command 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, the program is installed. If either step fails,
<tt>make clean</tt> is run, which removes the files created by the
build process
The following code runs the `make` command to build a program. If the build succeeds, `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.
The \c begin builtin is used to create a new block of code. The block
is unconditionally executed. <code>begin; ...; end</tt> is equivalent
to <tt>if true; ...; end</tt>. The begin command is used to group any
number of commands into a block. The reason for doing so is usually
either to introduce a new variable scope, to redirect 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 create a new block of code.
The block is unconditionally executed. `begin; ...; end` is equivalent to `if true; ...; end`.
`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.
The \c begin command 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.
Sends the specified jobs to the background. 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 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 \%0</tt> will put the job with job id 0 in the background.
`bg %1` will put the job with job ID 1 in the background.
The <tt>bind</tt> builtin causes fish to add a key binding from the specified sequence.
`bind` adds a binding for the specified key sequence to the specified command.
SEQUENCE is the character sequence to bind to. Usually, one would use
fish escape sequences to express them. 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>. Control character can be written in much the same way
using the \c \\c escape, for example Control-x can be written as
<tt>\\cx</tt>. Note that Alt-based key bindings are case sensitive and
Control base key bindings are not. This is not a design choice in
fish, it is simply how terminals work.
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`.
If SEQUENCE is the empty string, i.e. an empty set of quotes, this is
interpreted as the default keybinding. 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 keybining. 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 e.g. 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 man 5 terminfo 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.
- <tt>-a</tt> or <tt>--all</tt> If --key-names is specified, show all key names, not only the ones that actually are defined for the current terminal. If erase mode is specified, this switch will cause all current bindings to be erased.
- <tt>-e</tt> or <tt>--erase</tt> Erase mode. All non-switch arguments are interpreted as character sequences and any commands associated with those sequences are erased.
- <tt>-h</tt> or <tt>--help</tt> Display help and exit
- <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
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.
\subsection bind-example Example
When multiple `COMMAND`s are provided, they are all run in the specified order when the key is pressed.
<tt>bind \\cd 'exit'</tt> causes fish to exit on Control-d
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.
<tt>bind -k ppage history-search-backward</tt> Causes fish to perform a history search when the page up key is pressed
Key bindings are not saved between sessions by default. To save custom keybindings, edit the `fish_user_key_bindings` function and insert the appropriate `bind` statements.
Key bindings may use "modes", which mimics Vi's modal input behavior. The default mode is "default", and every bind applies to a single mode. The mode can be viewed/changed with the `$fish_bind_mode` variable.
The following parameters are available:
- `-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:
- `backward-char`, moves one character to the left
- `backward-delete-char`, deletes one character of input to the left of the cursor
- `backward-kill-line`, move everything from the beginning of the line to the cursor to the killring
- `backward-kill-word`, move the word to the left of the cursor to the killring
- `backward-word`, move one word to the left
- `beginning-of-history`, move to the beginning of the history
- `beginning-of-line`, move to the beginning of the line
- `capitalize-word`, make the current word begin with a capital letter
- `complete`, guess the remainder of the current token
- `delete-char`, delete one character to the right of the cursor
- `delete-line`, delete the entire line
- `downcase-word`, make the current word lowercase
- `dump-functions`, print a list of all key-bindings
- `end-of-history`, move to the end of the history
- `end-of-line`, move to the end of the line
- `explain`, print a description of possible problems with the current command
- `forward-char`, move one character to the right
- `forward-word`, move one word to the right
- `history-search-backward`, search the history for the previous match
- `history-search-forward`, search the history for the next match
- `kill-line`, move everything from the cursor to the end of the line to the killring
- `kill-whole-line`, move the line to the killring
- `kill-word`, move the next word to the killring
- `upcase-word`, make the current word uppercase
- `yank`, insert the latest entry of the killring into the buffer
- `yank-pop`, rotate to the previous entry of the killring
\subsection bind-example Examples
\fish
bind \cd 'exit'
\endfish
Causes `fish` to exit when @key{Control,D} is pressed.
\fish
bind -k ppage history-search-backward
\endfish
Performs a history search when the @key{Page Up} key is pressed.
\fish
set -g fish_key_bindings fish_vi_key_bindings
bind -M insert \cc kill-whole-line force-repaint
\endfish
Turns on Vi key bindings and rebinds @key{Control,C} to clear the input line.
\section block block - temporarily block delivery of events
\subsection block-synopsis Synopsis
<tt>block [OPTIONS...]</tt>
\fish{synopsis}
block [OPTIONS...]
\endfish
\subsection block-description Description
- <tt>-l</tt> or <tt>--local</tt> Release the block at the end of the currently innermost block scope
- <tt>-g</tt> or <tt>--global</tt> Never automatically release the lock
- <tt>-e</tt> or <tt>--erase</tt> Release global block
`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, `block` can be useful while performing work that should not be interrupted by the shell.
The block can be removed. Any events which triggered while the block was in place will then be delivered.
Event blocks should not be confused with code blocks, which are created with `begin`, `if`, `while` or `for`
The following parameters are available:
- `-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>
block -g
\#Do something that should not be interrupted
block -e
</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
The \c break builtin is used to halt 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`.
\subsection break-example Example
The following code searches all .c files for smurfs, and halts at the first occurrence.
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
The \c switch statement is used to perform one of several blocks of
commands depending on whether a specified value equals one of several
wildcarded values. The \c case statement is used together with the \c
switch statement in order to determine which block should be
performed.
`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 parameter. 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. Though the
syntax may look a bit like C switch statements, it behaves more like
the case statements of traditional shells.
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.
Also note that command substitutions in a case statement will be
evaluated even if it's body is not taken. This may seem
counterintuitive at first, but it is unavoidable, since it would be
impossible to know if a case command will evaluate to true before all
forms of parameter expansion have been performed for the case command.
\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
@@ -42,11 +31,12 @@ switch $animal
echo bird
case shark trout stingray
echo fish
# Note that the next case has a wildcard which is quoted
case '*'
echo I have no idea what a $animal is
end
</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
\subsection cd-description Description Changes the current
directory. If <tt>DIRECTORY</tt> is supplied it will become the new
directory. If \c DIRECTORY is a relative path, the paths found in the
CDPATH environment variable array will be tried as prefixes for the
specified path. If CDPATH is not set, it is assumed to be '.'. If \c
DIRECTORY is not specified, \$HOME will be the new directory.
\subsection cd-description Description
`cd` changes the current working directory.
If `DIRECTORY` is supplied, it will become the new directory. If no parameter is given, the contents of the `HOME` environment variable will be used.
If `DIRECTORY` is a relative path, the paths found in the `CDPATH` environment variable array will be tried as prefixes for the specified path.
Note that the shell will attempt to change directory without requiring `cd` if the name of a directory is provided (starting with `.`, `/` or `~`, or ending with `/`).
\subsection cd-example Examples
\fish
cd
# changes the working directory to your home directory.
cd /usr/src/fish-shell
# changes the working directory to /usr/src/fish-shell
prefixing a command with the word 'command' forces fish to ignore any functions or builtins with the same name.
\subsection command-example Example
`command` forces the shell to execute the program `COMMANDNAME` and ignore any functions or builtins with the same name.
The following options are available:
<tt>command ls</tt>
- `-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`.
causes fish to execute the ls program, even if there exists a 'ls' function.
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 commandline buffer
\section commandline commandline - set or get the current commandline buffer
\subsection commandline-synopsis Synopsis
<tt>commandline [OPTIONS] [CMD]</tt>
\fish{synopsis}
commandline [OPTIONS] [CMD]
\endfish
\subsection commandline-description Description
`commandline` can be used to set or get the current contents of the command line buffer.
- \c CMD is the new value of the commandline. If unspecified, the
current value of the commandline is written to standard output. All
output from the commandline builtin is escaped, i.e. quotes are
removed, backslash escapes are expanded, etc..
With no parameters, `commandline` returns the current value of the commandline.
The following switches change what the commandline builtin does
With `CMD` specified, the commandline buffer is erased and replaced with the contents of `CMD`.
- \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 can not 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.
The following options are available:
- `-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 switches change the way \c commandline updates the
commandline 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 switches 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 switch changes 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 commandline is called during a call to complete a given string
using <code>complete -C STRING</code>, commandline will consider the
specified string to be the current contents of the commandline.
\subsection commandline-example Example
<tt>commandline -j $history[3]</tt>
replaces the job under the cursor with the third item from the
commandline history.
`commandline -j $history[3]` replaces the job under the cursor with the third item from the command line history.
/** \page commands Commands, functions and builtins bundled with fish
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_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
For an introduction to how to specify completions, see the section <a
href='index.html#completion-own'>Writing your own completions</a> of
For an introduction to specifying completions, see <a
href='index.html#completion-own'>Writing your own completions</a> in
the fish manual.
- <tt>COMMAND</tt> is the name of the command for which to add a completion
- <tt>SHORT_OPTION</tt> is a one character option for the command
- <tt>LONG_OPTION</tt> is a multi character option for the command
- <tt>OPTION_ARGUMENTS</tt> is parameter containing a space-separated list of possible option-arguments, which may contain subshells
- <tt>DESCRIPTION</tt> is a description of what the option and/or option arguments do
- <tt>-C STRING</tt> or <tt>--do-complete=STRING</tt> makes complete try to find all possible completions for the specified string
- <tt>-e</tt> or <tt>--erase</tt> implies that the specified completion should be deleted
- <tt>-f</tt> or <tt>--no-files</tt> specifies that the option specified by this completion may not be followed by a filename
- <tt>-n</tt> or <tt>--condition</tt> specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases.
- <tt>-o</tt> or <tt>--old-option</tt> implies that the command uses old long style options with only one dash
- <tt>-p</tt> or <tt>--path</tt> implies that the string COMMAND is the full path of the command
- <tt>-r</tt> or <tt>--require-parameter</tt> specifies that the option specified by this completion always must have an option argument, i.e. may not be followed by another option
- <tt>-u</tt> or <tt>--unauthoritative</tt> implies that there may be more options than the ones specified, and that fish should not assume that options not listed are spelling errors
- <tt>-A</tt> or <tt>--authoritative</tt> implies that there may be no more options than the ones specified, and that fish should assume that options not listed are spelling errors
- <tt>-x</tt> or <tt>--exclusive</tt> implies both <tt>-r</tt> and <tt>-f</tt>
- `COMMAND` is the name of the command for which to add a completion.
Command specific tab-completions in \c fish are based on the notion
of options and arguments. An option is a parameter which begins with a
hyphen, such as '-h', '-help' or '--help'. Arguments are parameters
that do not begin with a hyphen. Fish recognizes three styles of
options, the same styles as the GNU version of the getopt
library. These styles are:
- `SHORT_OPTION` is a one character option for the command.
- Short options, like '-a'. Short options are a single character long, are preceded by a single hyphen and may be grouped together (like '-la', which is equivalent to '-l -a'). Option arguments may be specified in the following parameter ('-w 32') or by appending the option with the value ('-w32').
- Old style long options, like '-Wall'. Old style long options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified in the following parameter ('-ao null').
- GNU style long options, like '--colors'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('--quoting-style shell') or by appending the option with a '=' and the value ('--quoting-style=shell'). GNU style long options may be abbreviated so long as the abbreviation is unique ('--h' is equivalent to '--help' if help is the only long option beginning with an 'h').
- `LONG_OPTION` is a multi character option for the command.
The options for specifying command name, command path, or command
switches may all be used multiple times to specify multiple commands
which have the same completion or multiple switches accepted by a
command.
- `OPTION_ARGUMENTS` is parameter containing a space-separated list of possible option-arguments, which may contain subshells.
- `DESCRIPTION` is a description of what the option and/or option arguments do.
- `-C STRING` or `--do-complete=STRING` makes complete try to find all possible completions for the specified string.
- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the specified command to inherit completions from the wrapped command.
- `-e` or `--erase` implies that the specified completion should be deleted.
- `-f` or `--no-files` specifies that the option specified by this completion may not be followed by a filename.
- `-n` or `--condition` specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases.
- `-o` or `--old-option` implies that the command uses old long style options with only one dash.
- `-p` or `--path` implies that the string `COMMAND` is the full path of the command.
- `-r` or `--require-parameter` specifies that the option specified by this completion always must have an option argument, i.e. may not be followed by another option.
- `-u` or `--unauthoritative` implies that there may be more options than the ones specified, and that fish should not assume that options not listed are spelling errors.
- `-A` or `--authoritative` implies that there may be no more options than the ones specified, and that fish should assume that options not listed are spelling errors.
- `-x` or `--exclusive` implies both `-r` and `-f`.
Command specific tab-completions in `fish` are based on the notion of options and arguments. An option is a parameter which begins with a hyphen, such as '`-h`', '`-help`' or '`--help`'. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU version of the getopt library. These styles are:
- Short options, like '`-a`'. Short options are a single character long, are preceded by a single hyphen and may be grouped together (like '`-la`', which is equivalent to '`-l -a`'). Option arguments may be specified in the following parameter ('`-w 32`') or by appending the option with the value ('`-w32`').
- Old style long options, like '`-Wall`'. Old style long options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified in the following parameter ('`-ao null`').
- GNU style long options, like '`--colors`'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('`--quoting-style`') or by appending the option with a '`=`' and the value ('`--quoting-style=shell`'). GNU style long options may be abbreviated so long as the abbreviation is unique ('`--h`') is equivalent to '`--help`' if help is the only long option beginning with an 'h').
The options for specifying command name, command path, or command switches may all be used multiple times to specify multiple commands which have the same completion or multiple switches accepted by a command.
The `-w` or `--wraps` options causes the specified command to inherit completions from another command. The inheriting command is said to "wrap" the inherited command. The wrapping command may have its own completions in addition to inherited ones. A command may wrap multiple commands, and wrapping is transitive: if A wraps B, and B wraps C, then A automatically inherits all of C's completions. Wrapping can be removed using the `-e` or `--erase` options.
When erasing completions, it is possible to either erase all completions for a specific command by specifying `complete -e -c COMMAND`, or by specifying a specific completion option to delete by specifying either a long, short or old style option.
When erasing completions, it is possible to either erase all
completions for a specific command by specifying <tt>complete -e -c
COMMAND</tt>, or by specifying a specific completion option to delete
by specifying either a long, short or old style option.
\subsection complete-example Example
The short style option <tt>-o</tt> for the \c gcc command requires
that a file follows it. This can be done using writing <tt>complete
-c gcc -s o -r</tt>.
The short style option `-o` for the `gcc` command requires that a file follows it. This can be done using writing:
The short style option <tt>-d</tt> for the \c grep command requires
that one of the strings 'read', 'skip' or 'recurse' is used. This can
be specified writing <tt>complete -c grep -s d -x -a "read skip
recurse"</tt>.
\fish
complete -c gcc -s o -r
\endfish
The \c su command takes any username as an argument. Usernames are
given as the first colon-separated field in the file /etc/passwd. This
can be specified as: <tt>complete -x -c su -d "Username" -a "(cat
/etc/passwd|cut -d : -f 1)" </tt>.
The short style option `-d` for the `grep` command requires that one of the strings '`read`', '`skip`' or '`recurse`' is used. This can be specified writing:
The \c rpm command has several different modes. If the \c -e or \c
--erase flag has been specified, \c rpm should delete one or more
packages, in which case several switches related to deleting packages
are valid, like the \c nodeps switch.
\fish
complete -c grep -s d -x -a "read skip recurse"
\endfish
The `su` command takes any username as an argument. Usernames are given as the first colon-separated field in the file /etc/passwd. This can be specified as:
\fish
complete -x -c su -d "Username" -a "(cat /etc/passwd | cut -d : -f 1)"
\endfish
The `rpm` command has several different modes. If the `-e` or `--erase` flag has been specified, `rpm` should delete one or more packages, in which case several switches related to deleting packages are valid, like the `nodeps` switch.
\section contains contains - test if a word is present in a list
\subsection contains-synopsis Synopsis
<code>contains [OPTIONS] KEY [VALUES...]</code>
\fish{synopsis}
contains [OPTIONS] KEY [VALUES...]
\endfish
\subsection contains-description Description
- \c -h or \c --help display this message
`contains` tests whether the set `VALUES` contains the string `KEY`. If so, `contains` exits with status 0; if not, it exits with status 1.
Test if the set VALUES contains the string KEY. Return status is 0 if
yes, 1 otherwise
The following options are available:
- `-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 ~/bin and /usr/local/bin are in the path and if they are not, they are added.
\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
The \c continue builtin is used to skip the current lap of the innermost 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.
`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 without smurfs.
<pre>
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
The <tt>count</tt> builtin 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, but this is not the only
potential usage for the count command.
`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.
The count command does not accept any options, not even '-h'. This way
the user does not have to worry about an array containing elements
such as dashes. \c fish performs a special check when invoking the
count command, and if the user uses a help option, this help page is
displayed, but if a help option is contained inside of a variable or
is the result of expansion, it will simply be counted like any other
argument.
`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.
Count exits with a non-zero exit status if no arguments where passed
to it, with zero otherwise.
\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 achive 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 achived 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 \$''.
- 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 sep The law of minimalism
\section design-response The law of responsiveness
The shell should only contain features that cannot be implemented in
a reasonable way outside of the shell. A large performance decrease,
as well as some program complexity increase is acceptable in order to
improve separation.
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:
A modular project is easier to maintain since smaller programs are far
easier to understand than larger ones. A modular project is also more
future proof since the modules can be individually
replaced. Modularity also decreases the severity of bugs, since there
is good hope that a bug, even a serious one, in one module, does not
take the whole system down.
Bad performance increases user-facing complexity, because it trains users to recognize and route around slow use cases. It is also incredibly frustrating.
Examples:
- Builtin commands should only be created when it cannot be
avoided. \c echo, \c kill, \c printf and \c time are among the commands
that fish does not implement internally since they can be provided as
external commands. Several other commands that are commonly implemented
as builtins and can not be implemented as external commands,
including \c type, \c vared, \c pushd and \c popd are implemented as shellscript
functions in fish.
- Mathematical calculations, regex matching, generating lists of numbers
and many other funtions can easily be done in external programs. They
should not be supported internally by the shell.
- Features like syntax highlighting and autosuggestions must perform all of their disk I/O asynchronously.
The law of minimalism does not imply that a large feature set is
bad. So long as a feature is not part of the shell itself, but a
separate command or at least a shellscript function, bloat is fine.
- 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 of 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, shellscript functions and builtin commands should be made as small as possible. Builtins and shellscript functions should have exactly the same types of argument expansion as other commands, should be possible to use in any position in a pipeline, and should support any io redirection.
- The differences between built-in commands and shellscript functions should be made as small as possible. Built-ins and shellscript functions should have exactly the same types of argument expansion as other commands, should be possible to use in any position in a pipeline, and should support any I/O redirection.
- Instead of forking when performing command substitution to provide a fake variable scope, all fish commands are performed from the same process, and fish instead supports true scoping.
- All blocks end with the \c end builtin.
- All blocks end with the `end` built-in.
\section disc The law of discoverability
A program should be designed to make its features as
easy as possible to discover for the user.
A program should be designed to make its features as easy as possible to discover for the user.
Rationale:
A program whose features are discoverable turns a new user into an expert in a shorter span of time, since the user will become an expert on the program simply by using it.
A program whose features are discoverable turns a new user into an
expert in a shorter span of time, since the user will become an expert
on the program simply by using it.
The main benefit of a graphical program over a command line-based
program is discoverability. In a graphical program, one can discover
all the common features by simply looking at the user interface and
guessing what the different buttons, menus and other widgets do. The
traditional way to discover features in commandline programs is
through manual pages. This requires both that the user starts to use a
different program, and the she/he then remembers the new information
until the next time she/he uses the same program.
The main benefit of a graphical program over a command-line-based program is discoverability. In a graphical program, one can discover all the common features by simply looking at the user interface and guessing what the different buttons, menus and other widgets do. The traditional way to discover features in command-line programs is through manual pages. This requires both that the user starts to use a different program, and then she/he remembers the new information until the next time she/he uses the same program.
Examples:
- Everything should be tab-completable, and every tab completion should have a description.
- Every syntax error and error in a builtin command should contain an error message describing what went wrong and a relevant help page. Whenever possible, errors should be flagged red by the syntax highlighter.
- Every syntax error and error in a built-in command should contain an error message describing what went wrong and a relevant help page. Whenever possible, errors should be flagged red by the syntax highlighter.
- The help manual should be easy to read, easily available from the shell, complete and contain many examples
- The language should be uniform, so that once the user understands the command/argument syntax, he will know the whole language, and be able to use tab-completion to discover new featues.
- The language should be uniform, so that once the user understands the command/argument syntax, she/he will know the whole language, and be able to use tab-completion to discover new features.
<tt>dirh</tt> prints the current directory history. The current position in the
history is highlighted using <tt>$fish_color_history_current</tt>.
`dirh` prints the current directory history. The current position in the history is highlighted using the color defined in the `fish_color_history_current` environment variable.
if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
\endfish
\subsection else-description Description
<tt>if</tt> will execute the command CONDITION. If the condition's exit
status is 0, the commands COMMANDS_TRUE will execute. If it is not 0 and
<tt>else</tt> is given, COMMANDS_FALSE will be executed. Hint: use
<a href="#begin"><tt>begin; ...; end</tt></a> for complex conditions.
`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 command <tt>if test -f foo.txt; echo foo.txt exists; else; echo foo.txt does not exist; end</tt>
will print <tt>foo.txt exists</tt> if the file foo.txt
exists and is a regular file, otherwise it will print
<tt>foo.txt does not exist</tt>.
The following code tests whether a file `foo.txt` exists as a regular file.
The emit builtin fires a generic fish event. Such events can be caught by special functions called event handlers.
`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
The <tt>eval</tt> function causes fish to evaluate 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
<pre>
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
The \c exec builtin is used to replace the currently running shells
process image with a new command. On successful completion, exec never
returns. exec can not 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. 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.
The <tt>exit</tt> builtin 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">`set`</a> command:
\fish{cli-dark}
set -x key value
set -e key
\endfish
\section faq-login-cmd How do I run a command every login? What's fish's equivalent to .bashrc?
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 `fish_prompt` function. Put it in `~/.config/fish/functions/fish_prompt.fish`. For example, a simple prompt is:
\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.
\section faq-cmd-history How do I run a command from history?
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!
`fish` uses parentheses for subcommands. For example:
\fish{cli-dark}
for i in (ls)
echo $i
end
\endfish
\section faq-exit-status How do I get the exit status of a command?
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>`SOME_VAR=1 command` produces an error: `Unknown command "SOME_VAR=1"`.</i>
Use the `env` command.
`env SOME_VAR=1 command`
You can also declare a local variable in a block:
\fish{cli-dark}
begin
set -lx SOME_VAR 1
command
end
\endfish
\section faq-customize-colors How do I customize my syntax highlighting colors?
Use the web configuration tool, <a href="commands.html#fish_config">`fish_config`</a>, or alter the <a href="index.html#variables-color">`fish_color` family of environment variables</a>.
<hr>
\section faq-update-manpage-completions How do I update man page completions?
Use the <a href="commands.html#fish_update_completions">`fish_update_completions`</a> command.
<hr>
\section faq-cwd-symlink Why does cd, $PWD and and various fish commands always resolve symlinked directories to their canonical path?
<i>
For example if ~/images is a symlink to ~/Documents/Images, if I write
'cd images', my prompt will say ~/D/Images, not ~/images.
</i>
<i>For example if `~/images` is a symlink to `~/Documents/Images`, if I write '`cd images`', my prompt will say `~/Documents/Images`, not `~/images`.</i>
Because it is impossible to consistently keep symlinked directories
unresolved. It is indeed possible to do this partially, and many other
shells do so. But it was felt there are enough serious corner cases
that this is a bad idea. Most such issues have to do with how '..' is
handled, and are varitations of the following example:
Because it is impossible to consistently keep symlinked directories unresolved. It is indeed possible to do this partially, and many other shells do so. But it was felt there are enough serious corner cases that this is a bad idea. Most such issues have to do with how '..' is handled, and are varitations of the following example:
Writing <code>cd images; ls ..</code> given the above directory
structure would list the contents of ~/Documents, not of ~, even
though using <code>cd ..</code> changes the current direcotry to ~,
and the prompt, the pwd builtin and many other directory information
sources suggest that the the current directory is ~/images and it's
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-autocomplete Why does the cd command autocompletion list the subdirectories of my home directory as completions?
Because they are completions. In fish, if you specify a relative
directory to the cd command, i.e. any path that does not start with
either './' or '/', the environment variable CDPATH will be examined, and any
directories in this path is used as a base direcotry. To disable this
feature, write <code>set CDPATH .</code> on the commandline.
<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, 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 open command uses the mimetype database and the .desktop files
used by Gnome and KDE to identify filetypes and default actions. If
at least one of these two desktops are installed, but the open command is
not working, this probably means that the relevant files are installed
in a nonstandard location. Please contact the <a
href='mailto:fish-users@lists.sf.net'>fish mailing list</a>, and
hopefully this can be resolved.
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. Unfortuntaly, 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 `chsh -s /bin/bash` if you are not sure.
Next, do the following (assuming fish was installed to /usr/local):
Sends the specified job to the foreground. 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 \%0</tt> will put the job with job id 0 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
A commandline 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.
- <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
The following options are available:
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` or `--command=COMMANDS` evaluate the specified commands instead of reading from the commandline
- `-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.
\section fish_config fish_config - start the web-based configuration interface
\subsection fish_config-description Description
`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.
`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` 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.
\subsection fish_config-example Example
`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 or otherwise prettify 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.
\c fish_indent understands the following options:
The following options are available:
- <tt>-h</tt> or <tt>--help</tt> displays this help message and then exits
- <tt>-i</tt> or <tt>--no-indent</tt> do not indent commands
- <tt>-v</tt> or <tt>--version</tt> displays the current fish version and then exits
- `-i` or `--no-indent` do not indent commands; only reformat to one job per line
- `-v` or `--version` displays the current fish version and then exits
- `--ansi` colorizes the output using ANSI escape sequences, appropriate for the current $TERM, using the colors defined in the environment (such as `$fish_color_command`).
- `--html` outputs HTML, which supports syntax highlighting if the appropriate CSS is defined. The CSS class names are the same as the variable names, such as `fish_color_command`
\section fish_prompt fish_prompt - define the apperance of the command line prompt
\section fish_prompt fish_prompt - define the appearance of the command line prompt
\subsection fish_promt-synopsis Synopsis
<pre>function fish_prompt
\subsection fish_prompt-synopsis Synopsis
\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 `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.
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.
