This merges a collection of changes attempting to rationalize how fish
handles the tty size.
The basic problem this addresses is that, prior to this fix, a call to
`common_get_width()` could result in arbitary code execution, as it lazily
updates COLUMNS and LINES which fires events, etc. With the new design, we
explicitly track the 'last known' tty size and also whether it is known stale,
and update it only at defined points.
This stuff is fraught and tricky, and so it is a merge commit so that if
something breaks, we can revert the whole thing and not end up with two
sources of termsize truth. Knock on wood.
Finish the transition to termsize.h. Remove the scary termsize bits
from common.cpp, which can throw off events at arbitrary calls and are
dangerously reentrant. Migrate everyone to the new termsize.h.
fish's handling of terminal sizes is currently rather twisted. The
essential problem is that the terminal size may change at any point from a
SIGWINCH, and common_get_{width,height} may modify it and post variable
change events from arbitrary locations.
Tighten up the semantics. Assign responsibility for managing the tty size
to a new class, `termsize_container_t`. Rationalize locking and reentrancy.
Explicitly nail down the relationship between $COLUMNS/$LINES and the tty
size. The new semantics are: whatever changed most recently takes
precendence.
Prior to this fix, fish would attempt to resize the terminal via
TIOCSWINSZ, which was added as part of #3740. In practice this probably
never did anything useful since generally only the tty master can use
this. Remove the support and note it in the changelog.
Prior to this fix, s_reset would attempt to reset the screen, optionally
using the PROMPT_SP hack to go to the next line. This in turn required
passing in the screen width even if it wasn't needed (because we were
not going to abandon the line). Factor this into two functions:
- s_reset_line which does not apply the hack
- s_reset_abandoning_line which applies the PROMPT_SP hack
common_get_width will "lazily" decide the screen width, which means
changing the environment variable stack. This is a surprising thing
to do from the middle of screen rendering.
Switch to passing in widths explicitly to screen.
The removed comparison ({begin,end,field} == INT_MIN) always evaluates
to false, because at this point in evaluation, `begin <= 0` has already
been evaluated to be false. Since INT_MIN <= 0, the second conditional
in all three of the affected cases is always false. The C++ standard
seems to guarantee left-to-right evaluation of logical operators, but
not necessarily bitwise operators.
Signed-off-by: Kristofer Rye <kristofer.rye@gmail.com>
With the new pexpect based framework, bind and pipeline expect tests can
be removed.
Amusingly the complete.fish check required the existence of bind.expect.
Fix the check at the same time.
Make it easier to use pexpect and to understand its error messages.
Switch to a style in tests using bound methods, which makes them
less noisy to write.
This adds a new interactive test framework based on Python's pexpect. This
is intended to supplant the TCL expect-based tests.
New tests go in `tests/pexpects/`. As a proof-of-concept, the
pipeline.expect test and the (gnarly) bind.expect test are ported to the
new framework.
We are 1-indexed, and so it's weird to have `test` count its arguments
from 0.
For `test 1 =` this changes the error from
test: Missing argument at index 2
1 =
^
to
test: Missing argument at index 3
1 =
^
test loves error messages like
test: Missing argument at index 2
without explaining where that "index 2" is.
So now, we print the arguments below that, with a caret pointing to
the place where the error occured.
For example:
> test 1 = 2 and echo true or echo false
test: Expected a combining operator like '-a' at index 3
1 = 2 and echo true or echo false
^
(Type 'help test' for related documentation)
Fixes#6030.
* docs/faq: Mention prepend_sudo
[ci skip]
* __fish_prepend_sudo: Use $history[1] if commandline is empty
Currently, if you press alt+s with an empty commandline, it inserts
"sudo", which seems fairly useless.
Now, it inserts "sudo " followed by the last history entry, which
makes it a replacement for `sudo !!`.
* docs
There's a terrible number of fishscripts that start with
set path (dirname (status filename))
And that's really just a bit boring.
So let's let it be
set path (status dirname)
This reverts commit 1b0ec21773.
"Interactive" has multiple meanings here, one of them being "the whole shell" is interactive, which `status is-interactive` tests, and one "this interaction is interactive", which happens when `read`ing in a script.
Fixes#7080.
This change is necessary to fix dynamic titles for the Alacritty
terminal. We do this by simply adding the (wchar_t *) literal
L"alacritty" to the end of the title_terms array. This variable is
ultimately used in the subsequent function
does_term_support_setting_title (dtsst) for the purposes of whitelisting
certain terminals.
If an Alacritty user does not have the terminfo for alacritty present in
their terminfo database, Alacritty sets the TERM variable to
"xterm-256color", but if the terminfo for Alacritty is present, TERM is
instead set to "alacritty".
Prior to this change, none of the "fallback patterns" in the dtsst
function (which is used to ultimately decide whether or not a given
value of the TERM environment variable is supported) would apply to a
value of "alacritty". Ordinarily, the dtsst function would return true
if nothing matches, but one of the final checks involves testing the
result of ttyname_r to see if it contains the substring "tty", which
causes dtsst to return false. In the case where TERM="alacritty", this
is erroneous, because Alacritty does, indeed, support changing its title
and will also silently ignore attempts to change the title if that
behavior has been disabled by the user [1].
The changed file, src/env_dispatch.cpp, was reformatted by clang-format
in accordance with the documented procedures for contributors.
Signed-off-by: Kristofer Rye <kristofer.rye@gmail.com>
[1]: 1dacc99183/alacritty_terminal/src/term/mod.rs (L896-L900)
When fish exits, it tries to restore the foreground process group.
However this may actually steal control of the fg process group
from another process. Fix this by clearing the SIGTTOU handler so
that tcsetpgrp() will fail.
Credit to @mqudsi for awesome debugging.
Fixes#7060
Prior to this change, if the user's prompt was wider than the terminal, we
would reduce it to just `> `. With this change, attempt to truncate the
prompt.
For each line of the prompt, calculate its width. If the width exceeds
COLUMNS, prepend ellipsis to that line, and start removing characters
until it fits. Escape sequences are skipped.
Fixes#904
Initially I wanted to pick a different name to avoid confusion with
process groups, but really job trees *are* process groups. So name them
to reflect that fact.
Also rename "placeholder" to "internal" which is clearer.
Prior to this, jobs all had a pgid, and fish has to work hard to ensure
that pgids were inherited properly for nested jobs. But now the job tree
is the source of truth and there is only one location for the pgid.
job_lineage was used to track "where jobs came from" but the job tree idea is
a better abstraction. It groups jobs together similar to how a process group
would in other shells. Begin to remove the notion of lineage.
Job trees come in two flavors: “placeholders” for jobs which are only fish
functions, and non-placeholders which need to track a pgid. This adds
logic to allow a job to decide if its parent's job tree is appropriate,
and allocating a new tree if not.
job_tree represents the data that should be shared between a job and any
jobs that may be spawned by functions or eval run as part of that job. It
reifies shared data that before was handled piecemeal.
We use sphinx with rst for our documentation, and github supports rst
here, so it seems weird to have markdown just for these.
It also allows us e.g. to include the CHANGELOG in the docs without
requiring another build dependency.
Currently fish aborts execution mid-pipeline if a file redirection
failed, which can leave the shell in a broken state (job abandoned after
giving control of the terminal to an already-executed job in the
pipeline).
This patch replaces a failed fd with a closed fd and continues execution
if the affected process wasn't the first in the pipeline.
While this is a hack to address the regression behind fish-shell/#7038
introduced in d62576c, it can also be argued that this behavior is
actually more correct... right?
Closes#7038.
* Add an "_" builtin to call into gettext
We already have gettext in C++ (if available), so it seems weird to
fork off a command to start it from script.
This is only for fish's own translations. There's no way to call into
other catalogs, it just translates all arguments separately.
This is faster by a factor of ~1000, which allows us to call
translations much more, especially from scripts.
E.g. making fish_greeting global by default would hurt cost-wise,
given that my fish starts up in 8ms and just calling the current `_`
function takes 2ms, and that would have two calls.
Incidentally, this also makes us rely on a weirdly defined function
less, so it:
Fixes#6804.
* docs: Add `_` docs
Let's see if that filename works out.
* Reword _ docs
This is a function you can either execute once, interactively, or
stick in config.fish, and it will do the right thing.
Some options are included to choose some slightly different behavior,
like setting $PATH directly instead of $fish_user_paths, or moving
already existing components to the front/back instead of ignoring
them, or appending new components instead of prepending them.
The defaults were chosen because they are the most safe, and
especially because they allow it to be idempotent - running it again
and again and again won't change anything, it won't even run the
actual `set` because it skips that if all components are already in.
Fixes#6960.
Variables like $status and $history showed up in all scopes, including
universal, when querying with `set -q` or `set -S`.
This makes it so they all only count as set in global scope, because
we already only allow assignment to electric variables in global scope.
Fixes#7032
This patch fixes an underflow in the jump family of readline commands
when called via `commandline -f` outside of a bind context such as
`commandline -f backward-jump`. To reproduce, run that command at a
prompt and the shell will crash with a buffer underlow.
This happens because the jump commands have non-zero arity, requiring a
character event to be pushed on the function args stack. Pushing the
character event is handled in `function_push_args`, called by
`inputter_t::mapping_execute`, which checks the arity of the function
and enqueues the required number of charcter events. However,
`builtin_commandline` calls `reader_queue_ch`, which in turn calls
`inputter_t::queue_ch`, which immediately enqueues the readline event
without calling `function_push_args`, so the character event is never
pushed on the arg stack.
This patch adds a check in inputter_t::queue_ch which checks if the
character event is a readline event, and if so, calls
`function_push_args`.
fish_git_prompt encloses its output in brackets, however this can be changed by supplying a format string to it, i.e. `fish_git_prompt %s`.
However when using `fish_vcs_prompt` there's no way to pass on the arg to fish_git_prompt, so you need to manually remove it.
fish_hg_prompt doesn't have the same format string support as fish_git_prompt, but I suppose it could be added later if needed.
When sending SIGCONT to a stopped job, this behaves now
a bit more like a job that was continued by the bg builtin;
bg uses job_t::continue_job which seems overkill here.
We don't need to call it if a job was stopped, because in that case
read_i() will fire fish_prompt already, because the newly stopped job
was probably a foreground job.
Fixes#1018
This just produced a spurious "Unknown signal" error on NetBSD and OpenBSD, and
the number picked was arbitrary. So let's just use the maximum that
appears to work everywhere.
(I will hate this if I test it elsewhere and need to reduce it to 62)
(This is a squashed commit, I did indeed hate it when I moved from
NetBSD to OpenBSD)
The default implementation will not print any output in that case, but this provides users with additional flexibility when it comes to customising the shell's behaviour.
This allows users to customise the behaviour of the shell by redefining the function. This is similar to how fish_title or fish_greeting behave, where the default implementation can be easily overridden.
The function receives as arguments the job id, command line, signal name and signal description.
Since 4414d5c888 (in fish 3.0.0) we
don't autoload completions if the command doesn't exist.
So there is no need to check inside the scripts anymore.
Whats more, a few (like pip and cabal) checked `command -q` instead of
`type -q`, meaning they'd fail if someone used a function instead of a
command of that name.
If the *command* actually needs to exist, checks like that are still
warranted, like in `npm` where aliasing it to `nvm` is popular.
A teensy additional bit: Make `sysctl -w` the same as `sysctl
--write`. That description was bogus.
At the moment calling __fish_prepend_sudo multiple times does not toggle
sudo, and also unnecessarily uses the `-c` flag to `commandline` to see if
the first token on the commandline is "sudo".
This change removes the `-c` switch and also toggles "sudo" on multiple
calls to __fish_prepend_sudo, while maintaining the cursor position and
while maintaining any spaces between "sudo" and the next token on the
commandline.
The local-exported variable will have disappeared by the time the
function is called.
"-V"/"--inherit-variable" is meant for something like this.
Fixes#7011
This allows tools like `stty` to set the terminal modes and fish will
honor them, for external commands.
The modes for fish are kept as they are.
Until now, the only change fish would do to the external modes is to
disable flow control *every time*, this changes it to only disabling
it on startup.
After that we don't apply *any* changes to the external modes (no
checks or validation or...), because we've never done that (other than
flow control), and it's not been a problem.
Fixes#2315.
The completions for help know many more help topics, it makes no sense
to whitelist them here.
Fix anchor links for tutorial sections.
Remove some dead code: the "man" branch was unreachable because of the
earlier (__fish_print_commands) case.
Add missing options:
--path causes the specified variable to be treated as a path variable, meaning it will automatically be split on colons, and joined using colons when quoted (echo "$PATH") or exported.
--unpath causes the specified variable to not be treated as a path variable. Variables with a name ending in "PATH" are automatically path variables, so this can be used to treat such a variable normally.
[ci skip]
This removes the before_install step because it's currently failing.
The error message says pcre2 is already installed anyway, so we can
skip the entire thing and remove brew from the equation.
* Fix issue if md5sum is used instead of md5
Both have a different output which results in different array sized
Signed-off-by: Ron Gebauer <ron.gebauer@raytion.com>
* Add feedback
Signed-off-by: Ron Gebauer <ron.gebauer@raytion.com>
* Fix manpath handling in create_manpage_completions.py
...as well as do some (very!) light cleanup.
Currently, `create_manpage_completions.py` does not properly
understand/respect the `$MANPATH` variable. One important feature of
`$MANPATH` is that an empty component (i.e. the trailing : in
`foo:bar:`) expands to the 'default' or 'system' path -- that is to say,
the path that would be used if `$MANPATH` was unset. This allows the
user to extend the manpath without clobbering it, and has been a feature
many Unices have included for years.
The current implementation blindly uses the `$MANPATH` variable if it
exists, which does not allow for this behaviour -- to expand the
variable correctly, an external program must be invoked. Therefore, we
first shell out to the 'proper' (read: best guess) external program. If
that fails, we can then try to use `$MANPATH` directly/literally.
Finally, if both of those are impossible, we can fall back to some
common paths from widely used operating systems.
Note that the `man.conf` parsing has been removed: this is because while
many 'traditional' Unices (BSDs, Solaris, macOS) support this file, only
macOS actually ships a file -- most other Unices use a `conf.d`-style
layout and supporting that from our Python is impractical and silly at
best. On GNU (read: Linux) systems, `mandb` uses `/etc/man_db.conf` with
slightly different syntax and sematics. As this code-path has bitrotted
(and likely never worked, anyway), just remove it.
`create_manpage_completions.py` looks like it has suffered a lot of
confusion and bitrot in general over the last few years -- and is
overdue for a major refactoring. I am quite interested in tackling this,
but I plan to wait until the go-ahead to drop support for Python 2 is
given, as a major refactor/rewrite that still supports Python 2 (and
thus ignores the ergonomic/API/syntax improvements of Python 3) does not
make sense to me.
Related: #5657
It would probably be good to revisit `man.fish` once again when a
comprehensive refactor happens: hopefully every permutation of
`man`/`$MANPATH` could be documented as part of that effort.
* Restore /etc/man.conf parsing
I was not aware that this codepath was used -- since it appeared that it
would throw an error when it was reached. Redo it, using regex, and
support parsing NetBSD man.conf as well (untested).
* Fix create_manpage_completions.py under Python 2
It removed $KONSOLE_PROFILE_NAME and added $KONSOLE_VERSION.
Let's assume if $KONSOLE_PROFILE_NAME is set we use the old sequences,
if not we use the new ones.
This reverts commit 535845861a.
That commit introduced a bug where tab-completing commands no longer
prints their descriptions, unless there is an exact match.
If we output text and end up in the last column, the sticky right edge
will cause a clr_eos to erase the last character. Ensure this doesn't
happen by not issuing clr_eos in that case.
Fixes#6951
If a readline command is bound to a key sequence which also sends a
signal, then fish will set the cancel flag in addition to handling the
command. But this cancel flag is then persistent. Ensure it gets cleared
after each command.
Fixes#6937
The manual page for statfs(2) only lists SMB_SUPER_MAGIC and
CIFS_MAGIC_NUMBER, but it turns out there's a third type of CIFS/SMB
mount, represented by SMB2_MAGIC_NUMBER.
Haunting me from #6609.
The CMake variable FISH_USE_SYSTEM_PCRE2 now controls whether fish uses
system PCRE2 or the bundled version. The default is to use the system
version, unless no such version is found, or unless it is a macOS build
with code signing. Note the default behavior has not changed.
Fixes#6952
Use inline initializers rather than the constructor, and adopt some
maybe_t.
Also move post_buff_1 and post_buff_2 to local variables instead of
member variables.
Commit 5fccfd83ec, with the fix for #6806,
switched eval to buffer its output (like other builtins do). But this
prevents using eval with commands that wants to see the tty, especially
fzf. So only buffer the output if the output is piped to the next process.
builtin_eval needs to know whether to set up bufferfills to capture its
output and/or errput; it should do this specifically if the output and
errput is piped (and not, say, directed to a file). In preparation for
this change, add bools to io_streams_t which track whether stdout and
stderr are specifically piped.
Commit 5fccfd83ec, with the fix for #6806,
switched eval to buffer its output (like other builtins do). But this
prevents using eval with commands that wants to see the tty, especially
fzf. So only buffer the output if the output is piped to the next process.
This will solve #6955 (which needs to go into a point release).
builtin_eval needs to know whether to set up bufferfills to capture its
output and/or errput; it should do this specifically if the output and
errput is piped (and not, say, directed to a file). In preparation for
this change, add bools to io_streams_t which track whether stdout and
stderr are specifically piped.
Prior to this fix, builtin_eval would direct output to the io_chain of the
job. The problem is with pipes: `builtin_eval` might happily attempt to
write unlimited output to the write end of a pipe, but the corresponding
reading process has not yet been launched. This results in deadlock.
The fix is to buffer all the output from `builtin_eval`. This is not fun
but the best that can be done until we have real concurrent processes.
Fixes#6806
Give string expansion an (optional) parent pgroup. This is threaded all
the way into eval(). This ensures that in a mixed pipeline like:
cmd | begin ; something (cmd2) ; end
that cmd2 and cmd have the same pgroup.
Add a test to ensure that command substitutions inherit pgroups
properly.
Fixes#6624
This was a weird one. We split the aliases correctly even with
multiple lines, but then broke it all again when we just printed the
description.
Note that it would be possible to use `string split0` here, but since
anything longer than a line is likely too long for a description
anyway we don't bother.
Fixes#6946.
Changes it from
```
$fish_color_user: not set in local scope
$fish_color_user: set in global scope, unexported, with 1 elements
$fish_color_user[1]: length=3 value=|080|
$fish_color_user: set in universal scope, unexported, with 1 elements
$fish_color_user[1]: length=7 value=|brgreen|
```
(with the trailing empty line - not just a newline)
to
```
$fish_color_user: set in global scope, unexported, with 1 elements
$fish_color_user[1]: |080|
$fish_color_user: set in universal scope, unexported, with 1 elements
$fish_color_user[1]: |brgreen|
```
* Fire fish_postexec event after tokenization error
This is a fix for issue #6816 "shell integration with tokenization error"
* Pass command-line to fish_postexec on tokenization error
* Rename and move event for tokenization error
For the last 15 years the space was only skipped when the completion
ended in one of "/=@:". Add ".," since they are also sometimes used to
separate independent words within a token.
Fixes#6928
Improves on #6833
When this switched over from directly piping commandline to storing
its output and using printf, I inadvertently always added a trailing
newline. That's probably annoying.
Note that this will now always *remove* a trailing newline (because
the command substitution does). That will barely make a
difference (because trailing newlines are quite unusual in the
commandline) and will probably feel better than keeping it - we could
even make a point of removing trailing whitespace in general.
Fixes#6927
Prior to this fix, if job control is enabled but stdin is not a tty, we
would return an error from terminal_maybe_give_to_job which would cause us
to avoid waiting for the job. Instead just return notneeded.
Fixes#6573.
This updates the behavior of tilde to match the behavior found in vim.
In vim, tilde toggles the case of the character under the cursor and
advances one character. In visual mode, the case of each selected
character is toggled, the cursor position moves to the beginning of
the selection, and the mode is changed to normal. In fish, tilde
capitalizes the current letter and advances one word. There is no
current tilde command for visual mode in fish.
This patch adds the readline commands `togglecase-letter` and
`togglecase-selection` to match the behavior of vim more closely. The
only difference is that in visual mode, the cursor is not modified.
Modifying the cursor in visual mode would require either moving it in
`togglecase-selection`, which seems outside its scope or adding
something like a `move-to-selection-start` readline command.
The description for an alias which already has escape sequences will
use backslash escapes for quoting; usually `string escape` can simply
quote it. Use a regex that accepts either escaping style.
We've been getting a bunch of comments on old closed issues. Instead
people should create new ones.
This adds a github "workflow" that should lock closed issues/prs after
90 days, except those labelled "question".
Let's see how it works out.
We had previously added a more helpful error message when a literal zero
index was specified when indexing into an array. This patch extends that
coverage to cases indexing into a command substitution, e.g.
```fish
echo (printf "hello\nworld\n")[0]
```
A minor follow-up to #6866 (e658a88ab0).
These file types should be properly handled by other unzip flavors too,
regardless of Debian's/non-Linux Unixes' idiosyncrasies.
Otherwise it would print "Unknown Signal" on Linux. I didn't see an
obvious way to check signal validity, plus it hardly matters.
Also mimic the output from BSD strsignal on Linux.
Travis puts the commit message in an environment variable, so if it
contains the string `_flag` this would match TRAVIS_COMMIT_MESSAGE.
That happened in ca91c201c3, so the
tests failed.
We simply tighten the regex a little more, and make a commit message
that doesn't include the string.
I've been dealing with these a lot recently (android dev...), and it's
pretty annoying that unzip completions don't recognize them (They're
just zip files with a weird file extension).
For `true`, this makes uses like the
: some description of the job &
we used to have impossible, also it's just *wrong* that true can
return something that isn't true.
For false it's not super important but it should generally be
symmetrical with true.
This allows all variables to be set properly when the prefix or datadir changes.
The generated .pc file looks like this:
prefix=/usr/local
datadir=${prefix}/share
completionsdir=${datadir}/fish/vendor_completions.d
functionsdir=${datadir}/fish/vendor_functions.d
confdir=${datadir}/fish/vendor_conf.d
Name: fish
Description: fish, the friendly interactive shell
URL: https://fishshell.com/
Version: 3.1.0-402-g75ae172ba228-dirty
Closes: https://bugs.archlinux.org/task/65904
Due to RHEL's very old Python and other issues, keeping the tests
running is more work than it's worth. Switch to making sure the compiled
binary runs only.
At least on some versions/systems, pkg-config outputs a trailing
space. Since the usually-desired behavior isn't to have a blank argument,
recommend using `string split -n` instead of `string split`.
Fixes#6836.
[ci skip]
Fixes#6830
For some reason, with this change, typing "vi", Control-Z, and 2 x Control-D,
results in the cursor not moving correctly, but this only
seems to happen when starting fish from a fish that doesnt have this fix.
I hope that is a temporary glitch.
Building on OS X versions prior to 10.13.6 fails at the very end when
running `codesign`.
The `-options runtime`-argument isn't available on these earlier
versions of the OS.
Simply running codesign without that argument (on OS X <10.13.6) seems
to produce a runnable binary with no security warnings.
Make is much better than us at figuring out which makefile to use,
just pass through the relevant parameters.
Also previously they didn't work at all for Makefiles like the one in
https://github.com/jonas/tig, for example.
The prefix 'haha' is short enough, (and phonetic enough), that it could collide with an existing user on the system where the tests are running, causing the test to fail.
I kinda hate how fussy clang-format is. It reflows text
constantly (line limit), forces things onto one line *except* when
they're too long, and wants to turn this:
```c++
return true;;
```
into this:
```c++
return true;
;
```
instead of, you know, eliminating the second semicolon?
Anyway, it is what it is and we use it, I'll just look into getting some
more slack.
This allows code of the form `if jobs -q $some_pid` in scripts to check whether a previously started job is still running. Previously this would return the correct value, but also print an error message.
The invalid argument errors will still be printed.
Added test cases for both.
Add completion for terraform worskpace.
The terraform env command is deprecated.
The terraform workspace command should be used instead.
"terraform env" will be removed in a future Terraform version.
Because `command ./somedir/somecommand` is okay.
Fixes test failure from aa304cbd3d.
Child directories in $PATH are still not suggested, as was the main
intention of the commit that introduced the tests:
8a3cf144f Don't include child directories of $PATH in completions.
Fixes#6798
This re-adds some false positives: functions, builtins and abbreviations
are suggested after commands like sudo but I don't think anyone had
complained about that.
The default indicator ruined alignment, which is a major design
feature here.
Handle it by including the mode indicator in the prompt proper.
Fixes#6802.
[ci skip]
When we say "the XYZ command/builtin", we should typically include a
link. The exceptions are
- In the documentation for that command - no need to link to ulimit in
the ulimit page
- When we've already linked before - not every thing needs to be
clickable, or clicking it will cause the browser to mark fifty words
as visited. This is roughly what wikipedia does for crosslinks.
[ci skip]
Many people have mentioned wanting support for changing / yanking /
deleting between "" and '', meaning the commands `ci' ci" yi' yi" di' di"`,
so this adds that support in a generic, and thus potentially confusing way.
The concept is that we check for the character backwards and forwards
before making the selection. Unfortunately, this will also work for *any*
character that isn't `w` or `W`, so `cia` could change everything between
two `a` characters.
Looking through the [bind documentation](https://fishshell.com/docs/current/cmds/bind.html)
and input handler at `src/input.cpp`,
this is the best possible solution I could come up with until
`forward-jump` and `backward-jump` can accept input in the call to `bind`,
and not just from stdin, meaning we can write a binding as:
```
bind di\" backward-jump-till \" and repeat-jump-reverse ...`
```
If that were done, then other commands such as `di)` to go between `()` would
be possible.
There are also some added `y` bindings not part of #6648.
Let me know if you need anything else.
This reverts commit 7f402cdae7.
There are fundamental issues with `funced` and `funcsave` that prevent
this from working. A file and a function are not interchangeable.
This was meant as an alternative key name or something, but it's just
rendered. It seems clear what the glyph refers to and we explain it
where we explain the left/right bindings anyway.
[ci skip]
Currently we do not add such command lines to the history, so there
won't be a suggestion from history anyway.
Fixes#6763 which occurs because midnight commander feeds fish commands
like this one (note the loading space)
` cd (printf '%b' '\0057home\0057johannes\0057git\0057fish\0055shell\0057build')`
We have now entirely switched the script tests to littlecheck.
Note: This adjusts the complete_directories test, because it removes a
directory that was created before by a .in test. There's no real
change in behavior.
This does require the test directory be cleaned, or the tests will fail.
test_util gets to stay for a while longer, because it sets up the
testing env (locale and such).
This, together with the other testX, really just tests some basic
syntax. So let's just call it "basic".
Note that this file uses escaped newlines on purpose, so restyling it
would currently break it. I'm not sure what the best thing to do here is.
Instead of invoking littlecheck.py independently for each file, pass
all files at once. This amortizes the Python startup cost, and reduces
the total test time by ~15 seconds (!).
Commit b2f40783a2b5b0663409c4daa90b794b02dd37a6
This has better progress reporting, and the exit status of littlecheck
indicates how many test failures there were.
This isn't quite the old-style test, but it checks some of the line
continuation stuff.
Note that littlecheck ignores leading whitespace, so testing the
actual indentation requires some more effort.
Things like
```fish
\
echo foo
```
or
```fish
echo foo; \
echo bar
```
are a formatting blunder and should be handled.
This makes it so the escaped newline is removed, and the
semicolon/token_type_end handling will then put the statements on
different lines.
One case this doesn't handle brilliantly is an escaped newline after a
pipe:
```fish
echo foo | \
cat
```
is turned into
```fish
echo foo | cat
```
which here works great, but in long pipelines can cause issues.
Pipes at the end of the line cause fish to continue parsing on the
next line, so this can just be written as
```fish
echo foo |
cat
```
for now.
Add completions for `downgrade` tool
Add new `--installed` option for printing Arch packages
Change Arch Linux package related completions to use `--installed`
add newline
1. When the wall time and cpu time rows has different units
e.x. running multiple cores
2. When duration is around 1E3 or 1E6 microseconds
printf("%6.2F", 999.995) gives 1000.00 which is 7 digits
The output of
systemctl list-units
seems to include a marker of '●' or '*' for some units, even if the
output is not going to a terminal and "--no-legend" and "--no-pager"
are given. This appears
to be a recent development, and there does not appear to be a flag to
disable it.
So we simply filter it out in the completions to once again hopefully
offer the actual units.
Fixes#6740
Even if $DISPLAY is unset, xdg-open can be useful, and on systems that
have xdg-open, "open" is most likely some god awful outdated thing
called "openvt" elsewhere.
Fixes#6739
[ci skip]
If given a prompt that includes a non-ascii char and a C locale, fish
currently fails to properly display it.
So you set `function fish_prompt; echo 😃; end` and it shows empty
space.
While the underlying cause is obviously using a C locale and non-C
characters to begin with, this is an unacceptable failure mode.
Apparently I misunderstood wcstombs, so I inadvertently broke this in
2b0b3d3 while trying to fix 5134949's crash.
Just return the offending bit to pre-5134949 levels, so instead of an
infinite recursion we just call a lame function a couple of times.
This tries to see if quotes guard some expansion from happening. If it
detects a "weird" character it'll leave the quotes in place, even in
some cases where it might not trigger.
So
for i in 'c' 'color'
turns into
for i in c color
The rationale here is that these quotes are useless, wasting
space (and line length), but more importantly that they are
superstitions. They don't do anything, but look like they do.
The counter argument is that they can be kept in case of later
changes, or that they make the intent clear - "this is supposed to be
a string we pass".
This means you can install multiple architectures of fish (eg x86 and
x86_64) alongside each other, using the same fish-common package.
Idea from the Debian fish package (version 3.1.0-1.1) by Punit Agrawal
<punit@debian.org>.
This teaches the reader fast-path to use self-insert-notfirst, allowing
it to handle spaces. This greatly increases the performance of paste by
reducing redraws.
Fixes#6603. Somewhat improves #6704
This adds basic support for self-insert-notfirst. When we see a
self-insert-nonempty char event, we kick it back to the outer loop,
which only inserts the character if the cursor is not at the beginning.
This adds a new readline command self-insert-notfirst, which is
analogous to self-insert, except that it does nothing if the cursor
is at the beginning. This will serve as a higher-performance implementation
for stripping leading spaces on paste.
Fixes#6138
Naturally this does not work for many other editors/aliases,
but it's still nice that we can make it work for some common
editors without requiring any configuration.
Of course this approach is not terribly flexible; but it's
alwyas possible to just wrap edit_command_buffer and set an
EDITOR that knows about the cursor position. It doesn't
feel important enough to add a configuration option.
Using a local variable means we have to expand it when loading the
completion. With this approach, the content of the variable will be
expanded, so escape it.
The default hg prompt is slow on large repositories (hg status takes
2-3 seconds on mozilla-central) which is unacceptable as a default.
Mimick our git prompt: by default, only show the current branch.
If the new variable $fish_prompt_hg_show_informative_status is set,
then use the old behavior.
[ci skip]
debounce_t will be used to limit thread creation from background highlighting
and autosuggestion scenarios. This is a one-element queue backed by a
single thread. New requests displace any existing queued request; this
reflects the fact that autosuggestions and highlighting only care about
the most recent result.
A timeout allows for abandoning hung threads, which may happen if you
attempt to e.g. access a dead hard-mounted NFS server. We don't want
this to defeat autosuggestions and highlighting permanently, so allow
spawning a new thread after the timeout (here 500 ms).
The problem is that under TSAN, the timing of signals becomes very weird and
exposes some real race conditions. We will need to re-design how signal
event handlers work.
bbc3fecbe introduced a regression where support for 256 color was not
detected on xterm-like terminals that did not define the TERM_PROGRAM
env variable. Almost no terminal on linux define this variable.
This test launches two background processes and is sensitive to
interleaving of output. Fix it so that newlines are not output by
the background process.
Hopefully this fixes the flakiness of this test.
55e3270 introduced a regression where we would remove all completed
jobs. But jobs that want to print a status message get skipped, so
the status message (and associated event handlers) might not get run.
Fix this by making it explicit which jobs are safe to process, and which
should be skipped.
Fixes#6679.
f8ba0ac5bf introduced a bug where INT handlers would themselves be
cancelled, due to the signal. Defer processing handlers until the
parser is ready to execute more fish script.
Fixes the interactive case of #6649.
This was written before local-exported variables did anything useful.
Passing these vars as local-exports removes the need to define the
validation function with `--no-scope-shadowing` which is quite the
hack.
This is apparently quite slow on large svn repos (like 40 seconds
slow), and we don't have a good thing to display other than the full
file information.
So we'll have to disable it for now.
Fixes#6681.
[ci skip]
If a background process runs a fish function which launches another
background process, ensure that these background procs get different
pgroups. Add a test for it.
Which happened when starting the selection at the end of the commandline.
In this case, selections still interact weirdly with autosuggestions (the
first character of the suggestion appears to be part of the selection
when it's not).
Fixes#6680
This executes `fish --no-execute` a whole bunch of times in order to
find syntax errors in our fish scripts.
tests/ is exempt because it contains syntax errors on purpose.
This is a great idea in principle, but it takes ~4s on my system.
Since #6406, read will trim whitespace before the last variable.
In this case there is only one variable, and the line looks like
M CHANGELOG.md
so it does indeed start with whitespace, and the whitespace is quite
significant.
Fixes#6650.
[ci skip]
This used to use doxygen's html blocks, which don't have a *direct*
equivalent in sphinx in code blocks.
Instead of adding this to the pygments highlighter, let's just use
some roles.
It's a teensy bit awkward as we then use block styling, but we want to
add more of our own styling anyway, so we can presumably get this
somehow, and these html tags look awkward and confuse people.
Fix#6640
[ci skip]
- Define it before the headers so they can pick the variadic tparm
prototype.
- We need a TPARM_VARARGS define, add it to config_cmake.h.
- Move & adjust comment - put it near the code, and mentiont that
NetBSD curses doesn't need the kludge.
Now variadic tparm is used on NetBSD instead of the Solaris kludge.
Prior to this commit, when executing a builtin, we mark the job as not
foreground. After this commit we no longer modify the foreground state
of the job just for the builtin.
There was the following comment:
// Since this may be the foreground job, and since a builtin may execute another
// foreground job, we need to pretend to suspend this job while running the
// builtin, in order to avoid a situation where two jobs are running at once.
The concern seemed to be in the `bg` and `fg` builtins, which might attempt
to foreground or background the jobs associated with `bg` and `fg` themselves.
But the builtins run before the job is marked constructed, so it cannot
actually happen.
Bravely remove this code.
Perform an ad-hoc code signing with the hardened runtime.
This ensures that these executables can pass notarization.
The code signing ID is controlled by the MAC_CODESIGN_ID CMake
cache variable.
This commit updates PCRE2 to 10.34, and we no longer include what's in their
tarball as-is. I've yanked out a lot of uneccessary stuff for the sake of the
size of our codebase.
original pcre2-10.34 dir: 11.5MB
pcre2 dir in this commit: 1.6MB
* Remove documentation, makefiles, test suites, etc. LICENSE remains.
* Disable building tests when configuring PCRE2
* Yard out JIT support: delete src/jit, src/pcre2_jit_*.c, and code doing
stuff to code->executable_jit that needs a jit header (it was already NULL
because we've always built with JIT disabled).
* Remove most .c and .h files not needed to compile: pcre2grep code,
pcre2test code, dftables.c, pcre2_printint.c, pcre2_fuzzsupport.c ...
* Remove FindBZip2, FindZLIB, FindReadline, FindEditline. These were used
only by pcre2grep and made CMake's report misleading with regard to
optional packages being used.
* Remove configure.ac except for version number and date which CMake checks
Next time we update PCRE2, refer to this commit message as well as a diff
between pcre2-10.34.tar.gz and ./pcre2-10.34/. Or better yet, cease including
pcre2.
Mimic the behavior of Linux's `apropos -e` and ~BSD's `apropos -f` with
the awk script by disallowing trailing characters in the name of the
manpage as compared to the original input string. Apart from being
faster (by aborting earlier and stopping `apropos` by breaking the pipe
after the first match), it's also more correct.
Mostly line breaks, one instance of tabs!
For some reason clang-format insists on two spaces before a same-line comment?
(I continue to be unimpressed with super-strict line length limits,
but I continue to believe in automatic styling, so it is what it is)
[ci skip]
It used to error out when a command wasn't known, even when it was a
function that would only be discovered via autoloading.
Now we just accept that a command doesn't exist when no-execute is
given - we're not gonna execute it anyway.
Also, in the same breath stop counting empty commands after expansion
and empty wildcard expansions as errors - these depend on runtime
values, so we can't verify them without executing.
Fixes#977.
(note that it still executes "time", but that's another commit)
Appending to an fd doesn't really make sense, but we allowed the
syntax previously and it was actually used.
It's not too harmful to allow it, so let's just do that again.
For the record: Zsh also allows it, bash doesn't.
Fixes#6614
When building fish-shell with the macOS 10.12 SDK, <sys/proc.h> does not
include <sys/time.h> but references `struct itimerval`. This causes a
compilation failure if we don't import <sys/time.h> ourselves.
This was previously masked by an import of <sys/sysctl.h>, which was
removed in fc0c39b6fd.
Glob ordering is used in a variety of places, including figuring out
conf.d and really needs to be stable.
Other ordering, like completions, is really just cosmetic and can
change if it makes for a nicer experience.
So we uncouple it by copying the wcsfilecmp from 3.0.2, which will
return the ordering to what it was in that release.
Fixes#6593
The `function --on-job-exit caller` feature allows a command substitution
to observe when the parent job exits. This has never worked very well - in
particular it is based on job IDs, so a function that observes this will
run multiple times. Implement it properly.
Do this by having a not-recycled "internal job id".
This is only used by psub, but ensure it works properly none-the-less.
"job_exit" events, despite their name, can only be created via
the '--on-job-exit caller' misfeature of function. Rename it to make it
clear that this event type is specifically for caller-exit.
This one tests a bunch of separate stuff, so we put it into a few
different files.
The main, new one is "slices.fish", which tests various index expressions.
Add the input function undo which is bound to `\c_` (control + / on
some terminals). Redoing the most recent chain of undos is supported,
redo is bound to `\e/` for now.
Closes#1367.
This approach should not have the issues discussed in #5897.
Every single modification to the commandline can be undone individually,
except for adjacent single-character inserts, which are coalesced,
so they can be reverted with a single undo. Coalescing is not done for
space characters, so each word can be undone separately.
When moving between history search entries, only the current history
search entry is reachable via the undo history. This allows to go back
to the original search string with a single undo, or by pressing the
escape key.
Similarly, when moving between pager entries, only the most recent
selection in the pager can be undone.
Same issue occurs here, as in #6270 (and fixed in 611a658 for `__fish_describe_command.fish`). Same reason. I've just copied the same workaround and changed the function name to match.
Fixes#6556.
Although present since 2006, fish no longer relies on POSIX-compliant tools to the same degree. This
code causes a platform specific change that makes the tests fail, so remove it.
6902459566 was an attempt to not print
$status twice in the prompt. As a result we print $pipestatus but
not $status, which /usually/ is the same as $pipestatus[-1] --- unless
the builtin "not" is used, which inverts the $status of a job (it does
not alter $pipestatus).
As a result, the default prompt prints unexpected status codes:
~ > not false
~ [1]> not true
~ > not true | true
~ > not false | false
~ [1|1]>
This commit reintroduces printing of $status after $pipestatus, but only
if it is different from $pipestatus[-1].
Additionally, we only print anything at all if the $status is nonzero,
to avoid confusing output on `not false | false`
~ > not false
~ > not true
~ [0] 1> not true | true
~ [0|0] 1> not false | false
~ >
I think this is closer to users' expectations for those cases; they should
not have to think about this implementation detail of the not-statement.
This switches bufferfills from using an exclusively-owned thread, to
sharing an fd_monitor. This allows multiple bufferfills to all use the same
thread.
fd_monitor is a new class which can monitor a set of fds, waiting for them
to become readable. When an fd becomes readable, a callback is invoked.
Timeouts are also supported.
This is intended to replace the "bufferfill" threads. Rather than one
thread per bufferfill, we will have a single fd_monitor which can service
multiple bufferfills. This helps today with nested command substitutions,
and will help in the future with concurrent execution.
* Replace multiple calls to `tail` and `string` with a single `string
replace` execution
* Dynamically generate list of available benches, bins, and tests for
`--bench`, `--bin`, and `--test` switches
[ci skip]
This makes two changes:
1. Remove the 'brace_text_start' idea. The idea of 'brace_text_start' was
to prevent emitting `BRACE_SPACE` at the beginning or end of an item. But
we later strip these off anyways, so there is no apparent benefit. If we
are not doing brace expansion, this prevented emitting whitespace at the
beginning or end of an item, leading to #6564.
2. When performing brace expansion, only stomp the space character with
`BRACE_SPACE`; do not stomp newlines and tabs. This is because the fix in
came from a newline or tab literal, then we would have effectively
replaced a newline or tab with a space, so this is important for #6564 as
well. Moreover, it is not easy to place a literal newline or tab inside a
brace expansion, and users who do probably do not mean for it to be
stripped, so I believe this is a good change in general.
Fixes#6564
fish has some unprincipled code that attempts to tcsetpgrp() to own the
terminal before running a builtin; this was added because 'read' might
want to read from the terminal. I added this code before fully
understanding how process groups and terminals work. A better fix would
be to ensure that fish is marked as the pgroup leader in the job when
the builtin is the first process in the job, and we do that now.
Courageously back out the changes to grab the terminal; see #5147 and
also #5133.
Introduce pgroup_provenance_t, a type which captures "where the pgroup
comes from." This centralizes some logic around how pgroups are
assigned, and it anticipates concurrent execution.
Just another version of the error. We still want to get a bug if it
ever triggers a *wrong* error, so we still list all the options
instead of going for `.*option:.*Z.*`.
Fixes#6554
Solaris/OpenIndiana/Illumos `rm` checks that and errors out.
In these cases we don't actually need it to be a part of $PWD as
it's just for cleanup, so we `cd` out before.
See #5472
See 1ee57e9244Fixes#6555Fixes#6558
In some cases on some platforms this could clobber errno, so doing something like
aThingThatFailsWithErrno();
FLOG(category, "Some message");
wperror("something");
would print the wrong error (presumably if that category was enabled).
In our case it was our (very) old friend RHEL6 returning ESPIPE instead of EISDIR.
Fixes#6545.
At the moment the "prepend sudo" functionality always sets the cursor to
the end of the line. This changes it to restore the relative position of
the cursor.
Prior to this fix, the cancellation C++ test would mark the parser as
interactive in an effort to install interactive signal handling (so that,
for example, SIGINT would stop the job and return control to the user).
However this flag would also cause fish to attempt to save and restore tty modes
across the job. This would fail since there is no tty, and so the job would fail
with an unexpected error code.
We don't need to mark the parser as interactive, we can just remove that line.
Fixes#6539.
Use some more move semantics to reduce allocations.
Correctly handle the case where the completion is empty. For example, if
you type:
ls<tab>
we get an empty completion (since ls is already a valid command), but we
still want to show its description.
Remove some unsafe statics - these are unsafe today in weird cases where
completions might invoke complete recursively, and also will soon be
unsafe with concurrent execution.
Prior to this fix, fish was rather inconsistent in when $status gets set
in response to an error. For example, a failed expansion like "$foo["
would not modify $status.
This makes the following inter-related changes:
1. String expansion now directly returns the value to set for $status on
error. The value is always used.
2. parser_t::eval() now directly returns the proc_status_t, which cleans
up a lot of call sites.
3. We expose a new function exec_subshell_for_expand() which ignores
$status but returns errors specifically related to subshell expansion.
4. We reify the notion of "expansion breaking" errors. These include
command-not-found, expand syntax errors, and others.
The upshot is we are more consistent about always setting $status on
errors.
macOS `mktemp -d` likes to return symlinks. Guard against that possibility.
That allows the test to succeed when run directly, instead of through the
build target.
It was possible to start the new job and execute `jobs` again before
the job died (or we noticed it did), so the test would fail.
To properly test, we need to ensure the job has been removed. `wait`
should do it.
This allows:
- Running scripts via shebang (not important here)
- Progress output (so we can ditch more of our run script)
- Context (only after, for now) - this is important if there is a test failure
This document provides guidelines for making changes to the fish-shell project. This includes rules for how to format the code, naming conventions, et cetera. Generally known as the style of the code. It also includes recommended best practices such as creating a Travis CI account so you can verify that your changes pass all the tests before making a pull request.
See the bottom of this document for help on installing the linting and style reformatting tools discussed in the following sections.
Fish source should limit the C++ features it uses to those available in C++11. It should not use exceptions.
Before introducing a new dependency, please make it optional with graceful failure if possible. Add
any new dependencies to the README.md under the *Running* and/or *Building* sections.
## Versioning
The fish version is constructed by the *build_tools/git_version_gen.sh* script. For developers the version is the branch name plus the output of `git describe --always --dirty`. Normally the main part of the version will be the closest annotated tag. Which itself is usually the most recent release number (e.g., `2.6.0`).
## Include What You Use
You should not depend on symbols being visible to a `*.cpp` module from `#include` statements inside another header file. In other words if your module does `#include "common.h"` and that header does `#include "signal.h"` your module should not assume the sub-include is present. It should instead directly `#include "signal.h"` if it needs any symbol from that header. That makes the actual dependencies much clearer. It also makes it easy to modify the headers included by a specific header file without having to worry that will break any module (or header) that includes a particular header.
To help enforce this rule the `make lint` (and `make lint-all`) command will run the [include-what-you-use](https://include-what-you-use.org/) tool. You can find the IWYU project on [github](https://github.com/include-what-you-use/include-what-you-use).
To install the tool on OS X you'll need to add a [formula](https://github.com/jasonmp85/homebrew-iwyu) then install it:
```
brew tap jasonmp85/iwyu
brew install iwyu
```
On Ubuntu you can install it via `apt-get`:
```
sudo apt-get install iwyu
```
## Lint Free Code
Automated analysis tools like cppcheck and oclint can point out potential bugs or code that is extremely hard to understand. They also help ensure the code has a consistent style and that it avoids patterns that tend to confuse people.
Ultimately we want lint free code. However, at the moment a lot of cleanup is required to reach that goal. For now simply try to avoid introducing new lint.
To make linting the code easy there are two make targets: `lint` and `lint-all`. The latter does exactly what the name implies. The former will lint any modified but not committed `*.cpp` files. If there is no uncommitted work it will lint the files in the most recent commit.
Fish has custom cppcheck rules in the file `.cppcheck.rule`. These help catch mistakes such as using `wcwidth()` rather than `fish_wcwidth()`. Please add a new rule if you find similar mistakes being made.
Fish also depends on `diff` and `expect` for its tests.
### Dealing With Lint Warnings
You are strongly encouraged to address a lint warning by refactoring the code, changing variable names, or whatever action is implied by the warning.
### Suppressing Lint Warnings
Once in a while the lint tools emit a false positive warning. For example, cppcheck might suggest a memory leak is present when that is not the case. To suppress that cppcheck warning you should insert a line like the following immediately prior to the line cppcheck warned about:
```
// cppcheck-suppress memleak // addr not really leaked
```
The explanatory portion of the suppression comment is optional. For other types of warnings replace "memleak" with the value inside the parenthesis (e.g., "nullPointerRedundantCheck") from a warning like the following:
```
[src/complete.cpp:1727]: warning (nullPointerRedundantCheck): Either the condition 'cmd_node' is redundant or there is possible null pointer dereference: cmd_node.
```
Suppressing oclint warnings is more complicated to describe so I'll refer you to the [OCLint HowTo](http://docs.oclint.org/en/latest/howto/suppress.html#annotations) on the topic.
## Ensuring Your Changes Conform to the Style Guides
The following sections discuss the specific rules for the style that should be used when writing fish code. To ensure your changes conform to the style rules you simply need to run
```
build_tools/style.fish
```
before committing your change. That will run `git-clang-format` to rewrite only the lines you're modifying.
If you've already committed your changes that's okay since it will then check the files in the most recent commit. This can be useful after you've merged another person's change and want to check that it's style is acceptable. However, in that case it will run `clang-format` to ensure the entire file, not just the lines modified by the commit, conform to the style.
If you want to check the style of the entire code base run
```
build_tools/style.fish --all
```
That command will refuse to restyle any files if you have uncommitted changes.
### Configuring Your Editor for Fish C++ Code
#### ViM
As of ViM 7.4 it does not recognize triple-slash comments as used by Doxygen and the OS X Xcode IDE to flag comments that explain the following C symbol. This means the `gq` key binding to reformat such comments doesn't behave as expected. You can fix that by adding the following to your vimrc:
```
autocmd Filetype c,cpp setlocal comments^=:///
```
If you use ViM I recommend the [vim-clang-format plugin](https://github.com/rhysd/vim-clang-format) by [@rhysd](https://github.com/rhysd).
You can also get ViM to provide reasonably correct behavior by installing
If you use ViM: Install [vim-fish](https://github.com/dag/vim-fish), make sure you have syntax and filetype functionality in `~/.vimrc`:
```
syntax enable
filetype plugin indent on
```
Then turn on some options for nicer display of fish scripts in `~/.vim/ftplugin/fish.vim`:
```
" Set up :make to use fish for syntax checking.
compiler fish
" Set this to have long lines wrap inside comments.
setlocal textwidth=79
" Enable folding of block structures in fish.
setlocal foldmethod=expr
```
If you use Emacs: Install [fish-mode](https://github.com/wwwjfy/emacs-fish) (also available in melpa and melpa-stable) and `(setq-default indent-tabs-mode nil)` for it (via a hook or in `use-package`s ":init" block). It can also be made to run fish_indent via e.g.
If you have a good reason for doing so you can tell `clang-format` to not reformat a block of code by enclosing it in comments like this:
```
// clang-format off
code to ignore
// clang-format on
```
However, as I write this there are no places in the code where we use this and I can't think of any legitimate reasons for exempting blocks of code from clang-format.
## Fish Script Style Guide
1. All fish scripts, such as those in the *share/functions* and *tests* directories, should be formatted using the `fish_indent` command.
1. Function names should be in all lowercase with words separated by underscores. Private functions should begin with an underscore. The first word should be `fish` if the function is unique to fish.
1. The first word of global variable names should generally be `fish` for public vars or `_fish` for private vars to minimize the possibility of name clashes with user defined vars.
## C++ Style Guide
1. The [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) forms the basis of the fish C++ style guide. There are two major deviations for the fish project. First, a four, rather than two, space indent. Second, line lengths up to 100, rather than 80, characters.
1. The `clang-format` command is authoritative with respect to indentation, whitespace around operators, etc.
1. All names in code should be `small_snake_case`. No Hungarian notation is used. The names for classes and structs should be followed by `_t`.
1. Always attach braces to the surrounding context.
1. Indent with spaces, not tabs and use four spaces per indent.
1. Document the purpose of a function or class with doxygen-style comment blocks. e.g.:
```
/**
* Sum numbers in a vector.
*
* @param values Container whose values are summed.
* @return sum of `values`, or 0.0 if `values` is empty.
*/
double sum(std::vector<double> & const values) {
...
}
*/
```
or
```
/// brief description of somefunction()
void somefunction() {
```
## Testing
The source code for fish includes a large collection of tests. If you are making any changes to fish, running these tests is mandatory to make sure the behaviour remains consistent and regressions are not introduced. Even if you don't run the tests on your machine, they will still be run via the [Travis CI](https://travis-ci.org/fish-shell/fish-shell) service.
You are strongly encouraged to add tests when changing the functionality of fish, especially if you are fixing a bug to help ensure there are no regressions in the future (i.e., we don't reintroduce the bug).
### Local testing
The tests can be run on your local computer on all operating systems.
```
cmake path/to/fish-shell
make test
```
### Travis CI Build and Test
The Travis Continuous Integration services can be used to test your changes using multiple configurations. This is the same service that the fish-shell project uses to ensure new changes haven't broken anything. Thus it is a really good idea that you leverage Travis CI before making a pull request to avoid potential embarrassment at breaking the build.
You will need to [fork the fish-shell repository on GitHub](https://help.github.com/articles/fork-a-repo/), then setup Travis to test your changes before making a pull request.
1. [Sign in to Travis CI](https://travis-ci.org/auth) with your GitHub account, accepting the GitHub access permissions confirmation.
1. Once you're signed in and your repositories are synchronized, go to your [profile page](https://travis-ci.org/profile) and enable the fish-shell repository.
1. Push your changes to GitHub.
You'll receive an email when the tests are complete telling you whether or not any tests failed.
You'll find the configuration used to control Travis in the `.travis.yml` file.
### Git hooks
Since developers sometimes forget to run the tests, it can be helpful to use git hooks (see githooks(5)) to automate it.
One possibility is a pre-push hook script like this one:
```sh
#!/bin/sh
#### A pre-push hook for the fish-shell project
# This will run the tests when a push to master is detected, and will stop that if the tests fail
# Save this as .git/hooks/pre-push and make it executable
protected_branch='master'
# Git gives us lines like "refs/heads/frombranch SOMESHA1 refs/heads/tobranch SOMESHA1"
# We're only interested in the branches
while read from _ to _; do
if [ "x$to" = "xrefs/heads/$protected_branch" ]; then
isprotected=1
fi
done
if [ "x$isprotected" = x1 ]; then
echo "Running tests before push to master"
make test
RESULT=$?
if [ $RESULT -ne 0 ]; then
echo "Tests failed for a push to master, we can't let you do that" >&2
exit 1
fi
fi
exit 0
```
This will check if the push is to the master branch and, if it is, only allow the push if running `make test` succeeds. In some circumstances it may be advisable to circumvent this check with `git push --no-verify`, but usually that isn't necessary.
To install the hook, place the code in a new file `.git/hooks/pre-push` and make it executable.
### Coverity Scan
We use Coverity's static analysis tool which offers free access to open source projects. While access to the tool itself is restricted, fish-shell organization members should know that they can login [here](https://scan.coverity.com/projects/fish-shell-fish-shell?tab=overview) with their GitHub account. Currently, tests are triggered upon merging the `master` branch into `coverity_scan_master`. Even if you are not a fish developer, you can keep an eye on our statistics there.
## Installing the Required Tools
### Installing the Linting Tools
To install the lint checkers on Mac OS X using Homebrew:
```
brew tap oclint/formulae
brew install oclint
brew install cppcheck
```
To install the lint checkers on Debian-based Linux distributions:
```
sudo apt-get install clang
sudo apt-get install oclint
sudo apt-get install cppcheck
```
### Installing the Reformatting Tools
Mac OS X:
```
brew install clang-format
```
Debian-based:
```
apt-cache search clang-format
```
Above will list all the versions available. Pick the newest one available (3.9 for Ubuntu 16.10 as I write this) and install it:
Fish uses the GNU gettext library to translate messages from English to other languages.
All non-debug messages output for user consumption should be marked for translation. In C++, this requires the use of the `_` (underscore) macro:
```
streams.out.append_format(_(L"%ls: There are no jobs\n"), argv[0]);
```
All messages in fish script must be enclosed in single or double quote characters. They must also be translated via a subcommand. This means that the following are **not** valid:
```
echo (_ hello)
_ "goodbye"
```
Above should be written like this instead:
```
echo (_ "hello")
echo (_ "goodbye")
```
Note that you can use either single or double quotes to enclose the message to be translated. You can also optionally include spaces after the opening parentheses and once again before the closing parentheses.
Creating and updating translations requires the Gettext tools, including `xgettext`, `msgfmt` and `msgmerge`. Translation sources are stored in the `po` directory, named `LANG.po`, where `LANG` is the two letter ISO 639-1 language code of the target language (eg `de` for German).
To create a new translation, for example for German:
* generate a `messages.pot` file by running `build_tools/fish_xgettext.fish` from the source tree
* copy `messages.pot` to `po/LANG.po` ()
To update a translation:
* generate a `messages.pot` file by running `build_tools/fish_xgettext.fish` from the source tree
* update the existing translation by running `msgmerge --update --no-fuzzy-matching po/LANG.po messages.pot`
Many tools are available for editing translation files, including command-line and graphical user interface programs.
Be cautious about blindly updating an existing translation file. Trivial changes to an existing message (eg changing the punctuation) will cause existing translations to be removed, since the tools do literal string matching. Therefore, in general, you need to carefully review any recommended deletions.
Read the [translations wiki](https://github.com/fish-shell/fish-shell/wiki/Translations) for more information.
`formula <https://github.com/jasonmp85/homebrew-iwyu>`__ then install
it:
::
brew tap jasonmp85/iwyu
brew install iwyu
On Ubuntu you can install it via ``apt-get``:
::
sudo apt-get install iwyu
Lint Free Code
--------------
Automated analysis tools like cppcheck and oclint can point out
potential bugs or code that is extremely hard to understand. They also
help ensure the code has a consistent style and that it avoids patterns
that tend to confuse people.
Ultimately we want lint free code. However, at the moment a lot of
cleanup is required to reach that goal. For now simply try to avoid
introducing new lint.
To make linting the code easy there are two make targets: ``lint`` and
``lint-all``. The latter does exactly what the name implies. The former
will lint any modified but not committed ``*.cpp`` files. If there is no
uncommitted work it will lint the files in the most recent commit.
Fish has custom cppcheck rules in the file ``.cppcheck.rule``. These
help catch mistakes such as using ``wcwidth()`` rather than
``fish_wcwidth()``. Please add a new rule if you find similar mistakes
being made.
Fish also depends on ``diff`` and ``expect`` for its tests.
Dealing With Lint Warnings
~~~~~~~~~~~~~~~~~~~~~~~~~~
You are strongly encouraged to address a lint warning by refactoring the
code, changing variable names, or whatever action is implied by the
warning.
Suppressing Lint Warnings
~~~~~~~~~~~~~~~~~~~~~~~~~
Once in a while the lint tools emit a false positive warning. For
example, cppcheck might suggest a memory leak is present when that is
not the case. To suppress that cppcheck warning you should insert a line
like the following immediately prior to the line cppcheck warned about:
::
// cppcheck-suppress memleak // addr not really leaked
The explanatory portion of the suppression comment is optional. For
other types of warnings replace “memleak” with the value inside the
parenthesis (e.g., “nullPointerRedundantCheck”) from a warning like the
following:
::
[src/complete.cpp:1727]: warning (nullPointerRedundantCheck): Either the condition 'cmd_node' is redundant or there is possible null pointer dereference: cmd_node.
Suppressing oclint warnings is more complicated to describe so I’ll
[fish](https://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 macOS, 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](https://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 <https://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 <https://fishshell.com/docs/current/index.html>
You can quickly play with fish right in your browser by clicking the button below:
[](https://rootnroll.com/d/fish-shell/)
## Getting fish
### macOS
fish can be installed:
* using [Homebrew](http://brew.sh/): `brew install fish`
* using [MacPorts](https://www.macports.org/): `sudo port install fish`
* using the [installer from fishshell.com](https://fishshell.com/)
* as a [standalone app from fishshell.com](https://fishshell.com/)
### Packages for Linux
Packages for Debian, Fedora, openSUSE, and Red Hat Enterprise Linux/CentOS are available from the
PPA](https://launchpad.net/~fish-shell/+archive/ubuntu/release-3), and can be installed using the
following commands:
```
sudo apt-add-repository ppa:fish-shell/release-3
sudo apt-get update
sudo apt-get install fish
```
Instructions for other distributions may be found at [fishshell.com](https://fishshell.com).
### Windows
- On Windows 10, fish can be installed under the WSL Windows Subsystem for Linux with `sudo apt install fish` or from source with the instructions below.
- Fish can also be installed on all versions of Windows using [Cygwin](https://cygwin.com/) (from the **Shells** category).
### Building from source
If packages are not available for your platform, GPG-signed tarballs are available from
[fishshell.com](https://fishshell.com/) and [fish-shell on
GitHub](https://github.com/fish-shell/fish-shell/releases). See the *Building* section for instructions.
## Running fish
Once installed, run `fish` from your current shell to try fish out!
### Dependencies
Running fish requires:
* curses or ncurses (preinstalled on most \*nix systems)
* some common \*nix system utilities (currently `mktemp`), in addition to the basic POSIX utilities (`cat`, `cut`, `dirname`, `ls`, `mkdir`, `mkfifo`, `rm`, `sort`, `tee`, `tr`, `uname` and `sed` at least, but the full coreutils plus find, sed and awk is preferred)
* gettext (library and `gettext` command), if compiled with translation support
The following optional features also have specific requirements:
* builtin commands that have the `--help` option or print usage messages require `ul` and either `nroff` or `mandoc` for display
* automated completion generation from manual pages requires Python (2.7+ or 3.3+) and possibly the
`backports.lzma` module for Python 2.7
* the `fish_config` web configuration tool requires Python (2.7+ or 3.3 +) and a web browser
* system clipboard integration (with the default Ctrl-V and Ctrl-X bindings) require either the
`xsel`, `xclip`, `wl-copy`/`wl-paste` or `pbcopy`/`pbpaste` utilities
* full completions for `yarn` and `npm` require the `all-the-package-names` NPM module
### 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. (Substitute `/usr/local/bin/fish` with whatever path fish was installed to, if it differs.) Log out, then log in again for the changes to take effect.
Use the following command if fish isn't already added to `/etc/shells` to permit fish to be your login shell:
echo /usr/local/bin/fish | sudo tee -a /etc/shells
To switch your default shell back, you can run `chsh -s /bin/bash` (substituting `/bin/bash` with `/bin/tcsh` or `/bin/zsh` as appropriate).
## Building
### Dependencies
Compiling fish requires:
* a C++11 compiler (g++ 4.8 or later, or clang 3.3 or later)
* CMake (version 3.2 or later)
* a curses implementation such as ncurses (headers and libraries)
* PCRE2 (headers and libraries) - a copy is included with fish
* gettext (headers and libraries) - optional, for translation support
Sphinx is also optionally required to build the documentation from a cloned git repository.
### Building from source (all platforms) - Makefile generator
To install into `/usr/local`, run:
```bash
mkdir build;cd build
cmake ..
make
sudo make install
```
The install directory can be changed using the `-DCMAKE_INSTALL_PREFIX` parameter for `cmake`.
### Building from source (macOS) - Xcode
```bash
mkdir build;cd build
cmake .. -G Xcode
```
An Xcode project will now be available in the `build` subdirectory. You can open it with Xcode,
or run the following to build and install in `/usr/local`:
```bash
xcodebuild
xcodebuild -scheme install
```
The install directory can be changed using the `-DCMAKE_INSTALL_PREFIX` parameter for `cmake`.
### Help, it didn't build!
If fish reports that it could not find curses, try installing a curses development package and build again.
Questions, comments, rants and raves can be posted to the official fish mailing list at <https://lists.sourceforge.net/lists/listinfo/fish-users> or join us on our [gitter.im channel](https://gitter.im/fish-shell/fish-shell). Or use the [fish tag on Stackoverflow](https://stackoverflow.com/questions/tagged/fish) for questions related to fish script and the [fish tag on Superuser](https://superuser.com/questions/tagged/fish) for all other questions (e.g., customizing colors, changing key bindings).
Found a bug? Have an awesome idea? Please [open an issue](https://github.com/fish-shell/fish-shell/issues/new).
@@ -103,6 +103,31 @@ See the :ref:`fish_opt <cmd-fish_opt>` command for a friendlier but more verbose
In the following examples if a flag is not seen when parsing the arguments then the corresponding _flag_X var(s) will not be set.
Note: Optional arguments
------------------------
An option defined with ``=?`` can take optional arguments. Optional arguments have to be *directly attached* to the option they belong to.
That means you can only call::
cmd --flag=value
# or
cmd -fvalue
but not::
cmd --flag value
# "value" here will be used as a positional argument and "--flag" won't have an argument.
If this weren't the case, using an option without an optional argument would be difficult if you also wanted to use positional arguments.
For example::
grep --color auto
# Here "auto" will be used as the search string, "color" will not have an argument and will fall back to the default
This isn't specific to argparse but common to all things using ``getopt(3)`` (if they have optional arguments at all).
Flag Value Validation
---------------------
@@ -114,7 +139,7 @@ Sometimes you need to validate the option values. For example, that it is a vali
- ``_flag_value`` will be set to the value associated with the flag being processed.
If you do this via a function it should be defined with the ``--no-scope-shadowing`` flag. Otherwise it won't have access to those variables.
These variables are passed to the function as local exported variables.
The script should write any error messages to stdout, not stderr. It should return a status of zero if the flag value is valid otherwise a non-zero status to indicate it is invalid.
``bind``adds a binding for the specified key sequence to the specified command.
``bind``manages bindings.
SEQUENCE is the character sequence to bind to. These should be written as :ref:`fish escape sequences <escapes>`. 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, :kbd:`Alt+w` can be written as ``\ew``. The control character can be written in much the same way using the``\c`` escape, for example :kbd:`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``.
It can add bindings if given a SEQUENCE of characters to bind to. These should be written as :ref:`fish escape sequences <escapes>`. The most important of these are ``\c``for the control key, and``\e`` for escape, and because of historical reasons also the Alt key (sometimes also called "Meta").
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.
For example, :kbd:`Alt`\ +\ :kbd:`W` can be written as``\ew``, and :kbd:`Control`\ +\ :kbd:`X` (^X) can be written as``\cx``. Note that Alt-based key bindings are case sensitive and Control-based keybindings are not. This is a constraint of text-based terminals, not ``fish``.
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.) If used in conjunction with the ``-s`` switch, ``bind`` will silently ignore bindings to named keys that are not found in termcap for the current ``$TERMINAL``, otherwise a warning is emitted.
The generic key binding that matches if no other binding does can be set by specifying a ``SEQUENCE`` of the empty string (that is, ``''`` ). For most key bindings, it makes sense to bind this to the ``self-insert`` function (i.e. ``bind '' self-insert``). 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 inserted.
If the ``-k`` switch is used, the name of a key (such as 'down', 'up' or 'backspace') is used instead of a sequence. The names used are the same as the corresponding curses variables, but without the 'key\_' prefix. (See ``terminfo(5)`` for more information, or use ``bind --key-names`` for a list of all available named keys). Normally this will print an error if the current ``$TERM`` entry doesn't have a given key, unless the ``-s`` switch is given.
``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.
@@ -32,15 +34,17 @@ When ``COMMAND`` is a shellscript command, it is a good practice to put the actu
If a script produces output, it should finish by calling ``commandline -f repaint`` to tell fish that a repaint is in order.
When multiple ``COMMAND``\s are provided, they are all run in the specified order when the key is pressed. Note that special input functions cannot be combined with ordinary shell script commands. The commands must be entirely a sequence of special input functions (from ``bind -f``) or all shell script commands (i.e., valid fish script).
Note that special input functions cannot be combined with ordinary shell script commands. The commands must be entirely a sequence of special input functions (from ``bind -f``) or all shell script commands (i.e., valid fish script).
If no ``SEQUENCE`` is provided, all bindings (or just the bindings in the specified``MODE``) are printed. If ``SEQUENCE`` is provided without``COMMAND``, just the binding matching that sequence is printed.
If no ``SEQUENCE`` is provided, all bindings (or just the bindings in the given``MODE``) are printed. If ``SEQUENCE`` is provided but no``COMMAND``, just the binding matching that sequence is printed.
To save custom keybindings, put the ``bind`` statements into :ref:`config.fish <initialization>`. Alternatively, fish also automatically executes a function called ``fish_user_key_bindings`` if it exists.
Key bindings may use "modes", which mimics Vi's modal input behavior. The default mode is "default", and every bind applies to a single mode. The mode can be viewed/changed with the ``$fish_bind_mode`` variable.
The following parameters are available:
Options
-------
The following options are available:
- ``-k`` or ``--key`` Specify a key name, such as 'left' or 'backspace' instead of a character sequence
@@ -58,7 +62,7 @@ The following parameters are available:
- ``-a`` or ``--all`` See ``--erase`` and ``--key-names``
- ``--preset`` and ``--user`` specify if bind should operate on user or preset bindings. User bindings take precedence over preset bindings when fish looks up mappings. By default, all ``bind`` invocations work on the "user" level except for listing, which will show both levels. All invocations except for inserting new bindings can operate on both levels at the same time. ``--preset`` should only be used in full binding sets (like when working on ``fish_vi_key_bindings``).
- ``--preset`` and ``--user`` specify if bind should operate on user or preset bindings. User bindings take precedence over preset bindings when fish looks up mappings. By default, all ``bind`` invocations work on the "user" level except for listing, which will show both levels. All invocations except for inserting new bindings can operate on both levels at the same time (if both ``--preset`` and ``--user`` are given). ``--preset`` should only be used in full binding sets (like when working on ``fish_vi_key_bindings``).
Special input functions
-----------------------
@@ -160,7 +164,7 @@ The following special input functions are available:
- ``repaint`` reexecutes the prompt functions and redraws the prompt. Multiple successive repaints are coalesced.
- ``repaint-mode`` reexecutes the fish_mode_prompt function and redraws the prompt. This is useful for vi-mode. If no fish_mode_prompt exists, it acts like a normal repaint.
- ``repaint-mode`` reexecutes the :ref:`fish_mode_prompt <cmd-fish_mode_prompt>` and redraws the prompt. This is useful for vi-mode. If no ``fish_mode_prompt`` exists, it acts like a normal repaint.
- ``self-insert``, inserts the matching sequence into the command line
@@ -176,6 +180,8 @@ The following special input functions are available:
- ``up-line``, move up one line
- ``undo`` and ``redo``, revert or redo the most recent edits on the command line
- ``upcase-word``, make the current word uppercase
- ``yank``, insert the latest entry of the killring into the buffer
@@ -185,13 +191,11 @@ The following special input functions are available:
Examples
--------
::
bind \cd 'exit'
Causes ``fish`` to exit when :kbd:`Control+D` is pressed.
Causes ``fish`` to exit when :kbd:`Control`\ +\ :kbd:`D` is pressed.
@@ -208,11 +212,30 @@ Performs a history search when the :kbd:`Page Up` key is pressed.
set -g fish_key_bindings fish_vi_key_bindings
bind -M insert \cc kill-whole-line force-repaint
Turns on Vi key bindings and rebinds :kbd:`Control+C` to clear the input line.
Turns on Vi key bindings and rebinds :kbd:`Control`\ +\ :kbd:`C` to clear the input line.
::
bind \cg 'git diff; commandline -f repaint'
Causes :kbd:`Control`\ +\ :kbd:`G` to launch ``git diff`` and repaint the commandline afterwards.
.._cmd-bind-termlimits:
Terminal Limitations
--------------------
Unix terminals, like the ones fish operates in, are at heart 70s technology. They have some limitations that applications running inside them can't workaround.
For instance, the control key modifies a character by setting the top three bits to 0. This means:
- Many characters + control are indistinguishable from other keys. :kbd:`Control`\ +\ :kbd:`I`*is* tab, :kbd:`Control`\ +\ :kbd:`J`*is* newline (`\n`).
- Control and shift don't work simultaneously
Other keys don't have a direct encoding, and are sent as escape sequences. For example :kbd:`→` (Right) often sends `\e\[C`. These can differ from terminal to terminal, and the mapping is typically available in `terminfo(5)`. Sometimes however a terminal identifies as e.g. `xterm-256color` for compatibility, but then implements xterm's sequences incorrectly.
.._cmd-bind-escape:
Special Case: The escape Character
Special Case: The Escape Character
----------------------------------
The escape key can be used standalone, for example, to switch from insertion mode to normal mode when using Vi keybindings. Escape can also be used as a "meta" key, to indicate the start of an escape sequence, like for function or arrow keys. Custom bindings can also be defined that begin with an escape character.
``cdh`` with no arguments presents a list of :ref:`recently visited directories <directory-history>`. You can then select one of the entries by letter or number. You can also press :kbd:`Tab` to use the completion pager to select an item from the list. If you give it a single argument it is equivalent to ``cd directory``.
Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables which this command manipulates. If you make those universal variables your ``cd`` history is shared among all fish instances.
See Also
--------
- the :ref:`dirh <cmd-dirh>` command to print the directory history
- the :ref:`prevd <cmd-prevd>` command to move backward
- the :ref:`nextd <cmd-nextd>` command to move forward
@@ -37,9 +37,9 @@ The following options change what part of the commandline is printed or updated:
- ``-b`` or ``--current-buffer`` select the entire buffer, including any displayed autosuggestion (default)
- ``-j`` or ``--current-job`` select the current job
- ``-j`` or ``--current-job`` select the current job - a `job` here is one pipeline. It stops at logical operators or terminators (`;`, `&` or newlines).
- ``-p`` or ``--current-process`` select the current process
- ``-p`` or ``--current-process`` select the current process - a `process` here is one simple command. It stops at logical operators, terminators or pipes.
- ``-s`` or ``--current-selection`` selects the current selection
@@ -72,12 +72,18 @@ If the commandline contains
::
>_ echo $fl___ounder >&2 | less; and echo $catfish
>_ echo $flounder >&2 | less; and echo $catfish
(with the cursor on the "o" of "flounder")
Then the following invocations behave like this:
The`echo $flounder >&` is the first process, `less` the second and `and echo $catfish` the third.
`echo $flounder >&2 | less` is the first job, `and echo $catfish` the second.
- ``-u`` and ``--unauthoritative`` no longer do anything and are silently ignored.
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:
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``').
- 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``').
- 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').
- GNU style long options, like ``--colors``. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter (``--quoting-style shell``) or by appending the option with a ``=`` and the value (``--quoting-style=shell``). GNU style long options may be abbreviated so long as the abbreviation is unique (``--h``) is equivalent to ``--help`` if help is the only long option beginning with an 'h').
The options for specifying command name and command path may be used multiple times to define the same completions for multiple commands.
@@ -111,7 +111,7 @@ The short style option ``-o`` for the ``gcc`` command requires that a file follo
complete -c gcc -s o -r
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 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:
``dirh`` prints the current :ref:`directory history <directory-history>`. The current position in the history is highlighted using the color defined in the ``fish_color_history_current`` environment variable.
``dirh`` does not accept any parameters.
Note that the :ref:`cd <cmd-cd>` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables.
See Also
--------
- the :ref:`cdh <cmd-cdh>` command to display a prompt to quickly navigate the history
- the :ref:`prevd <cmd-prevd>` command to move backward
- the :ref:`nextd <cmd-nextd>` command to move forward
@@ -19,7 +19,7 @@ Jobs in the list of jobs are sent a hang-up signal when fish terminates, which u
If no process is specified, the most recently-used job is removed (like :ref:`bg <cmd-bg>` and :ref:`fg <cmd-fg>`). If one or more PIDs are specified, jobs with the specified process IDs are removed from the job list. Invalid jobs are ignored and a warning is printed.
If a job is stopped, it is sent a signal to continue running, and a warning is printed. It is not possible to use the ``bg`` builtin to continue a job once it has been disowned.
If a job is stopped, it is sent a signal to continue running, and a warning is printed. It is not possible to use the :ref:`bg <cmd-bg>` builtin to continue a job once it has been disowned.
``disown`` returns 0 if all specified jobs were disowned successfully, and 1 if any problems were encountered.
``eval`` evaluates the specified parameters as a command. If more than one parameter is specified, all parameters will be joined using a space character as a separator.
If your command does not need access to stdin, consider using ``source`` instead.
If your command does not need access to stdin, consider using :ref:`source <cmd-source>` instead.
If no piping or other compound shell constructs are required, variable-expansion-as-command, as in ``set cmd ls -la; $cmd``, is also an option.
fish is a command-line shell written mainly with interactive use in mind. This page briefly describes the options for invoking fish. The :ref:`full manual <intro>` is available in HTML by using the :ref:`help <cmd-help>` command from inside fish, and in the `fish-doc(1)` man page. The :ref:`tutorial <tutorial>` is available as HTML via ``help tutorial`` or in `fish-tutorial(1)`.
The following options are available:
-``-c`` or ``--command=COMMANDS`` evaluate the specified commands instead of reading from the commandline
-``-C`` or ``--init-command=COMMANDS`` evaluate the specified commands after reading the configuration, before running the command specified by ``-c`` or reading interactive input
-``-d`` or ``--debug=DEBUG_CATEGORIES`` enable debug output and specify a pattern for matching debug categories. See :ref:`Debugging <debugging-fish>` below for details.
-``-o`` or ``--debug-output=DEBUG_FILE`` specify a file path to receive the debug output, including categories and ``fish_trace``. The default is stderr.
-``-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
-``-P`` or ``--private`` enables :ref:`private mode <private-mode>`, so fish will not access old or store new history.
-``--print-rusage-self`` when fish exits, output stats from getrusage
-``--print-debug-categories`` outputs the list of debug categories, and then exits.
-``-v`` or ``--version`` display version and exit
-``-D`` or ``--debug-stack-frames=DEBUG_LEVEL`` specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128.
-``-f`` or ``--features=FEATURES`` enables one or more :ref:`feature flags <featureflags>` (separated by a comma). These are how fish stages changes that might break scripts.
The fish exit status is generally the :ref:`exit status of the last foreground command <variables-status>`.
.._debugging-fish:
Debugging
---------
While fish provides extensive support for :ref:`debugging fish scripts <debugging>`, it is also possible to debug and instrument its internals. Debugging can be enabled by passing the ``--debug`` option. For example, the following command turns on debugging for background IO thread events, in addition to the default categories, i.e. *debug*, *error*, *warning*, and *warning-path*::
> fish --debug=iothread
Available categories are listed by ``fish --print-debug-categories``. The ``--debug`` option accepts a comma-separated list of categories, and supports glob syntax. The following command turns on debugging for *complete*, *history*, *history-file*, and *profile-history*, as well as the default categories::
> fish --debug='complete,*history*'
Debug messages output to stderr by default. Note that if ``fish_trace`` is set, execution tracing also outputs to stderr by default. You can output to a file using the ``--debug-output`` option::
> fish --debug='complete,*history*' --debug-output=/tmp/fish.log --init-command='set fish_trace on'
``fish_add_path`` is a simple way to add more components to fish's $PATH. It does this by adding the components either to $fish_user_paths or directly to $PATH (if the ``--path`` switch is given).
It is (by default) safe to use ``fish_add_path`` in config.fish, or it can be used once, interactively, and the paths will stay in future because of :ref:`universal variables <variables-universal>`. This is a "do what I mean" style command, if you need more control, consider modifying the variable yourself.
Components are normalized by :ref:`realpath <cmd-realpath>`. This means that trailing slashes are ignored and symlinks are resolved, and relative paths are made absolute. If a component already exists, it is not added again and stays in the same place unless the ``--move`` switch is given.
Components are added in the order they are given, and they are prepended to the path unless ``--append`` is given (if $fish_user_paths is used, that means they are last in $fish_user_paths, which is itself prepended to $PATH, so they still stay ahead of the system paths).
If no component is new, the variable ($fish_user_paths or $PATH) is not set again or otherwise modified, so variable handlers are not triggered.
If a component is not an existing directory, ``fish_add_path`` ignores it.
Options
-------
-``-a`` or ``--append`` causes the components to be added to the *end* of the variable
-``-p`` or ``--prepend`` causes the components to be added to the *front* of the variable (this is the default)
-``-g`` or ``--global`` means to use a global $fish_user_paths
-``-U`` or ``--universal`` means to use a universal $fish_user_paths - this is the default if it doesn't already exist
-``-P`` or ``--path`` means to use $PATH directly
-``-m`` or ``--move`` means to move already existing components to the place they would be added - by default they would be left in place and not added again
-``-v`` or ``--verbose`` means to print the :ref:`set <cmd-set>` command used
-``-n`` or ``--dry-run`` means to print the ``set`` command that would be used without executing it
If ``--move`` is used, it may of course lead to the path swapping order, so you should be careful doing that in config.fish.
Example
-------
::
# I just installed mycoolthing and need to add it to the path to use it.
@@ -28,7 +28,7 @@ The following options are available:
- ``--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``.
- ``-d`` or ``--debug=CATEGORY_GLOB`` enables debug output and specifies a glob for matching debug categories (like ``fish -d``). Defaults to empty.
- ``-d`` or ``--debug-level=DEBUG_LEVEL`` enables debug output and specifies a verbosity level. Defaults to 0.
- ``-D`` or ``--debug-stack-frames=DEBUG_LEVEL`` specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128.
``fish_key_reader`` is used to study input received from the terminal and can help with key binds. The program is interactive and works on standard input. Individual characters themselves and their hexadecimal values are displayed.
The tool will write an example ``bind`` command matching the character sequence captured to stdout. If the character sequence matches a special key name (see ``bind --key-names``), both ``bind CHARS ...`` and ``bind -k KEYNAME ...`` usage will be shown. Additional details about the characters received, such as the delay between chars, are written to stderr.
The tool will write an example :ref:`bind <cmd-bind>` command matching the character sequence captured to stdout. If the character sequence matches a special key name (see ``bind --key-names``), both ``bind CHARS ...`` and ``bind -k KEYNAME ...`` usage will be shown. Additional details about the characters received, such as the delay between chars, are written to stderr.
The following options are available:
- ``-c`` or ``--continuous`` begins a session where multiple key sequences can be inspected. By default the program exits after capturing a single key sequence.
- ``-d`` or ``--debug=CATEGORY_GLOB`` enables debug output and specifies a glob for matching debug categories (like ``fish -d``). Defaults to empty.
- ``-D`` or ``--debug-stack-frames=DEBUG_LEVEL`` specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128.
- ``-h`` or ``--help`` prints usage information.
- ``-v`` or ``--version`` prints fish_key_reader's version and exits.
@@ -36,7 +32,7 @@ The delay in milliseconds since the previous character was received is included
``fish_key_reader`` intentionally disables handling of many signals. To terminate ``fish_key_reader`` in ``--continuous`` mode do:
The ``fish_mode_prompt`` function outputs the mode indicator for use in vi-mode.
The default ``fish_mode_prompt`` function will output indicators about the current Vi editor mode displayed to the left of the regular prompt. Define your own function to customize the appearance of the mode indicator. You can also define an empty ``fish_mode_prompt`` function to remove the Vi mode indicators. The ``$fish_bind_mode variable`` can be used to determine the current mode. It
will be one of ``default``, ``insert``, ``replace_one``, or ``visual``.
The default ``fish_mode_prompt`` function will output indicators about the current Vi editor mode displayed to the left of the regular prompt. Define your own function to customize the appearance of the mode indicator. The ``$fish_bind_mode variable`` can be used to determine the current mode. It will be one of ``default``, ``insert``, ``replace_one``, or ``visual``.
fish_mode_prompt will be executed when the vi mode changes. If it produces any output, it is displayed and used. If it does not, the other prompt functions (:ref:`fish_prompt <cmd-fish_prompt>` and :ref:`fish_right_prompt <cmd-fish_right_prompt>`) will be executed as well in case they contain a mode display.
You can also define an empty ``fish_mode_prompt`` function to remove the Vi mode indicators::
function fish_mode_prompt; end
funcsave fish_mode_prompt
``fish_mode_prompt`` will be executed when the vi mode changes. If it produces any output, it is displayed and used. If it does not, the other prompt functions (:ref:`fish_prompt <cmd-fish_prompt>` and :ref:`fish_right_prompt <cmd-fish_right_prompt>`) will be executed as well in case they contain a mode display.
``funced`` provides an interface to edit the definition of the function ``NAME``.
If the ``$VISUAL`` environment variable is set, it will be used as the program to edit the function. If ``$VISUAL`` is unset but ``$EDITOR`` is set, that will be used. Otherwise, a built-in editor will be used. Note that to enter a literal newline using the built-in editor you should press :kbd:`Alt+Enter`. Pressing :kbd:`Enter` signals that you are done editing the function. This does not apply to an external editor like emacs or vim.
If the ``$VISUAL`` environment variable is set, it will be used as the program to edit the function. If ``$VISUAL`` is unset but ``$EDITOR`` is set, that will be used. Otherwise, a built-in editor will be used. Note that to enter a literal newline using the built-in editor you should press :kbd:`Alt`\ +\ :kbd:`Enter`. Pressing :kbd:`Enter` signals that you are done editing the function. This does not apply to an external editor like emacs or vim.
If there is no function called ``NAME`` a new function will be created with the specified name
@@ -24,3 +24,20 @@ If there is no function called ``NAME`` a new function will be created with the
- ``-i`` or ``--interactive`` Force opening the function body in the built-in editor even if ``$VISUAL`` or ``$EDITOR`` is defined.
- ``-s`` or ``--save`` Automatically save the function after successfully editing it.
Example
-------
Say you want to modify your prompt.
Run::
>_ funced fish_prompt
This will open up your editor, allowing you to modify the function. When you're done, save and quit. Fish will reload the function, so you should see the changes right away.
``funcsave`` saves the current definition of a function to a file in the fish configuration directory. This function will be automatically loaded by current and future fish sessions. This can be useful if you have interactively created a new function and wish to save it for later use.
``funcsave`` saves a function to a file in the fish configuration directory. This function will be automatically loaded by current and future fish sessions. This can be useful if you have interactively created a new function and wish to save it for later use.
Note that because fish loads functions on-demand, saved functions will not function as :ref:`event handlers <event>` until they are run or sourced otherwise. To activate an event handler for every new shell, add the function to your :ref:`shell initialization file <initialization>` instead of using ``funcsave``.
This is typically used together with :ref:`funced <cmd-funced>`, which will open the function in your editor and load it in the current seession afterwards.
@@ -39,7 +39,7 @@ The following options are available:
- ``-s`` or ``--on-signal SIGSPEC`` tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP).
- ``-S`` or ``--no-scope-shadowing`` allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents is independent of the calling function.
- ``-S`` or ``--no-scope-shadowing`` allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents are independent of the calling function.
It's important to note that this does not capture referenced variables or the scope at the time of function declaration! At this time, fish does not have any concept of closures, and variable lifetimes are never extended. In other words, by using ``--no-scope-shadowing`` the scope of the function each time it is run is shared with the scope it was *called* from rather than the scope it was *defined* in.
- ``-V`` or ``--inherit-variable NAME`` snapshots the value of the variable ``NAME`` and defines a local variable with that same name and value when the function is defined. This is similar to a closure in other languages like Python but a bit different. Note the word "snapshot" in the first sentence. If you change the value of the variable after defining the function, even if you do so in the same scope (typically another function) the new value will not be used by the function you just created using this option. See the ``function notify`` example below for how this might be used.
@@ -52,13 +52,11 @@ By using one of the event handler switches, a function can be made to run automa
- ``fish_command_not_found``, which is emitted whenever a command lookup failed.
- ``fish_preexec``, which is emitted right before executing an interactive command. The commandline is passed as the first parameter.
- ``fish_preexec``, which is emitted right before executing an interactive command. The commandline is passed as the first parameter. Not emitted if command is empty.
Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines.
- ``fish_posterror``, which is emitted right after executing a command with syntax errors. The commandline is passed as the first parameter.
- ``fish_postexec``, which is emitted right after executing an interactive command. The commandline is passed as the first parameter.
Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines.
- ``fish_postexec``, which is emitted right after executing an interactive command. The commandline is passed as the first parameter. Not emitted if command is empty.
- ``fish_exit`` is emitted right before fish exits.
@@ -29,7 +29,7 @@ The following options are available:
- ``-e`` or ``--erase`` causes the specified functions to be erased. This also means that it is prevented from autoloading.
- ``-D`` or ``--details`` reports the path name where each function is defined or could be autoloaded, ``stdin`` if the function was defined interactively or on the command line or by reading stdin, ``-`` if the function was created via ``source``, and ``n/a`` if the function isn't available. (Functions created via ``alias`` will return ``-``, because ``alias`` uses ``source`` internally.) If the ``--verbose`` option is also specified then five lines are written:
- ``-D`` or ``--details`` reports the path name where the specified function is defined or could be autoloaded, ``stdin`` if the function was defined interactively or on the command line or by reading stdin, ``-`` if the function was created via :ref:`source <cmd-source>`, and ``n/a`` if the function isn't available. (Functions created via :ref:`alias <cmd-alias>` will return ``-``, because ``alias`` uses ``source`` internally.) If the ``--verbose`` option is also specified then five lines are written:
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.
