h/fish-shell
1
Fork 0
mirror of https://github.com/fish-shell/fish-shell.git synced 2026-06-09 03:51:20 -03:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into coverity_scan_master

Browse Source
This commit is contained in:
ridiculousfish
2019-03-05 21:46:40 -08:00
parent ed844fa0ac 60ce10ad84
commit 2ea6b8c128
339 changed files with 11999 additions and 24495 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
.builds/alpine.yml Normal file
View File

@@ -0,0 +1,23 @@
image: alpine/edge
packages:
- cmake
- ninja
- ncurses-dev
- pcre2-dev
- expect
sources:
- https://git.sr.ht/~faho/fish
tasks:
- build: |
cd fish
mkdir build || :
cd build
cmake -G Ninja .. \
-DCMAKE_INSTALL_PREFIX=/usr \
-DCMAKE_INSTALL_DATADIR=share \
-DCMAKE_INSTALL_DOCDIR=share/doc/fish \
-DCMAKE_INSTALL_SYSCONFDIR=/etc
ninja
- test: |
cd fish/build
env SHOW_INTERACTIVE_LOG=1 ninja test

21
.builds/arch.yml Normal file
View File

@@ -0,0 +1,21 @@
image: archlinux
packages:
- cmake
- ninja
- expect
sources:
- https://git.sr.ht/~faho/fish
tasks:
- build: |
cd fish
mkdir build || :
cd build
cmake -G Ninja .. \
-DCMAKE_INSTALL_PREFIX=/usr \
-DCMAKE_INSTALL_DATADIR=share \
-DCMAKE_INSTALL_DOCDIR=share/doc/fish \
-DCMAKE_INSTALL_SYSCONFDIR=/etc
ninja
- test: |
cd fish/build
env SHOW_INTERACTIVE_LOG=1 ninja test

25
.builds/freebsd.yml Normal file
View File

@@ -0,0 +1,25 @@
image: freebsd/latest
packages:
- ncurses
- gcc
- gettext
- expect
- cmake
- gmake
- pcre2
sources:
- https://git.sr.ht/~faho/fish
tasks:
- build: |
cd fish
mkdir build || :
cd build
cmake .. \
-DCMAKE_INSTALL_PREFIX=/usr \
-DCMAKE_INSTALL_DATADIR=share \
-DCMAKE_INSTALL_DOCDIR=share/doc/fish \
-DCMAKE_INSTALL_SYSCONFDIR=/etc
gmake -j2
- test: |
cd fish/build
gmake test SHOW_INTERACTIVE_LOG=1

23
.builds/netbsd.yml Normal file
View File

@@ -0,0 +1,23 @@
image: netbsd/latest
packages:
- ncurses
- gettext
- tcl-expect
- cmake
- gmake
- pcre2
tasks:
- build: |
git -c http.sslVerify=false clone https://git.sr.ht/~faho/fish
cd fish
mkdir build || :
cd build
cmake .. \
-DCMAKE_INSTALL_PREFIX=/usr \
-DCMAKE_INSTALL_DATADIR=share \
-DCMAKE_INSTALL_DOCDIR=share/doc/fish \
-DCMAKE_INSTALL_SYSCONFDIR=/etc
gmake -j2
- test: |
cd fish/build
gmake test SHOW_INTERACTIVE_LOG=1

7
.gitattributes vendored
View File

@@ -6,6 +6,7 @@
# let git show off diff hunk headers, help git diff -L:
# https://git-scm.com/docs/gitattributes
*.cpp diff=cpp
*.h diff=cpp
*.py diff=py
# add a [diff "fish"] to git config with pattern
*.fish diff=fish
@@ -18,12 +19,12 @@
/debian/* export-ignore
/.github export-ignore
/.github/* export-ignore
/.builds export-ignore
/.builds/* export-ignore
/.travis.yml export-ignore
# for linguist; let github identify our project as C++ instead of C due to pcre2
/pcre2-10.32/ linguist-vendored
/pcre2-10.32/* linguist-vendored
/muparser-2.2.5/ linguist-vendored
/muparser-2.2.5/* linguist-vendored
angular.js linguist-vendored
/doc_src/* linguist-documentation
*.fish linguist-language=fish

14
.gitignore vendored
View File

@@ -38,16 +38,6 @@ Desktop.ini
Thumbs.db
ehthumbs.db
# These file names can appear anywhere in the hierarchy. They tend to be OS
# or build system artifacts.
autom4te.cache
aclocal.m4
Makefile
config.h
config.cache
config.h.in
config.status
messages.pot
.directory
.fuse_hidden*
@@ -55,7 +45,6 @@ messages.pot
# Directories that only contain transitory files from building and testing.
/doc/
/obj/
/share/man/
/share/doc/
/test/
@@ -67,8 +56,6 @@ messages.pot
/command_list.txt
/command_list_toc.txt
/compile_commands.json
/confdefs.h
/configure
/doc.h
/fish
/fish.pc
@@ -85,7 +72,6 @@ fish-build-version-witness.txt
# from building and testing.
/doc_src/commands.hdr
/doc_src/index.hdr
/pcre2-*/configure.lineno
/po/*.gmo
/share/__fish_build_paths.fish
/share/pkgconfig

49
.travis.yml
View File

@@ -24,32 +24,6 @@ matrix:
- g++-multilib
env:
- CXXFLAGS="-g -O2 -m32" CFLAGS="-g -m32"
- os: linux
compiler: clang
addons:
apt:
packages:
- expect
- gettext
- libncurses5-dev
- cmake
- libpcre2-dev
env:
- USE_CMAKE="1" # Dummy value, shows up in the Travis UI only
script:
- cmake -DCMAKE_INSTALL_PREFIX=$HOME/prefix . || cat CMakeFiles/CMakeError.log &&
make -j2 &&
make install &&
make test SHOW_INTERACTIVE_LOG=1
coverity_scan:
project:
name: "fish-shell/fish-shell"
description: "The friendly interactive shell"
notification_email:
secure: "lq3AelSInSOqVJI2EZUTrsOrt9ev5c8DHMi7ESyefvv1p+7Qr2gRZmLa+dXLrkPegG+Op9Tykq9zwXRGC4pzC+0OelCKJgqpqkj6LwS8WSamiamAf9ZtPbANwSFMD17f/NTeG/OtBgq6Z87Nur2GEhxmSu3M9IEBOsnOgmCKo84="
build_command_prepend: "mkdir -p build; cd build; cmake -G Ninja -DCMAKE_CXX_COMPILER=clang++ .."
build_command: "ninja"
branch_pattern: coverity_scan_master
- os: linux
compiler: clang
env:
@@ -63,23 +37,26 @@ matrix:
- gettext
- libncurses5-dev
- libpcre2-dev
coverity_scan:
project:
name: "fish-shell/fish-shell"
description: "The friendly interactive shell"
notification_email:
secure: "lq3AelSInSOqVJI2EZUTrsOrt9ev5c8DHMi7ESyefvv1p+7Qr2gRZmLa+dXLrkPegG+Op9Tykq9zwXRGC4pzC+0OelCKJgqpqkj6LwS8WSamiamAf9ZtPbANwSFMD17f/NTeG/OtBgq6Z87Nur2GEhxmSu3M9IEBOsnOgmCKo84="
build_command_prepend: "mkdir -p build; cd build; cmake -G Ninja -DCMAKE_CXX_COMPILER=clang++ .."
build_command: "ninja"
branch_pattern: coverity_scan_master
- os: osx
before_install:
- brew update
- brew install pcre2 # use system PCRE2
- brew outdated xctool || brew upgrade xctool # for xcode... soon.
env:
- CXXFLAGS="-g -O2 -lstdc++"
fast_finish: true
script:
- autoreconf --no-recursive
- ./configure --prefix=$HOME/prefix || cat config.log
- make -j2 &&
make test DESTDIR=$HOME/prefix/ SHOW_INTERACTIVE_LOG=1 &&
make uninstall &&
echo "Checking for leftover files after make uninstall" &&
find $HOME/prefix/ -type f -print -exec false '{}' +
- cmake -DCMAKE_INSTALL_PREFIX=$HOME/prefix . || cat CMakeFiles/CMakeError.log &&
make -j2 &&
make install &&
make test SHOW_INTERACTIVE_LOG=1
notifications:
# Some items are encrypted so that notifications from other repositories

35
BSDmakefile
View File

@@ -1,15 +1,23 @@
# by default bmake will cd into ./obj first
# This is a very basic `make` wrapper around the CMake build toolchain.
#
# Supported arguments:
# PREFIX: sets the installation prefix
# GENERATOR: explicitly specifies the CMake generator to use
# By default, bmake will try to cd into ./obj before anything else. Don't do that.
.OBJDIR: ./
.BEGIN:
# test for cmake, which is the only requirement to be able to run this Makefile
# cmake will perform the remaining dependency tests on its own
@which cmake >/dev/null 2>/dev/null || (echo 'Please install cmake and then re-run the `make` command!' 1>&2 && false)
CMAKE?=cmake
# Use ninja, if it is installed
_GENERATOR!=which ninja 2>/dev/null >/dev/null && echo Ninja || echo "'Unix Makefiles'"
# Before anything else, test for CMake, which is the only requirement to be able to run
# this Makefile CMake will perform the remaining dependency tests on its own.
.BEGIN:
@which $(CMAKE) >/dev/null 2>/dev/null || \
(echo 'Please install CMake and then re-run the `make` command!' 1>&2 && false)
# Prefer to use ninja, if it is installed
_GENERATOR!=which ninja 2>/dev/null >/dev/null && echo Ninja || echo "Unix Makefiles"
GENERATOR?=$(_GENERATOR)
PREFIX?=/usr/local
.if $(GENERATOR) == "Ninja"
BUILDFILE=build/build.ninja
@@ -17,19 +25,20 @@ BUILDFILE=build/build.ninja
BUILDFILE=build/Makefile
.endif
.DEFAULT: build/fish
PREFIX?=/usr/local
build/fish: build/$(BUILDFILE)
cmake --build build
$(CMAKE) --build build
build:
mkdir -p build
build/$(BUILDFILE): build
cd build; cmake .. -G $(GENERATOR) -DCMAKE_INSTALL_PREFIX=$(PREFIX) -DCMAKE_EXPORT_COMPILE_COMMANDS=1
cd build; $(CMAKE) .. -G "$(GENERATOR)" -DCMAKE_INSTALL_PREFIX="$(PREFIX)" -DCMAKE_EXPORT_COMPILE_COMMANDS=1
.PHONY: install
install: build/fish
cmake --build build --target install
$(CMAKE) --build build --target install
.PHONY: clean
clean:
@@ -37,7 +46,7 @@ clean:
.PHONY: test
test: build/fish
cmake --build build --target test
$(CMAKE) --build build --target test
.PHONY: run
run: build/fish

25
CHANGELOG.md
View File

@@ -4,6 +4,9 @@
- The vcs-prompt functions have been renamed to names without double-underscore, so __fish_git_prompt is now fish_git_prompt, __fish_vcs_prompt is now fish_vcs_prompt, __fish_hg_prompt is now fish_hg_prompt and __fish_svn_prompt is now fish_svn_prompt. Shims at the old names have been added, and the variables have kept their old names (#5586).
## Notable fixes and improvements
- Add `$pipestatus` support
- `string split0` now returns 0 if it split something (#5701).
### Syntax changes and new commands
- None yet.
@@ -17,6 +20,28 @@
- New color options for the pager have been added (#5524).
- The default escape delay (to differentiate between the escape key and an alt-combination) has been reduced to 30ms, down from 300ms for the default mode and 100ms for vi-mode (#3904).
- In the interest of consistency, `builtin -q` and `command -q` can now be used to query if a builtin or command exists (#5631).
- The `path_helper` on macOS now only runs in login shells, matching the bash implementation.
- `math` now accepts `--scale=max` for the maximum scale (#5579).
- The `forward-bigword` binding now interacts correctly with autosuggestions (#5336)
- Added completions for
- `cf`
- `bosh`
### For distributors and developers
- The autotools-based build system and legacy Xcode build systems have been removed, leaving only the CMake build system. All distributors and developers must migrate to the CMake build.
---
# fish 3.0.2 (released February 19, 2019)
This release of fish fixes an issue discovered in fish 3.0.1.
### Fixes and improvements
- The PWD environment variable is now ignored if it does not resolve to the true working directory, fixing strange behaviour in terminals started by editors and IDEs (#5647).
If you are upgrading from version 2.7.1 or before, please also review the release notes for 3.0.1,
3.0.0 and 3.0b1 (included below).
---

32
CMakeLists.txt
View File

@@ -56,6 +56,14 @@ ELSE()
SET(FISH_IN_TREE_BUILD FALSE)
ENDIF()
# NetBSD does weird things with finding libraries,
# making the tests fail by failing to find pcre.
#
# Keep the rpath used to build.
IF(CMAKE_SYSTEM_NAME STREQUAL NetBSD)
SET(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
ENDIF()
# All objects that the system needs to build fish, except fish.cpp
SET(FISH_SRCS
src/autoload.cpp src/builtin.cpp src/builtin_bg.cpp src/builtin_bind.cpp
@@ -80,7 +88,7 @@ SET(FISH_SRCS
src/postfork.cpp src/proc.cpp src/reader.cpp src/sanity.cpp src/screen.cpp
src/signal.cpp src/tinyexpr.cpp src/tnode.cpp src/tokenizer.cpp src/utf8.cpp src/util.cpp
src/wcstringutil.cpp src/wgetopt.cpp src/wildcard.cpp src/wutil.cpp
src/future_feature_flags.cpp src/redirection.cpp
src/future_feature_flags.cpp src/redirection.cpp src/topic_monitor.cpp
)
# Header files are just globbed.
@@ -121,11 +129,14 @@ SET_SOURCE_FILES_PROPERTIES(src/fish_version.cpp
OPTION(INTERNAL_WCWIDTH "use fallback wcwidth" ON)
IF(INTERNAL_WCWIDTH)
add_definitions(-DHAVE_BROKEN_WCWIDTH=1)
ADD_DEFINITIONS(-DHAVE_BROKEN_WCWIDTH=1)
ELSE()
add_definitions(-DHAVE_BROKEN_WCWIDTH=0)
ADD_DEFINITIONS(-DHAVE_BROKEN_WCWIDTH=0)
ENDIF()
# Enable thread-safe errno on Solaris (#5611)
ADD_DEFINITIONS(-D_REENTRANT)
# Set up PCRE2
INCLUDE(cmake/PCRE2.cmake)
@@ -167,5 +178,20 @@ INCLUDE(cmake/Install.cmake)
# Mac app.
INCLUDE(cmake/MacApp.cmake)
# Lint targets
# This could be implemented as target properties, but the script has the useful feature of only
# checking the currently-staged commands
# The generator expressions below rebuild the command line for the fishlib targets
# CMake does not support the "iquote" flag - https://gitlab.kitware.com/cmake/cmake/issues/15491
SET(LINT_ARGS "-D$<JOIN:$<TARGET_PROPERTY:fishlib,COMPILE_DEFINITIONS>, -D>" "-I$<JOIN:$<TARGET_PROPERTY:fishlib,INCLUDE_DIRECTORIES>, -I>")
ADD_CUSTOM_TARGET(lint
COMMAND build_tools/lint.fish -- ${LINT_ARGS}
WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
)
ADD_CUSTOM_TARGET(lint-all
COMMAND build_tools/lint.fish --all -- ${LINT_ARGS}
WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
)
INCLUDE(FeatureSummary)
FEATURE_SUMMARY(WHAT ALL)

25
CONTRIBUTING.md
View File

@@ -69,7 +69,7 @@ Suppressing oclint warnings is more complicated to describe so I'll refer you to
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
```
make style
build_tools/style.fish
```
before committing your change. That will run `git-clang-format` to rewrite only the lines you're modifying.
@@ -79,7 +79,7 @@ If you've already committed your changes that's okay since it will then check th
If you want to check the style of the entire code base run
```
make style-all
build_tools/style.fish --all
```
That command will refuse to restyle any files if you have uncommitted changes.
@@ -165,9 +165,24 @@ However, as I write this there are no places in the code where we use this and I
1. Indent with spaces, not tabs and use four spaces per indent.
1. Comments should always use the C++ style; i.e., each line of the comment should begin with a `//` and should be limited to 100 characters. Comments that do not begin a line should be separated from the previous text by two spaces.
1. Comments that document the purpose of a function or class should begin with three slashes, `///`, so that OS X Xcode (and possibly other IDEs) will extract the comment and show it in the "Quick Help" window when the cursor is on the symbol.
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

5
Dockerfile
View File

@@ -2,7 +2,7 @@ FROM centos:latest
# Build dependency
RUN yum update -y &&\
yum install -y autoconf automake clang gcc-c++ make ncurses-devel &&\
yum install -y clang cmake gcc-c++ make ncurses-devel &&\
yum clean all
# Test dependency
@@ -12,8 +12,7 @@ ADD . /src
WORKDIR /src
# Build fish
RUN autoreconf &&\
./configure &&\
RUN cmake . &&\
make &&\
make install

2358
Doxyfile
View File

File diff suppressed because it is too large Load Diff

2357
Doxyfile.help
View File

File diff suppressed because it is too large Load Diff

2357
Doxyfile.user
View File

File diff suppressed because it is too large Load Diff

1311
Makefile.in
View File

File diff suppressed because it is too large Load Diff

20
README.md
View File

@@ -101,16 +101,14 @@ To switch your default shell back, you can run `chsh -s /bin/bash` (substituting
Compiling fish requires:
* a C++11 compiler (g++ 4.8 or later, or clang 3.3 or later)
* any of CMake, GNU Make, or (on macOS only) Xcode
* 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
Additionally, if compiling fish with GNU Make from git (that is, not from an officially released tarball), `autoconf` 2.60+ and `automake` 1.13+ are required. Doxygen (1.8.7 or later) is also optionally required to build the documentation from a cloned git repository.
Doxygen (1.8.7 or later) is also optionally required to build the documentation from a cloned git repository.
### Building from source (all platforms)
#### Using CMake (preferred)
### Building from source (all platforms) - Makefile generator
```bash
mkdir build; cd build
@@ -119,22 +117,22 @@ make
sudo make install
```
#### Using autotools
### Building from source (macOS) - Xcode
```bash
autoreconf --no-recursive #if building from Git
./configure
make
sudo make install
mkdir build; cd build
cmake .. -G Xcode
```
An Xcode project will now be available in the `build` subdirectory.
### Help, it didn't build!
If fish reports that it could not find curses, try installing a curses development package and build again.
On Debian or Ubuntu you want:
sudo apt-get install build-essential ncurses-dev libncurses5-dev gettext autoconf
sudo apt-get install build-essential cmake ncurses-dev libncurses5-dev libpcre2-dev gettext
On RedHat, CentOS, or Amazon EC2:

20
build_tools/build_commands_hdr.sh
View File

@@ -1,20 +0,0 @@
#!/bin/sh
# Builds the commands.hdr file.
# Usage: build_commands_hdr.sh ${HELP_SRC} < commands_hdr.in > commands.hdr
rm -f command_list.tmp command_list_toc.tmp
for i in `printf "%s\n" $@ | LC_ALL=C.UTF-8 sort`; do
echo "<hr>" >>command_list.tmp;
cat $i >>command_list.tmp;
echo >>command_list.tmp;
echo >>command_list.tmp;
NAME=`basename $i .txt`;
echo '- <a href="#'$NAME'">'$NAME'</a>' >> command_list_toc.tmp;
echo "Back to <a href='index.html#toc-commands'>command index</a>". >>command_list.tmp;
done
mv command_list.tmp command_list.txt
mv command_list_toc.tmp command_list_toc.txt
/usr/bin/env awk '{if ($0 ~ /@command_list_toc@/) { system("cat command_list_toc.txt"); }
else if ($0 ~ /@command_list@/){ system("cat command_list.txt");}
else{ print $0;}}'

163
build_tools/build_documentation.sh
View File

@@ -1,163 +0,0 @@
#!/bin/sh
# This script is run as part of the build process
if test $# -eq 0
then
# Use fish's defaults
DOXYFILE=Doxyfile.help
INPUTDIR=doc_src
OUTPUTDIR=share
echo "Using defaults: $0 ${DOXYFILE} ${INPUTDIR} ${OUTPUTDIR}"
elif test $# -eq 3
then
DOXYFILE="$1"
INPUTDIR="$2"
OUTPUTDIR="$3"
else
echo "Usage: $0 doxygen_file input_directory output_directory"
exit 1
fi
# Determine which man pages we don't want to generate.
# on OS X, don't make a man page for open, since we defeat fish's open function on OS X.
# This is also done in the Makefile, but the Xcode build doesn't use that
CONDEMNED_PAGES=
if test `uname` = 'Darwin'; then
CONDEMNED_PAGES="$CONDEMNED_PAGES open.1"
fi
# Helper function to turn a relative path into an absolute path
resolve_path()
{
D=`command dirname "$1"`
B=`command basename "$1"`
echo "`cd \"$D\" 2>/dev/null && pwd || echo \"$D\"`/$B"
}
# Expand relative paths
DOXYFILE=`resolve_path "$DOXYFILE"`
INPUTDIR=`resolve_path "$INPUTDIR"`
INPUTFILTER=`resolve_path "$INPUT_FILTER"`
OUTPUTDIR=`resolve_path "$OUTPUTDIR"`
echo " doxygen file: $DOXYFILE"
echo " input directory: $INPUTDIR"
echo " input filter: $INPUTFILTER"
echo " output directory: $OUTPUTDIR"
echo " skipping: $CONDEMNED_PAGES"
#Until now the makefile likely has been affecting our output, reset for upcoming warnings
tput sgr0
# Make sure INPUTDIR is found
if test ! -d "$INPUTDIR"; then
echo >&2 "Could not find input directory '${INPUTDIR}'"
exit 1
fi
# Make sure doxygen is found
DOXYGENPATH=`command -v doxygen`
if test -z "$DOXYGENPATH" ; then
for i in /usr/local/bin/doxygen /opt/bin/doxygen /Applications/Doxygen.app/Contents/Resources/doxygen ~/Applications/Doxygen.app/Contents/Resources/doxygen ; do
if test -f "$i"; then
DOXYGENPATH="$i"
break
fi
done
fi
if test -z "$DOXYGENPATH"; then
echo >&2 "doxygen is not installed, so documentation will not be built."
exit 0
fi
# Check we have the lexicon filter
if test -z "$INPUT_FILTER"; then
echo >&2 "Lexicon filter is not available. Continuing without."
INPUTFILTER=''
fi
# Determine where our output should go
if ! mkdir -p "${OUTPUTDIR}" ; then
echo "Could not create output directory '${OUTPUTDIR}'"
fi
# Make a temporary directory
TMPLOC=`mktemp -d -t fish_doc_build_XXXXXX` || { echo >&2 "Could not build documentation because mktemp failed"; exit 1; }
# Copy stuff to the temp directory
for i in "$INPUTDIR"/*.txt; do
BASENAME=`basename $i .txt`
INPUTFILE=$TMPLOC/$BASENAME.doxygen
echo "/** \\page" $BASENAME > $INPUTFILE
cat $i | sed "s/\\\section $BASENAME $BASENAME/\\\section $BASENAME-man $BASENAME/" >> $INPUTFILE
echo "*/" >> $INPUTFILE
done
# Make some extra stuff to pass to doxygen
# Input is kept as . because we cd to the input directory beforehand
# This prevents doxygen from generating "documentation" for intermediate directories
PROJECT_NUMBER=$(echo "$FISH_BUILD_VERSION" | env sed "s/-[a-z0-9-]*//")
echo "PROJECT_NUMBER: $FISH_BUILD_VERSION"
DOXYPARAMS=$(cat <<EOF
PROJECT_NUMBER=${PROJECT_NUMBER}
INPUT_FILTER=$INPUTFILTER
INPUT=.
OUTPUT_DIRECTORY=$OUTPUTDIR
QUIET=YES
EOF
);
# echo "$DOXYPARAMS"
# Clear out the output directory first
find "${OUTPUTDIR}" -name "*.1" -delete
# Run doxygen
cd "$TMPLOC"
(cat "${DOXYFILE}" ; echo "$DOXYPARAMS";) | "$DOXYGENPATH" -
# Remember errors
RESULT=$?
cd "${OUTPUTDIR}/man/man1/"
if test "$RESULT" = 0 ; then
# Postprocess the files
for i in "$INPUTDIR"/*.txt; do
# This command turns the following weirdness from Doxygen:
# abbr \-
# .SH "abbr - manage fish abbreviations"
# into
# \fBabbr\fP - manage fish abbreviations
# It would be nice to use -i here for edit in place, but that is not portable
CMD_NAME=`basename "$i" .txt`;
sed -E < ${CMD_NAME}.1 > ${CMD_NAME}.1.tmp \
-e "/^.SH NAME/{
N; N
s/${CMD_NAME} \\\\- \n.SH \"${CMD_NAME} (- .*)\"/\\\fB${CMD_NAME}\\\fP \1/g
}"
mv "${CMD_NAME}.1.tmp" "${CMD_NAME}.1"
done
# Erase condemned pages
rm -f $CONDEMNED_PAGES
fi
# Destroy TMPLOC
if test "$RESULT" -ne 0; then
echo "Cleaning up '$TMPLOC'"
fi
rm -Rf "$TMPLOC"
if test "$RESULT" -ne 0; then
tput smso 2> /dev/null || true
echo "Doxygen failed creating manpages. See the output log for details."
tput sgr0 2> /dev/null || true
else
tput bold 2> /dev/null || true
echo Built manpages
tput sgr0 2> /dev/null || true
fi
exit $RESULT

5
build_tools/build_index_hdr.sh
View File

@@ -1,5 +0,0 @@
#!/bin/sh
TOC_TXT=$1
env awk "{if (\$0 ~ /@toc@/){ system(\"cat ${TOC_TXT}\");} else{ print \$0;}}"

51
build_tools/build_lexicon_filter.sh
View File

@@ -1,51 +0,0 @@
#!/bin/sh
# Builds the lexicon filter
# Usage: build_lexicon_filter.sh FUNCTIONS_DIR COMPLETIONS_DIR lexicon_filter.in [SED_BINARY] > lexicon_filter
set -e
# To enable the lexicon filter, we first need to be aware of what fish
# considers to be a command, function, or external binary. We use
# command_list_toc.txt for the base commands. Scan the share/functions
# directory for other functions, some of which are mentioned in the docs, and
# use /share/completions to find a good selection of binaries. Additionally,
# colour defaults from __fish_config_interactive to set the docs colours when
# used in a 'cli' style context.
rm -f lexicon.tmp lexicon_catalog.tmp lexicon_catalog.txt lexicon.txt
FUNCTIONS_DIR=${1}
FUNCTIONS_DIR_FILES=${1}/*.fish
COMPLETIONS_DIR_FILES=${2}/*.fish
LEXICON_FILTER_IN=${3}
SED=${4:-$(command -v sed)}
# Scan sources for commands/functions/binaries/colours. If GNU sed was portable, this could be much smarter.
$SED <command_list_toc.txt >>lexicon.tmp -n \
-e "s|^.*>\([a-z][a-z_]*\)</a>|'\1'|w lexicon_catalog.tmp" \
-e "s|'\(.*\)'|bltn \1|p"; mv lexicon_catalog.tmp lexicon_catalog.txt
printf "%s\n" ${COMPLETIONS_DIR_FILES} | $SED -n \
-e "s|[^ ]*/\([a-z][a-z_-]*\).fish|'\1'|p" | grep -F -vx -f lexicon_catalog.txt | $SED >>lexicon.tmp -n \
-e 'w lexicon_catalog.tmp' \
-e "s|'\(.*\)'|cmnd \1|p"; cat lexicon_catalog.tmp >> lexicon_catalog.txt;
printf "%s\n" ${FUNCTIONS_DIR_FILES} | $SED -n \
-e "s|[^ ]*/\([a-z][a-z_-]*\).fish|'\1'|p" | grep -F -vx -f lexicon_catalog.txt | $SED >>lexicon.tmp -n \
-e 'w lexicon_catalog.tmp' \
-e "s|'\(.*\)'|func \1|p";
$SED < ${FUNCTIONS_DIR}/__fish_config_interactive.fish >>lexicon.tmp -n \
-e '/set_default/s/.*\(fish_[a-z][a-z_]*\).*$$/clrv \1/p'; \
$SED < ${LEXICON_FILTER_IN} >>lexicon.tmp -n \
-e '/^#.!#/s/^#.!# \(.... [a-z][a-z_]*\)/\1/p';
mv lexicon.tmp lexicon.txt; rm -f lexicon_catalog.tmp lexicon_catalog.txt;
# Copy the filter to stdout. We're going to append sed commands to it after.
$SED -e 's|@sed@|'$SED'|' < ${LEXICON_FILTER_IN}
# Scan through the lexicon, transforming each line to something useful to Doxygen.
if echo x | $SED "/[[:<:]]x/d" 2>/dev/null; then
WORDBL='[[:<:]]'; WORDBR='[[:>:]]';
else
WORDBL='\\<'; WORDBR='\\>';
fi;
$SED < lexicon.txt -n -e "s|^\([a-z][a-z][a-z][a-z]\) \([a-z_-]*\)$|s,$WORDBL\2$WORDBR,@\1{\2},g|p" -e '$G;s/.*\n/b tidy/p';

17
build_tools/build_toc_txt.sh
View File

@@ -1,17 +0,0 @@
#!/bin/sh
# Usage: build_toc_txt.sh $(HDR_FILES:index.hdr=index.hdr.in) > toc.txt
# Ugly hack to set the toc initial title for the main page
echo "- <a href=\"index.html\" id=\"toc-index\">fish shell documentation - ${FISH_BUILD_VERSION}</a>" > toc.txt
# The first sed command captures the page name, followed by the description
# The second sed command captures the command name \1 and the description \2, but only up to a dash
# This is to reduce the size of the TOC in the command listing on the main page
for i in $@; do
NAME=`basename $i .hdr`
NAME=`basename $NAME .hdr.in`
env sed <$i >>toc.txt -n \
-e 's,.*\\page *\([^ ]*\) *\(.*\)$,- <a href="'$NAME'.html" id="toc-'$NAME'">\2</a>,p' \
-e 's,.*\\section *\([^ ]*\) *\(.*\) - .*$, - <a href="'$NAME'.html#\1">\2</a>,p' \
-e 's,.*\\section *\([^ ]*\) *\(.*\)$, - <a href="'$NAME'.html#\1">\2</a>,p'
done

16
build_tools/build_user_doc.sh
View File

@@ -1,16 +0,0 @@
#!/bin/sh
# Usage: Doxyfile.user lexicon_filter
DOXYFILE=$1
LEXICON_FILTER=$2
(cat "${DOXYFILE}" ;\
echo INPUT_FILTER="${LEXICON_FILTER}"; \
echo PROJECT_NUMBER=${FISH_BUILD_VERSION} \
| /usr/bin/env sed "s/-[a-z0-9-]*//") \
| doxygen - && touch user_doc
(cd ./user_doc/html/ && \
rm -f bc_s.png bdwn.png closed.png doc.png folder*.png ftv2*.png \
nav*.png open.png splitbar.png sync_*.png tab*.* doxygen.* \
dynsections.js jquery.js pages.html)

12
build_tools/lint.fish
View File

@@ -14,18 +14,6 @@ set kernel_name (uname -s)
set machine_type (uname -m)
argparse a/all -- $argv
set -q argv[1]; and set -gx CXX $argv[1]
set -e argv[1]
if test $kernel_name = Linux
# This is an awful hack. However, the include-what-you-use program spews lots of errors like
# /usr/include/unistd.h:226:10: fatal error: 'stddef.h' file not found
# if we don't explicitly tell it where to find the system headers on Linux. See
# http://stackoverflow.com/questions/19642590/libtooling-cant-find-stddef-h-nor-other-headers/
set -l sys_includes ($CXX -v -c src/builtin.cpp 2>&1 | \
sed -n -e '/^#include <...> search/,/^End of search list/s/^ *//p')[2..-2]
set -x CPLUS_INCLUDE_PATH (string join ':' $sys_includes)
end
# We only want -D and -I options to be passed thru to cppcheck.
for arg in $argv

3
build_tools/make_pkg.sh
View File

@@ -5,6 +5,9 @@
VERSION=`git describe --always --dirty 2>/dev/null`
if test -z "$VERSION" ; then
echo "Could not get version from git"
if test -f version; then
VERSION=`cat version`
fi
fi
echo "Version is $VERSION"

28
build_tools/make_tarball.sh
View File

@@ -14,8 +14,7 @@ set -e
# but to get the documentation in, we need to make a symlink called "fish-VERSION"
# and tar from that, so that the documentation gets the right prefix
# We need GNU tar as that supports the --mtime option
# BSD tar supports --mtree but keeping them in sync sounds too hard
# We need GNU tar as that supports the --mtime and --transform options
TAR=notfound
for try in tar gtar gnutar; do
if $try -Pcf /dev/null --mtime now /dev/null >/dev/null 2>&1; then
@@ -48,26 +47,21 @@ rm -f "$path" "$path".gz
# git starts the archive
git archive --format=tar --prefix="$prefix"/ HEAD > "$path"
# tarball out the documentation, generate a configure script and version file
autoreconf --no-recursive
./configure --with-doxygen
make doc share/man
echo $VERSION > version
# tarball out the documentation, generate a version file
PREFIX_TMPDIR=`mktemp -d`
cd $PREFIX_TMPDIR
echo $VERSION > version
cmake $wd
make doc
ln -s "$wd" "$prefix"
TAR_APPEND="$TAR --append --file=$path --mtime=now --owner=0 --group=0 --mode=g+w,a+rX"
$TAR_APPEND --no-recursion "$prefix"/user_doc
$TAR_APPEND "$prefix"/user_doc/html "$prefix"/share/man
$TAR_APPEND "$prefix"/version
$TAR_APPEND "$prefix"/configure "$prefix"/config.h.in
rm "$prefix"/version
unlink "$prefix"
TAR_APPEND="$TAR --append --file=$path --mtime=now --owner=0 --group=0 \
--mode=g+w,a+rX --transform s/^/$prefix\//"
$TAR_APPEND --no-recursion user_doc
$TAR_APPEND user_doc/html user_doc/man
$TAR_APPEND version
cd -
rmdir $PREFIX_TMPDIR
rm -r "$PREFIX_TMPDIR"
# gzip it
gzip "$path"

3
build_tools/style.fish
View File

@@ -1,8 +1,5 @@
#!/usr/bin/env fish
#
# This is meant to be run by "make style" or "make style-all". It is not meant to
# be run directly from a shell prompt although it can be.
#
# This runs C++ files and fish scripts (*.fish) through their respective code
# formatting programs.
#

159
cmake/Docs.cmake
View File

@@ -1,19 +1,49 @@
FIND_PACKAGE(Doxygen 1.8.7)
FIND_PROGRAM(SPHINX_EXECUTABLE NAMES sphinx-build
HINTS
$ENV{SPHINX_DIR}
PATH_SUFFIXES bin
DOC "Sphinx documentation generator")
INCLUDE(FeatureSummary)
IF(DOXYGEN_FOUND)
OPTION(BUILD_DOCS "build documentation (requires Doxygen)" ON)
ELSE(DOXYGEN_FOUND)
OPTION(BUILD_DOCS "build documentation (requires Doxygen)" OFF)
ENDIF(DOXYGEN_FOUND)
SET(SPHINX_SRC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/sphinx_doc_src")
SET(SPHINX_ROOT_DIR "${CMAKE_CURRENT_BINARY_DIR}/user_doc")
SET(SPHINX_BUILD_DIR "${SPHINX_ROOT_DIR}/build")
SET(SPHINX_CACHE_DIR "${SPHINX_ROOT_DIR}/doctrees")
SET(SPHINX_HTML_DIR "${SPHINX_ROOT_DIR}/html")
SET(SPHINX_MANPAGE_DIR "${SPHINX_ROOT_DIR}/man")
IF(BUILD_DOCS AND NOT DOXYGEN_FOUND)
MESSAGE(FATAL_ERROR "build documentation selected, but Doxygen could not be found")
ADD_CUSTOM_TARGET(sphinx-docs
${SPHINX_EXECUTABLE}
-q -b html
-c "${SPHINX_SRC_DIR}"
-d "${SPHINX_CACHE_DIR}"
"${SPHINX_SRC_DIR}"
"${SPHINX_HTML_DIR}"
COMMENT "Building HTML documentation with Sphinx")
ADD_CUSTOM_TARGET(sphinx-manpages
${SPHINX_EXECUTABLE}
-q -b man
-c "${SPHINX_SRC_DIR}"
-d "${SPHINX_CACHE_DIR}"
"${SPHINX_SRC_DIR}"
# TODO: This only works if we only have section 1 manpages.
"${SPHINX_MANPAGE_DIR}/man1"
COMMENT "Building man pages with Sphinx")
IF(SPHINX_EXECUTABLE)
OPTION(BUILD_DOCS "build documentation (requires Sphinx)" ON)
ELSE(SPHINX_EXECUTABLE)
OPTION(BUILD_DOCS "build documentation (requires Sphinx)" OFF)
ENDIF(SPHINX_EXECUTABLE)
IF(BUILD_DOCS AND NOT SPHINX_EXECUTABLE)
MESSAGE(FATAL_ERROR "build documentation selected, but sphinx-build could not be found")
ENDIF()
IF(IS_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/user_doc/html
AND IS_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/share/man/man1)
AND IS_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/user_doc/man)
SET(HAVE_PREBUILT_DOCS TRUE)
ELSE()
SET(HAVE_PREBUILT_DOCS FALSE)
@@ -28,121 +58,18 @@ ENDIF()
ADD_FEATURE_INFO(Documentation INSTALL_DOCS "user manual and documentation")
IF(BUILD_DOCS)
# Files in ./share/completions/
FILE(GLOB COMPLETIONS_DIR_FILES share/completions/*.fish)
# Files in ./share/functions/
FILE(GLOB FUNCTIONS_DIR_FILES share/functions/*.fish)
# Files in doc_src
FILE(GLOB DOC_SRC_FILES doc_src/*)
# .txt files in doc_src
FILE(GLOB HELP_SRC doc_src/*.txt)
# These files are the source files, they contain a few @FOO@-style substitutions.
# Note that this order defines the order that they appear in the documentation.
SET(HDR_FILES_SRC doc_src/index.hdr.in doc_src/tutorial.hdr doc_src/design.hdr
doc_src/license.hdr doc_src/commands.hdr.in doc_src/faq.hdr)
# These are the generated result files.
STRING(REPLACE ".in" "" HDR_FILES "${HDR_FILES_SRC}")
# Header files except for index.hdr
SET(HDR_FILES_NO_INDEX ${HDR_FILES})
LIST(REMOVE_ITEM HDR_FILES_NO_INDEX doc_src/index.hdr)
# Copy doc_src files
FILE(COPY ${DOC_SRC_FILES} DESTINATION doc_src)
# Build lexicon_filter.
ADD_CUSTOM_COMMAND(OUTPUT lexicon_filter
COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/build_tools/build_lexicon_filter.sh
${CMAKE_CURRENT_SOURCE_DIR}/share/functions/
${CMAKE_CURRENT_SOURCE_DIR}/share/completions/
${CMAKE_CURRENT_SOURCE_DIR}/lexicon_filter.in
${SED}
> ${CMAKE_CURRENT_BINARY_DIR}/lexicon_filter
&& chmod a+x ${CMAKE_CURRENT_BINARY_DIR}/lexicon_filter
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS ${FUNCTIONS_DIR_FILES} ${COMPLETIONS_DIR_FILES}
doc_src/commands.hdr ${CMAKE_CURRENT_SOURCE_DIR}/lexicon_filter.in
share/functions/__fish_config_interactive.fish
build_tools/build_lexicon_filter.sh command_list_toc.txt)
# Other targets should depend on this target, otherwise the lexicon
# filter can be built twice.
ADD_CUSTOM_TARGET(build_lexicon_filter DEPENDS lexicon_filter)
#
# commands.hdr collects documentation on all commands, functions and
# builtins
#
FILE(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doc_src)
ADD_CUSTOM_COMMAND(OUTPUT doc_src/commands.hdr command_list_toc.txt
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/build_tools/build_commands_hdr.sh ${HELP_SRC}
< doc_src/commands.hdr.in
> ${CMAKE_CURRENT_BINARY_DIR}/doc_src/commands.hdr
DEPENDS ${HELP_SRC}
${CMAKE_CURRENT_SOURCE_DIR}/doc_src/commands.hdr.in
${CMAKE_CURRENT_SOURCE_DIR}/build_tools/build_commands_hdr.sh)
# doc.h is a compilation of the various snippets of text used both for
# the user documentation and for internal help functions into a single
# file that can be parsed by Doxygen to generate the user
# documentation.
ADD_CUSTOM_COMMAND(OUTPUT doc.h
COMMAND cat ${HDR_FILES} > ${CMAKE_CURRENT_BINARY_DIR}/doc.h
DEPENDS ${HDR_FILES})
# toc.txt: $(HDR_FILES:index.hdr=index.hdr.in) build_tools/build_toc_txt.sh | show-SED
# FISH_BUILD_VERSION=${FISH_BUILD_VERSION} build_tools/build_toc_txt.sh \
# $(HDR_FILES:index.hdr=index.hdr.in) > toc.txt
# Note we would like to add doc_src/index.hdr.in as a dependency but CMake replaces this with
# doc_src/index.hdr; CMake bug?
ADD_CUSTOM_COMMAND(OUTPUT toc.txt
COMMAND env `cat ${FBVF} | tr -d '\"'` ${CMAKE_CURRENT_SOURCE_DIR}/build_tools/build_toc_txt.sh
doc_src/index.hdr.in ${HDR_FILES_NO_INDEX}
> ${CMAKE_CURRENT_BINARY_DIR}/toc.txt
DEPENDS ${CFBVF} ${HDR_FILES_NO_INDEX})
# doc_src/index.hdr: toc.txt doc_src/index.hdr.in | show-AWK
# @echo " AWK CAT $(em)$@$(sgr0)"
# $v cat $@.in | $(AWK) '{if ($$0 ~ /@toc@/){ system("cat toc.txt");} else{ print $$0;}}' >$@
ADD_CUSTOM_COMMAND(OUTPUT doc_src/index.hdr
COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/build_tools/build_index_hdr.sh toc.txt
< doc_src/index.hdr.in
> ${CMAKE_CURRENT_BINARY_DIR}/doc_src/index.hdr
DEPENDS toc.txt)
# doc: $(HDR_FILES_SRC) Doxyfile.user $(HTML_SRC) $(HELP_SRC) doc.h $(HDR_FILES) lexicon_filter
# @echo " doxygen $(em)user_doc$(sgr0)"
# $v (cat Doxyfile.user; echo INPUT_FILTER=./lexicon_filter; echo PROJECT_NUMBER=$(FISH_BUILD_VERSION) | $(SED) "s/-.*//") | doxygen - && touch user_doc
# $v rm -f $(wildcard $(addprefix ./user_doc/html/,arrow*.png bc_s.png bdwn.png closed.png doc.png folder*.png ftv2*.png nav*.png open.png splitbar.png sync_*.png tab*.* doxygen.* dynsections.js jquery.js pages.html))
CONFIGURE_FILE("${SPHINX_SRC_DIR}/conf.py" "${SPHINX_BUILD_DIR}/conf.py" @ONLY)
ADD_CUSTOM_TARGET(doc ALL
COMMAND env `cat ${FBVF}`
${CMAKE_CURRENT_SOURCE_DIR}/build_tools/build_user_doc.sh
${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.user ./lexicon_filter
DEPENDS ${CFBVF} Doxyfile.user ${DOC_SRC_FILES} doc.h ${HDR_FILES} build_lexicon_filter command_list_toc.txt)
ADD_CUSTOM_COMMAND(OUTPUT share/man/
COMMAND env `cat ${FBVF} | tr -d '\"' `
INPUT_FILTER=lexicon_filter ${CMAKE_CURRENT_SOURCE_DIR}/build_tools/build_documentation.sh ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.help doc_src ./share
DEPENDS ${CFBVF} ${HELP_SRC} build_lexicon_filter)
ADD_CUSTOM_TARGET(BUILD_MANUALS ALL DEPENDS share/man/)
DEPENDS sphinx-docs sphinx-manpages)
# Group docs targets into a DocsTargets folder
SET_PROPERTY(TARGET doc BUILD_MANUALS build_lexicon_filter
SET_PROPERTY(TARGET doc sphinx-docs sphinx-manpages
PROPERTY FOLDER cmake/DocTargets)
ELSEIF(HAVE_PREBUILT_DOCS)
IF(NOT CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_CURRENT_BINARY_DIR)
# Out of tree build - link the prebuilt documentation to the build tree
ADD_CUSTOM_TARGET(link_doc ALL)
ADD_CUSTOM_COMMAND(TARGET link_doc
COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/share/man ${CMAKE_CURRENT_BINARY_DIR}/share/man
POST_BUILD)
ADD_CUSTOM_COMMAND(TARGET link_doc
COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/user_doc ${CMAKE_CURRENT_BINARY_DIR}/user_doc
POST_BUILD)

12
cmake/Install.cmake
View File

@@ -37,9 +37,9 @@ SET(extra_confdir
CACHE STRING "Path for extra configuration")
# These are the man pages that go in system manpath; all manpages go in the fish-specific manpath.
SET(MANUALS ${CMAKE_CURRENT_BINARY_DIR}/share/man/man1/fish.1
${CMAKE_CURRENT_BINARY_DIR}/share/man/man1/fish_indent.1
${CMAKE_CURRENT_BINARY_DIR}/share/man/man1/fish_key_reader.1)
SET(MANUALS ${CMAKE_CURRENT_BINARY_DIR}/user_doc/man/man1/fish.1
${CMAKE_CURRENT_BINARY_DIR}/user_doc/man/man1/fish_indent.1
${CMAKE_CURRENT_BINARY_DIR}/user_doc/man/man1/fish_key_reader.1)
# Determine which man page we don't want to install.
# On OS X, don't install a man page for open, since we defeat fish's open
@@ -153,8 +153,8 @@ INSTALL(DIRECTORY share/groff
# $v test -z "$(wildcard share/man/man1/*.1)" || $(INSTALL) -m 644 $(filter-out $(addprefix share/man/man1/, $(CONDEMNED_PAGES)), $(wildcard share/man/man1/*.1)) $(DESTDIR)$(datadir)/fish/man/man1/
# CONDEMNED_PAGE is managed by the conditional above
# Building the man pages is optional: if doxygen isn't installed, they're not built
INSTALL(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/share/man/man1/
# Building the man pages is optional: if sphinx isn't installed, they're not built
INSTALL(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/user_doc/man/man1/
DESTINATION ${rel_datadir}/fish/man/man1
FILES_MATCHING
PATTERN "*.1"
@@ -187,7 +187,7 @@ INSTALL(DIRECTORY share/tools/web_config
# $(INSTALL) -m 644 $$i $(DESTDIR)$(mandir)/man1/; \
# true; \
# done;
# Building the man pages is optional: if doxygen isn't installed, they're not built
# Building the man pages is optional: if Sphinx isn't installed, they're not built
INSTALL(FILES ${MANUALS} DESTINATION ${mandir}/man1/ OPTIONAL)
#install-doc: $(user_doc)

7
cmake/gettext.cmake
View File

@@ -23,12 +23,12 @@ IF(GETTEXT_FOUND)
ENDFOREACH()
ENDIF()
CMAKE_PUSH_CHECK_STATE()
SET(CMAKE_REQUIRED_INCLUDES ${CMAKE_REQUIRED_INCLUDES} ${Intl_INCLUDE_DIR})
SET(CMAKE_REQUIRED_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES} ${Intl_LIBRARIES})
# libintl.h can be compiled into the stdlib on some GLibC systems
IF(Intl_FOUND AND Intl_LIBRARIES)
SET(LIBINTL_INCLUDE "#include <libintl.h>")
SET(CMAKE_REQUIRED_INCLUDES ${CMAKE_REQUIRED_INCLUDES} ${Intl_INCLUDE_DIR})
SET(CMAKE_REQUIRED_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES} ${Intl_LIBRARIES})
ENDIF()
CHECK_CXX_SOURCE_COMPILES("
${LIBINTL_INCLUDE}
@@ -40,3 +40,4 @@ int main () {
}
"
HAVE__NL_MSG_CAT_CNTR)
CMAKE_POP_CHECK_STATE()

1438
config.guess vendored
View File

File diff suppressed because it is too large Load Diff

1810
config.sub vendored
View File

File diff suppressed because it is too large Load Diff

744
configure.ac
View File

@@ -1,744 +0,0 @@
#
# This file is the main build configuration file for fish. It is used
# to determine your systems capabilities, and tries to adapt fish to
# take maximum advantage of the services your system offers.
#
# Process this file using the 'autoconf' command to produce a working
# configure script, which should in turn be executed in order to
# configure the build process.
#
m4_syscmd([build_tools/git_version_gen.sh 2>/dev/null])
AC_PREREQ([2.60])
AC_INIT(fish,
m4_esyscmd([cut -f 2 -d '=' FISH-BUILD-VERSION-FILE | tr -d '"\n']),
https://github.com/fish-shell/fish-shell/issues)
ac_clean_files=a.out.dSYM
#
# List of output variables produced by this configure script
#
AC_SUBST(HAVE_GETTEXT)
AC_SUBST(HAVE_DOXYGEN)
AC_SUBST(LDFLAGS_FISH)
AC_SUBST(WCHAR_T_BITS)
AC_SUBST(EXTRA_PCRE2)
AC_SUBST(HAVE_BROKEN_WCWIDTH)
#
# If needed, run autoconf to regenerate the configure file
#
# This makes sure that after running autoconf once to create the first
# version of configure, we never again need to worry about manually
# running autoconf to handle an updates configure.ac.
#
AC_MSG_CHECKING([if autoreconf needs to be run])
if test configure -ot configure.ac; then
AC_MSG_RESULT([yes])
if command -v autoreconf >/dev/null; then
# No need to provide any error messages if autoreconf fails, the
# shell and autconf should take care of that themselves
AC_MSG_NOTICE([running autoreconf --no-recursive])
if autoreconf --no-recursive; then
./configure "$@"
exit
fi
exit 1
else
AC_MSG_ERROR(
[cannot find the autoreconf program in your path.
This program needs to be run whenever the configure.ac file is modified.
Please install autoreconf and try again.]
)
fi
else
AC_MSG_RESULT([no])
fi
#
# If needed, run autoheader to regenerate config.h.in
#
# This makes sure we never ever have to run autoheader manually. It
# will be run whenever needed automatically.
#
AC_MSG_CHECKING([if autoheader needs to be run])
if test ! -f ./config.h.in -o config.h.in -ot configure.ac; then
AC_MSG_RESULT([yes])
if command -v autoheader >/dev/null; then
AC_MSG_NOTICE([running autoheader])
autoheader || exit 1
else
AC_MSG_ERROR(
[cannot find the autoheader program in your path.
This program needs to be run whenever the configure.ac file is modified.
Please install autotools and try again.]
)
fi
else
AC_MSG_RESULT([no])
fi
#
# Include the autoconf macros directory
#
AC_CONFIG_MACRO_DIRS([m4])
#
# Set up various programs needed for install
# Note AC_PROG_CXX sets CXXFLAGS if not set, which we want
# So ensure this happens before we modify CXXFLAGS below
# Do CC also, because PCRE2 will use it.
AC_PROG_CC
AC_PROG_CC_STDC # c99
AC_PROG_CXX
AC_LANG(C++)
AC_PROG_INSTALL
AC_PROG_LN_S
AC_PROG_MKDIR_P
AC_PROG_AWK
AC_PROG_FGREP
AC_PROG_SED
AC_USE_SYSTEM_EXTENSIONS
AX_CXX_COMPILE_STDCXX_11(noext,mandatory)
#
# Tell autoconf to create config.h header
#
AC_CONFIG_HEADERS(config.h)
AC_CANONICAL_HOST
#
# This adds markup to the code that results in a few extra compile
# time checks on recent GCC versions. It helps stop a few common bugs.
#
AH_BOTTOM([#if __GNUC__ >= 3
#ifndef __warn_unused
#define __warn_unused __attribute__ ((warn_unused_result))
#endif
#ifndef __sentinel
#define __sentinel __attribute__ ((sentinel))
#endif
#ifndef __packed
#define __packed __attribute__ ((packed))
#endif
#else
#define __warn_unused
#define __sentinel
#define __packed
#endif])
#
# Optionally drop gettext support
#
AC_ARG_WITH(
gettext,
AS_HELP_STRING(
[--without-gettext],
[do not translate messages, even if gettext is available]
),
[local_gettext=$withval],
[local_gettext=check]
)
AS_IF([test x$local_gettext != xno],
[ AC_CHECK_PROGS( [found_msgfmt], [msgfmt], [no] )
if test x$found_msgfmt != xno; then
AC_DEFINE([USE_GETTEXT],[1],[Perform string translations with gettext])
elif test "x$local_gettext" != "xcheck" ; then
AC_MSG_FAILURE([--with-gettext was given, but the msgfmt program could not be found])
else
local_gettext=no
fi
],
)
#
# Build/clean the documentation only if Doxygen is available
#
doxygen_minimum=1.8.7
AC_ARG_WITH(
doxygen,
AS_HELP_STRING(
[--with-doxygen],
[use Doxygen to regenerate documentation]
),
[use_doxygen=$withval],
[use_doxygen=auto]
)
AS_IF([test "$use_doxygen" != "no"],
[
AC_CHECK_PROGS([found_doxygen], [doxygen], [no])
if test "$found_doxygen" != no; then
# test version
AC_MSG_CHECKING([the doxygen version])
doxygen_version=`doxygen --version 2>/dev/null`
AC_MSG_RESULT([$doxygen_version])
dnl This requires autoconf 2.60 or newer
AS_VERSION_COMPARE([$doxygen_version], [$doxygen_minimum],
[ if test "$use_doxygen" = auto; then
AC_MSG_WARN([doxygen version $doxygen_version found, but $doxygen_minimum required])
HAVE_DOXYGEN=0
else
AC_MSG_FAILURE([doxygen version $doxygen_version found, but $doxygen_minimum required])
fi
],
[HAVE_DOXYGEN=1], [HAVE_DOXYGEN=1])
elif test "$use_doxygen" != auto; then
AC_MSG_FAILURE([--with-doxygen was given, but the doxygen program could not be found])
else
HAVE_DOXYGEN=0
fi
],
)
#
# Try to enable large file support. This will make sure that on systems
# where off_t can be either 32 or 64 bit, the latter size is used. On
# other systems, this should do nothing. (Hopefully)
#
AC_SYS_LARGEFILE
# Fish does not use exceptions.
CXXFLAGS="$CXXFLAGS -fno-exceptions"
#
# Set some warning flags
# Don't warn about missing field initializers, it has too many
# false positives for code like `struct termios tmodes = {};`
#
CXXFLAGS="$CXXFLAGS -Wextra -Wno-missing-field-initializers"
#
# This is needed in order to get the really cool backtraces on Linux
#
AC_MSG_CHECKING([for -rdynamic linker flag])
prev_LDFLAGS="$LDFLAGS"
LDFLAGS="$LDFLAGS -rdynamic"
AC_LINK_IFELSE([AC_LANG_PROGRAM([[]],[[]])],
[
AC_MSG_RESULT([yes])
LDFLAGS_FISH="$LDFLAGS_FISH -rdynamic"
], [
AC_MSG_RESULT([no])
LDFLAGS_FISH="$LDFLAGS_FISH"
])
LDFLAGS="$prev_LDFLAGS"
#
# See if Linux procfs is present. This is used to get extra
# information about running processes.
#
AC_CHECK_FILES([/proc/self/stat])
# Disable curses macros that conflict with the STL
AC_DEFINE([NCURSES_NOMACROS], [1], [Define to 1 to disable ncurses macros that conflict with the STL])
AC_DEFINE([NOMACROS], [1], [Define to 1 to disable curses macros that conflict with the STL])
# Threading is excitingly broken on Solaris without adding -pthread to CXXFLAGS
# Only support GCC for now
dnl Ideally we would use the AX_PTHREAD macro here, but it's GPL3-licensed
dnl ACX_PTHREAD is way too old and seems to break the OS X build
dnl Both only check with AC_LANG(C) in any case
case $host_os in
solaris*)
CXXFLAGS="$CXXFLAGS -pthread"
CFLAGS="$CFLAGS -pthread"
;;
esac
#
# Check presense of various libraries. This is done on a per-binary
# level, since including various extra libraries in all binaries only
# because thay are used by some of them can cause extra bloat and
# slower compiles when developing fish.
#
# Check for os dependant libraries for all binaries.
AC_SEARCH_LIBS( nanosleep, rt, , [AC_MSG_ERROR([Cannot find the rt library, needed to build this package.] )] )
AC_SEARCH_LIBS( shm_open, rt, [AC_DEFINE([HAVE_SHM_OPEN], [1], [Define to 1 if the shm_open() function exists])] )
AC_SEARCH_LIBS( pthread_create, pthread, , [AC_MSG_ERROR([Cannot find the pthread library, needed to build this package.] )] )
AC_SEARCH_LIBS( setupterm, [ncurses tinfo curses], , [AC_MSG_ERROR([Could not find a curses implementation, needed to build fish. If this is Linux, try running 'sudo apt-get install libncurses5-dev' or 'sudo yum install ncurses-devel'])] )
AC_SEARCH_LIBS( [dladdr], [dl] )
if test x$local_gettext != xno; then
AC_SEARCH_LIBS( gettext, intl,,)
fi
#
# Check presense of various header files
#
AC_CHECK_HEADERS([getopt.h termios.h sys/resource.h term.h ncurses/term.h ncurses.h ncurses/curses.h curses.h stropts.h siginfo.h sys/select.h sys/ioctl.h execinfo.h spawn.h sys/sysctl.h xlocale.h])
if test x$local_gettext != xno; then
AC_CHECK_HEADERS([libintl.h])
fi
#
# Get the size in bits of wchar_t, needed for configuring the pcre2 build
# and for code that #includes pcre2.h
#
AC_CHECK_SIZEOF(wchar_t)
WCHAR_T_BITS=`expr 8 \* $ac_cv_sizeof_wchar_t`
AC_DEFINE_UNQUOTED([WCHAR_T_BITS], [$WCHAR_T_BITS], [The size of wchar_t in bits.])
#
# Detect nanoseconds fields in struct stat
#
AC_CHECK_MEMBERS([struct stat.st_ctime_nsec])
AC_CHECK_MEMBERS([struct stat.st_mtimespec.tv_nsec])
AC_CHECK_MEMBERS([struct stat.st_mtim.tv_nsec])
#
# Check for D_TYPE in dirent, only on BSD and Linux
#
AC_STRUCT_DIRENT_D_TYPE
#
# Check for presence of various functions used by fish
#
AC_CHECK_FUNCS( wcsndup )
AC_CHECK_FUNCS( wcstod_l )
AC_CHECK_FUNCS( futimes )
AC_CHECK_FUNCS( wcslcpy lrand48_r killpg )
AC_CHECK_FUNCS( backtrace_symbols getifaddrs )
AC_CHECK_FUNCS( futimens clock_gettime )
AC_CHECK_FUNCS( getpwent flock )
AC_MSG_CHECKING([dirfd])
AC_LINK_IFELSE([
AC_LANG_PROGRAM(
[
#include <dirent.h>
DIR *dirp;
], [
return dirfd(dirp);
]
)
]
, [ AC_MSG_RESULT([yes])
AC_DEFINE([HAVE_DIRFD], 1, [ Define to 1 if you have the `dirfd' function or macro. ])
],
[ AC_MSG_RESULT([no])]
)
AC_CHECK_DECL( [__NetBSD__], AC_DEFINE([TPARM_VARARGS], 1, [ Make tparm take varargs ]) )
AC_CHECK_DECL( [mkostemp], [ AC_CHECK_FUNCS([mkostemp]) ] )
#
# Although setupterm is linkable thanks to SEARCH_LIBS above, some
# builds of ncurses include the actual headers in a different package
#
AC_CHECK_DECL( [setupterm], , [AC_MSG_ERROR([Could not find a curses implementation, needed to build fish. If this is Linux, try running 'sudo apt-get install libncurses5-dev' or 'sudo yum install ncurses-devel'])], [
#if HAVE_NCURSES_H
#include <ncurses.h>
#elif HAVE_NCURSES_CURSES_H
#include <ncurses/curses.h>
#else
#include <curses.h>
#endif
#if HAVE_TERM_H
#include <term.h>
#elif HAVE_NCURSES_TERM_H
#include <ncurses/term.h>
#endif
] )
dnl AC_CHECK_FUNCS uses C linkage, but sometimes (Solaris!) the behaviour is
dnl different with C++.
AC_MSG_CHECKING([for wcsdup])
AC_TRY_LINK( [ #include <wchar.h> ],
[ wchar_t* foo = wcsdup(L""); ],
[ AC_MSG_RESULT(yes)
AC_DEFINE(HAVE_WCSDUP, 1, Define to 1 if you have the `wcsdup' function.)
],
[AC_MSG_RESULT(no)],
)
AC_MSG_CHECKING([for std::wcsdup])
AC_TRY_LINK( [ #include <wchar.h> ],
[ wchar_t* foo = std::wcsdup(L""); ],
[ AC_MSG_RESULT(yes)
AC_DEFINE(HAVE_STD__WCSDUP, 1, Define to 1 if you have the `std::wcsdup' function.)
],
[AC_MSG_RESULT(no)],
)
AC_MSG_CHECKING([for wcscasecmp])
AC_TRY_LINK( [ #include <wchar.h> ],
[ int foo = wcscasecmp(L"", L""); ],
[ AC_MSG_RESULT(yes)
AC_DEFINE(HAVE_WCSCASECMP, 1, Define to 1 if you have the `wcscasecmp' function.)
],
[AC_MSG_RESULT(no)],
)
AC_MSG_CHECKING([for std::wcscasecmp])
AC_TRY_LINK( [ #include <wchar.h> ],
[ int foo = std::wcscasecmp(L"", L""); ],
[ AC_MSG_RESULT(yes)
AC_DEFINE(HAVE_STD__WCSCASECMP, 1, Define to 1 if you have the `std::wcscasecmp' function.)
],
[AC_MSG_RESULT(no)],
)
AC_MSG_CHECKING([for wcsncasecmp])
AC_TRY_LINK( [ #include <wchar.h> ],
[ int foo = wcsncasecmp(L"", L"", 0); ],
[ AC_MSG_RESULT(yes)
AC_DEFINE(HAVE_WCSNCASECMP, 1, Define to 1 if you have the `wcsncasecmp' function.)
],
[AC_MSG_RESULT(no)],
)
AC_MSG_CHECKING([for std::wcsncasecmp])
AC_TRY_LINK( [ #include <wchar.h> ],
[ int foo = std::wcsncasecmp(L"", L"", 0); ],
[ AC_MSG_RESULT(yes)
AC_DEFINE(HAVE_STD__WCSNCASECMP, 1, Define to 1 if you have the `std::wcsncasecmp' function.)
],
[AC_MSG_RESULT(no)],
)
AC_MSG_CHECKING([for std::make_unique])
AC_TRY_LINK( [ #include <memory> ],
[ std::unique_ptr<int> foo = std::make_unique<int>(); ],
[ AC_MSG_RESULT(yes)
AC_DEFINE(HAVE_STD__MAKE_UNIQUE, 1, Define to 1 if you have the `std::make_unique' function.)
],
[AC_MSG_RESULT(no)],
)
if test x$local_gettext != xno; then
AC_CHECK_FUNCS( gettext )
#
# The Makefile also needs to know if we have gettext, so it knows if
# the translations should be installed.
#
AC_CHECK_FUNC( gettext, HAVE_GETTEXT=1, HAVE_GETTEXT=0 )
fi
#
# Here follows a list of small programs used to test for various
# features that Autoconf doesn't tell us about
#
dnl AC_CHECK_FUNCS uses C linkage, but sometimes (Solaris!) the behaviour is
dnl different with C++.
AC_MSG_CHECKING([if ctermid_r() available])
AC_TRY_LINK( [ #include <stdio.h> ],
[ char buf[L_ctermid]; char *foo = ctermid_r(buf); ],
[ AC_MSG_RESULT(yes)
AC_DEFINE(HAVE_CTERMID_R, 1, Define to 1 if you have the `ctermid_r' function.)
],
[AC_MSG_RESULT(no)],
)
#
# Check if struct winsize and TIOCGWINSZ exist
#
AC_MSG_CHECKING([if struct winsize and TIOCGWINSZ exist])
AC_LINK_IFELSE(
[
AC_LANG_PROGRAM(
[
#ifdef HAVE_TERMIOS_H
#include <termios.h>
#endif
#ifdef HAVE_SYS_IOCTL_H
#include <sys/ioctl.h>
#endif
],
[
struct winsize termsize = {0};
TIOCGWINSZ;
]
)
],
[
AC_MSG_RESULT(yes);
AC_DEFINE([HAVE_WINSIZE], [1], [Define to 1 if the winsize struct and TIOCGWINSZ macro exist])
],
[
AC_MSG_RESULT(no)
]
)
# Check for _nl_msg_cat_cntr symbol
AC_MSG_CHECKING([for _nl_msg_cat_cntr symbol])
AC_TRY_LINK(
[
#if HAVE_LIBINTL_H
#include <libintl.h>
#endif
#include <stdlib.h>
],
[
extern int _nl_msg_cat_cntr;
int tmp = _nl_msg_cat_cntr;
exit(tmp);
],
have__nl_msg_cat_cntr=yes,
have__nl_msg_cat_cntr=no
)
if test "$have__nl_msg_cat_cntr" = yes; then
AC_MSG_RESULT(yes)
AC_DEFINE(
[HAVE__NL_MSG_CAT_CNTR],
[1],
[Define to 1 if the _nl_msg_cat_cntr symbol is exported.]
)
else
AC_MSG_RESULT(no)
fi
# Check for sys_errlist
AC_MSG_CHECKING([for sys_errlist array])
AC_TRY_LINK(
[
#include <stdio.h>
],
[
const char *p;
p = sys_errlist[sys_nerr];
],
have_sys_errlist=yes,
have_sys_errlist=no
)
if test "$have_sys_errlist" = yes; then
AC_MSG_RESULT(yes)
AC_DEFINE(
[HAVE_SYS_ERRLIST],
[1],
[Define to 1 if the sys_errlist array is available.]
)
else
AC_MSG_RESULT(no)
fi
# Check for _sys_errs
AC_MSG_CHECKING([for _sys_errs array])
AC_TRY_LINK(
[
#include <string>
],
[
std::string p;
extern const char _sys_errs[];
extern const int _sys_index[];
p = _sys_errs[_sys_index[0]];
],
have__sys__errs=yes,
have__sys__errs=no
)
if test "$have__sys__errs" = yes; then
AC_MSG_RESULT(yes)
AC_DEFINE(
[HAVE__SYS__ERRS],
[1],
[Define to 1 if the _sys_errs array is available.]
)
else
AC_MSG_RESULT(no)
fi
# Check for Solaris curses tputs having fixed length parameter list.
AC_MSG_CHECKING([if we are using non varargs tparm.])
AC_COMPILE_IFELSE(
[
AC_LANG_PROGRAM(
[
#define TPARM_VARARGS 1
#if HAVE_NCURSES_H
#include <ncurses.h>
#elif HAVE_NCURSES_CURSES_H
#include <ncurses/curses.h>
#else
#include <curses.h>
#endif
#if HAVE_TERM_H
#include <term.h>
#elif HAVE_NCURSES_TERM_H
#include <ncurses/term.h>
#endif
],
[
tparm( "" );
]
)
],
[tparm_solaris_kludge=no],
[tparm_solaris_kludge=yes]
)
if test "x$tparm_solaris_kludge" = "xyes"; then
AC_MSG_RESULT(yes)
AC_DEFINE(
[TPARM_SOLARIS_KLUDGE],
[1],
[Define to 1 if tparm accepts a fixed amount of paramters.]
)
else
AC_MSG_RESULT(no)
fi
# ========
# PCRE2 library configuration.
pcre2_min_version=10.21
EXTRA_PCRE2=
AC_ARG_WITH(
included-pcre2,
AS_HELP_STRING(
[--without-included-pcre2],
[build against the system PCRE2 library instead of the bundled version]
),
[included_pcre2=$withval],
[included_pcre2=auto]
)
HAVE_BROKEN_WCWIDTH=
AC_ARG_ENABLE(
[wcwidth],
AS_HELP_STRING(
[--disable-internal-wcwidth],
[use system wcwidth instead of the bundled version]
))
if test "x$enable_wcwidth" != "xno"; then
AC_DEFINE([HAVE_BROKEN_WCWIDTH], [1], [banana])
else
AC_DEFINE([HAVE_BROKEN_WCWIDTH], [0], [banana])
fi
if test "x$included_pcre2" != "xyes"; then
# test for pcre2-config
# can use either pcre2-config or pkgconfig here but only implement the former for now
AC_CHECK_PROG(PCRE2_CONFIG, pcre2-config, pcre2-config)
if test "x$PCRE2_CONFIG" != "x"; then
dnl AC_MSG_CHECKING([for $WCHAR_T_BITS-bit PCRE2])
XLIBS="$LIBS"
LIBS="$LIBS "`$PCRE2_CONFIG --libs$WCHAR_T_BITS 2>/dev/null`
XCXXFLAGS="$CXXFLAGS"
CXXFLAGS="$CXXFLAGS "`$PCRE2_CONFIG --cflags`
# cheat a bit here. the exact library is determined by $WCHAR_T_BITS,
# and so AC_CHECK_LIB won't work (can't use a variable as library name)
# AC_SEARCH_LIBS will use the existing $LIBS flags with no additional library first
AC_SEARCH_LIBS([pcre2_compile_$WCHAR_T_BITS], [],
[ # pcre2 lib found, check for minimum version
pcre2_version=`$PCRE2_CONFIG --version`
AS_VERSION_COMPARE([$pcre2_version], [$pcre2_min_version],
[ # version < minimum
AC_MSG_NOTICE([system PCRE2 library version $pcre2_version, need $pcre2_min_version or later])
if test "x$included_pcre2" = "xno"; then
# complain about pcre2 version
AC_MSG_ERROR([system PCRE2 library is too old, but --without-included-pcre2 was given.])
else
# use the internal version; undo changes to LIBS/CXXFLAGS
included_pcre2=yes
LIBS="$XLIBS"
CXXFLAGS="$XCXXFLAGS"
fi
],
[ # version == minimum
working_pcre2=yes
],
[ # version > minimum
working_pcre2=yes
]
)
],
[ # fail case; undo the changes to LIBS/CXXFLAGS
working_pcre2=no
LIBS="$XLIBS"
CXXFLAGS="$XCXXFLAGS"
]
)
fi
if test "x$working_pcre2" = "xyes"; then
AC_MSG_NOTICE([using system PCRE2 library])
else
# pcre2 size wrong or pcre2-config not found
# is it OK to use the included version?
if test "x$included_pcre2" = "xno"; then
# complain
AC_MSG_ERROR([cannot find system pcre2-config, but --without-included-pcre2 was given.
Make sure pcre2-config is installed and available in PATH.
You may need to install the PCRE2 development library for your system.])
else
# use the internal version
included_pcre2=yes
fi
fi
fi
# Re-test as value may have changed.
if test "x$included_pcre2" = "xyes"; then
# Build configure/Makefile for pcre2
AC_MSG_NOTICE([using included PCRE2 library])
# unfortunately these get added to the global configuration
ac_configure_args="$ac_configure_args --disable-pcre2-8 --enable-pcre2-$WCHAR_T_BITS --disable-shared"
AC_CONFIG_SUBDIRS([pcre2-10.32])
PCRE2_CXXFLAGS='-I$(PCRE2_DIR)/src'
PCRE2_LIBS='-L$(PCRE2_LIBDIR) -lpcre2-$(PCRE2_WIDTH)'
# Make the binary depend on the PCRE2 libraries so they get built
EXTRA_PCRE2='$(PCRE2_LIB)'
CXXFLAGS="$CXXFLAGS $PCRE2_CXXFLAGS"
LIBS="$LIBS $PCRE2_LIBS"
fi
# Allow configurable extra directories.
AC_SUBST(extra_completionsdir)
AC_ARG_WITH([extra-completionsdir],
AS_HELP_STRING([--with-extra-completionsdir=DIR],
[path for extra completions]),
[extra_completionsdir=$withval],
[extra_completionsdir='${datadir}/fish/vendor_completions.d'])
AC_SUBST(extra_functionsdir)
AC_ARG_WITH([extra_functionsdir],
AS_HELP_STRING([--with-extra-functionsdir=DIR],
[path for extra functions]),
[extra_functionsdir=$withval],
[extra_functionsdir='${datadir}/fish/vendor_functions.d'])
AC_SUBST(extra_confdir)
AC_ARG_WITH([extra-confdir],
AS_HELP_STRING([--with-extra-confdir=DIR],
[path for extra conf]),
[extra_confdir=$withval],
[extra_confdir='${datadir}/fish/vendor_conf.d'])
# Tell the world what we know.
AC_CONFIG_FILES([Makefile])
AC_OUTPUT
echo "fish is now configured."

253
doc_src/FORMATTING.md
View File

@@ -1,253 +0,0 @@
# Formatting guide for fish docs
The fish documentation has been updated to support Doxygen 1.8.7+, and while the main benefit of this change is extensive Markdown support, the addition of a fish lexicon and syntax filter, combined with semantic markup rules allows for automatic formatting enhancements across the HTML user_docs and man pages.
Initially my motivation was to fix a problem with long options ([Issue #1557](https://github.com/fish-shell/fish-shell/issues/1557) on GitHub), but as I worked on fixing the issue I realised there was an opportunity to simplify, reinforce and clarify the current documentation, hopefully making further contribution easier and cleaner, while allowing the documentation examples to presented more clearly with less author effort.
While the documentation is pretty robust to variations in the documentation source, adherence to the following style guide will help keep the already excellent documentation in good shape moving forward.
## Line breaks and wrapping
Contrary to the rest of the fish source code, the documentation greatly benefits from the use of long lines and soft wrapping. Doxygen is able to treat paragraphs as complete blocks. The semantic filter can see complete lines when deciding on how to apply syntax highlighting. In advanced pagers, such as 'most', man pages will consistently wrap to the width of the user's console.
## Doxygen special commands and aliases
While Markdown syntax forms the basis of the documentation content, there are some exceptions that require the use of Doxygen special commands. On the whole, Doxygen commands should be avoided, especially inline word formatting such as \\c as this would allow Doxygen to make unhelpful assumptions, such as converting double dashes (\--) to n-dashes (–).
### Structure: \\page, \\section and \\subsection
Use of Doxygen sections markers are important, as these determine what will be eventually output as a web page, man page or included in the developer docs.
Currently the make process for the documentation is quite convoluted, but basically the HTML docs are produced from a single, compiled file, doc.h. This contains a number of \\page markers that produce the various pages used in the documentation. The format of a \\page mark is:
\page universally_unique_page_id Page title
The source files that contain the page markers are currently:
- __index.hdr.in__: Core documentation
- __commands.hdr.in__: Individual commands
- __tutorial.hdr__: Tutorial
- __design.hdr__: Design document
- __faq.hdr__: Frequently Asked Questions
- __license.hdr__: Fish and 3rd party licences
Unless there is a _VERY_ good reason and developer consensus, new pages should never be added.
The rest of the documentation is structured using \\section and \\subsection markers. Most of the source files (listed above) contain their full content, the exception being commands, which are separated out into source text files in the doc_src directory. These files are concatenated into one file, so each one starts with a \\section declaration. The synopsis, description and examples (if present) are declared as \\subsections. The format of these marks is practically identical to the page mark.
\section universally_unique_section_id Section title
\subsection universally_unique_subsection_id Subsection title
Each page, section and subsection id _must_ be unique across the whole of the documentation, otherwise Doxygen will issue a warning.
### Semantic markup: the \\fish .. \\endfish block
While Doxygen has support for \\code..\\endcode blocks with enhanced markup and syntax colouring, it only understands the core Doxygen languages: C, C++, Objective C, Java, PHP, Python, Tcl and Fortran. To enhance Fish's syntax presentation, use the special \\fish..\\endfish blocks instead.
Text placed in this block will be parsed by Doxygen using the included lexicon filter (see lexicon_filter.in) as a Doxygen input filter. The filter is built during make so that it can pick up information on builtins, functions and shell commands mentioned in completions and apply markup to keywords found inside the \\fish block.
Basically, preformatted plain text inside the \\fish block is fed through the filter and is returned marked up so that Doxygen aliases can convert it back to a presentable form, according to the output document type.
For instance:
`echo hello world`
is transformed into:
`@cmnd{echo} @args{hello} @args{world}`
which is then transformed by Doxygen into an HTML version (`make doc`):
`<span class="command">echo</span> <span class="argument">hello</span> <span class="argument">world</span>`
And a man page version (`make share/man`):
__echo__ hello world
### Fonts
In older browsers, it was easy to set the fonts used for the three basic type styles (serif, sans-serif and monospace). Modern browsers have removed these options in their respective quests for simplification, assuming the content author will provide suitable styles for the content in the site's CSS, or the end user will provide overriding styles manually. Doxygen's default styling is very simple and most users will just accept this default.
I've tried to use a sensible set of fonts in the documentation's CSS based on 'good' terminal fonts and as a result the first preference font used throughout the documentation is '[DejaVu](https://dejavu-fonts.github.io)'. The rationale behind this is that while DejaVu is getting a little long in the tooth, it still provides the most complete support across serif, sans-serif and monospace styles (giving a well balanced feel and consistent [x-height](https://en.wikipedia.org/wiki/X-height)), has the widest support for extended Unicode characters and has a free, permissive licenses (though it's still incompatible with GPLv2, though arguably less so than the SIL Open Font license, though this is a moot point when using it solely in the docs).
#### Fonts inside \\fish blocks and \`backticks\`
As the point of these constructs is to make fish's syntax clearer to the user, it makes sense to mimic what the user will see in the console, therefore any content is formatted using the monospaced style, specifically monospaced fonts are chosen in the following order:
1. __DejaVu Sans Mono__: Explained above. [[&darr;](https://dejavu-fonts.github.io)]
2. __Source Code Pro__: Monospaced code font, part of Adobe's free Edge Web Fonts. [[&darr;](https://edgewebfonts.adobe.com)]
3. __Menlo__: Apple supplied variant of DejaVu.
4. __Ubuntu Mono__: Ubuntu Linux's default monospaced font. [[&darr;](http://font.ubuntu.com)]
5. __Consolas__: Modern Microsoft supplied console font.
6. __Monaco__: Apple supplied console font since 1984!
7. __Lucida Console__: Generic mono terminal font, standard in many OS's and distros.
8. __monospace__: Catchall style. Chooses default monospaced font, often Courier.
9. __fixed__: As above, more often used on mobile devices.
#### General Fonts
1. __DejaVu Sans__: As above.[[&darr;](https://dejavu-fonts.github.io)]
2. __Roboto__: Elegant Google free font and is Doxygen's default [[&darr;](https://fonts.google.com/specimen/Roboto)]
3. __Lucida Grande__: Default Apple OS X content font.
4. __Calibri__: Default Microsoft Office font (since 2007).
5. __Verdana__: Good general font found in a lot of OSs.
6. __Helvetica Neue__: Better spaced and balanced Helvetica/Arial variant.
7. __Helvetica__: Standard humanist typeface found almost everywhere.
8. __Arial__: Microsoft's Helvetica.
9. __sans-serif__: Catchall style. Chooses default sans-serif typeface, often Helvetica.
The ordering of the fonts is important as it's designed to allow the documentation to settle into a number of different identities according to the fonts available. If you have the complete DejaVu family installed, then the docs are presented using that, and if your Console is set up to use the same fonts, presentation will be completely consistent.
On OS X, with nothing extra installed, the docs will default to Menlo and Lucida Grande giving a Mac feel. Under Windows, it will default to using Consolas and Calibri on recent versions, giving a modern Windows style.
#### Other sources:
- [Font Squirrel](https://www.fontsquirrel.com): Good source of open source font packages.
### Choosing a CLI style: using a \\fish{style} block
By default, when output as HTML, a \\fish block uses syntax colouring suited to the style of the documentation rather than trying to mimic the terminal. The block has a light, bordered background and a colour scheme that 'suggests' what the user would see in a console.
Additional stying can be applied adding a style declaration:
\fish{additional_style [another_style...]}
...
\endfish
This will translate to classes applied to the `<div>` tag, like so:
<div class="fish additional_style another_style">
...
</div>
The various classes are defined in `doc_src/user_doc.css` and new style can be simply added
The documentation currently defines a couple of additional styles:
- __cli-dark__: Used in the _tutorial_ and _FAQ_ to simulate a dark background terminal, with fish's default colours (slightly tweaked for legibility in the browser).
- __synopsis__: A simple colour theme helpful for displaying the logical 'summary' of a command's syntax, options and structure.
## Markdown
Apart from the exceptions discussed above, the rest of the documentation now supports the use of Markdown. As such the use of Doxygen special commands for HTML tags is unnecessary.
There are a few exceptions and extensions to the Markdown [standard](https://daringfireball.net/projects/markdown/) that are documented in the Doxygen [documentation](https://www.stack.nl/~dimitri/doxygen/manual/markdown.html).
### \`Backticks\`
As is standard in Markdown and 'Github Flavoured Markdown' (GFM), backticks can be used to denote inline technical terms in the documentation, `like so`. In the documentation this will set the font to the monospaced 'console' typeface and will cause the enclosed term to stand out.
However, fenced code blocks using 4 spaces or 3 backticks (\`\`\`) should be avoided as Doxygen will interpret these as \\code blocks and try to apply standard syntax colouring, which doesn't work so well for fish examples. Use `\fish..\endfish` blocks instead.
### Lists
Standard Markdown list rules apply, but as Doxygen will collapse white space on output, combined with the use of long lines, it's a good idea to include an extra new line between long list items to assist future editing.
## Special cases
The following can be used in \\fish blocks to render some fish scenarios. These are mostly used in the tutorial when an interactive situation needs to be displayed.
### Custom formatting tags
```html
<u>: <u>These words are underlined.</u>
<s>: auto<s>suggestion</s>.
<m>: <m>Matched</m> items, such as tab completions.
<sm>: Matched items <sm>searched</sm> for, like grep results.
<bs>: Render the contents with a preceding backslash. Useful when presenting output.
<eror>: <eror>This would be shown as an error. (Note eror, not error).</eror>
<asis>: <asis>This text will not be parsed for fish markup.</asis>
<outp>: <outp>This would be rendered as command/script output.</outp>
{{ and }}: Required when wanting curly braces in regular expression example.
```
### Prompts and cursors
```html
>_: Display a basic prompt.
~>_: Display a prompt with a the home directory as the current working directory.
___ (3 underscores): Display a cursor.
```
### Keyboard shortcuts: @key{} and @cursor_key{}
Graphical keyboard shortcuts can be defined using the following special commands. These allow for the different text requirements across the html and man pages. The HTML uses CSS to create a keyboard style, whereas the man page would display the key as text.
- `@key{lable}`
Displays a key with a purely textual lable, such as: 'Tab', 'Page Up', 'Page Down', 'Home', 'End', 'F1', 'F19' and so on.
- `@key{modifier,lable}`
Displays a keystroke requiring the use of a 'modifier' key, such as 'Control-A', 'Shift-X', 'Alt-Tab' etc.
- `@key{modifier,entity,lable}`
Displays a keystroke using a graphical entity, such as an arrow symbol for cursor key based shortcuts.
- `@cursor_key{entity,lable}`
A special case for cursor keys, when no modifier is needed. i.e. `@cursor_key{&uarr;,up}` for the up arrow key.
Some useful Unicode/HTML5 entities:
- Up arrow: `&uarr;`
- Down arrow: `&darr;`
- Left arrow: `&larr;`
- Right arrow `&rarr;`
- Shift: `&#8679;`
- Tab: `&rarrb;`
- Mac option: `&#8997;`
- Mac command: `&#8984;`
## Notes
### Doxygen
Tested on:
- Ubuntu 14.04 with Doxygen 1.8.8, built from [GitHub source](https://github.com/doxygen/doxygen.git).
- CentOS 6.5 with Doxygen 1.8.8, built from [GitHub source](https://github.com/doxygen/doxygen.git).
- Mac OS X 10.9 with Homebrew install Doxygen 1.8.7 and 1.8.8.
Graphviz was also installed in all the above testing.
Doxygen 1.8.6 and lower do not have the \\htmlonly[block] directive which fixes a multitude of problems in the rendering of the docs. In Doxygen 1.8.7 the list of understood HTML entities was greatly increased. I tested earlier versions and many little issues returned.
As fish ships with pre-built documentation, I don't see this as an issue.
### Updated Configure/Makefile
- Tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9.
- Makefile has GNU/BSD sed/grep detection.
### HTML output
- The output HTML is HTML5 compliant, but should quickly and elegantly degrade on older browsers without losing basic structure.
- The CSS avoids the use or browser specific extensions (i.e. -webkit, -moz etc), using the W3C HTML5 standard instead.
- It's been tested in Chrome 37.0 and Firefox 32.0 on Mac OS X 10.9 (+Safari 7), Windows 8.1 (+Internet Explorer 11) and Ubuntu Desktop 14.04.
- My assumption is basically that if someone cares enough to want to install fish, they'll be keeping a browser current.
### Man page output
- Tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9.
- Output is substantially cleaner.
- Tested in cat, less, more and most pagers using the following fish script:
```
function manTest --description 'Test manpage' --argument page
set -l pager
for i in $argv
switch $i
case "-l"
set pager -P '/usr/bin/less -is'
case "-m"
set pager -P '/usr/bin/more -s'
case "-c"
set pager -P '/bin/cat'
end
end
man $pager ~/Projects/OpenSource/fish-shell/share/man/man1/$page.1
end
# Assumes 'most' is the default system pager.
# NOT PORTABLE! Paths would be need to be updated on other systems.
```
#### Author: Mark Griffiths [@GitHub](https://github.com/MarkGriffiths)

80
doc_src/abbr.txt
View File

@@ -1,80 +0,0 @@
\section abbr abbr - manage fish abbreviations
\subsection abbr-synopsis Synopsis
\fish{synopsis}
abbr --add [SCOPE] WORD EXPANSION
abbr --erase word
abbr --rename [SCOPE] OLD_WORD NEW_WORD
abbr --show
abbr --list
\endfish
\subsection abbr-description Description
`abbr` manages abbreviations - user-defined words that are replaced with longer phrases after they are entered.
For example, a frequently-run command like `git checkout` can be abbreviated to `gco`. After entering `gco` and pressing @key{Space} or @key{Enter}, the full text `git checkout` will appear in the command line.
\subsection abbr-options Options
The following options are available:
- `-a WORD EXPANSION` or `--add WORD EXPANSION` Adds a new abbreviation, causing WORD to be expanded to PHRASE.
- `-r OLD_WORD NEW_WORD` or `--rename OLD_WORD NEW_WORD` Renames an abbreviation, from OLD_WORD to NEW_WORD.
- `-s` or `--show` Show all abbreviations in a manner suitable for export and import.
- `-l` or `--list` Lists all abbreviated words.
- `-e WORD` or `--erase WORD` Erase the abbreviation WORD.
In addition, when adding abbreviations:
- `-g` or `--global` to use a global variable.
- `-U` or `--universal` to use a universal variable (default).
See the "Internals" section for more on them.
\subsection abbr-example Examples
\fish
abbr -a -g gco git checkout
\endfish
Add a new abbreviation where `gco` will be replaced with `git checkout` global to the current shell. This abbreviation will not be automatically visible to other shells unless the same command is run in those shells (such as when executing the commands in config.fish).
\fish
abbr -a -U l less
\endfish
Add a new abbreviation where `l` will be replaced with `less` universal so all shells. Note that you omit the `-U` since it is the default.
\fish
abbr -r gco gch
\endfish
Renames an existing abbreviation from `gco` to `gch`.
\fish
abbr -e gco
\endfish
Erase the `gco` abbreviation.
\fish
ssh another_host abbr -s | source
\endfish
Import the abbreviations defined on another_host over SSH.
\subsection abbr-internals Internals
Each abbreviation is stored in its own global or universal variable. The name consists of the prefix `_fish_abbr_` followed by the WORD after being transformed by `string escape style=var`. The WORD cannot contain a space but all other characters are legal.
Defining an abbreviation with global scope is slightly faster than universal scope (which is the default). But in general you'll only want to use the global scope when defining abbreviations in a startup script like `~/.config/fish/config.fish` like this:
\fish
if status --is-interactive
abbr --add --global first 'echo my first abbreviation'
abbr --add --global second 'echo my second abbreviation'
abbr --add --global gco git checkout
# etcetera
end
\endfish
You can create abbreviations interactively and they will be visible to other fish sessions if you use the `-U` or `--universal` flag or don't explicitly specify the scope and the abbreviation isn't already defined with global scope. If you want it to be visible only to the current shell use the `-g` or `--global` flag.

41
doc_src/alias.txt
View File

@@ -1,41 +0,0 @@
\section alias alias - create a function
\subsection alias-synopsis Synopsis
\fish{synopsis}
alias
alias [OPTIONS] NAME DEFINITION
alias [OPTIONS] NAME=DEFINITION
\endfish
\subsection alias-description Description
`alias` is a simple wrapper for the `function` builtin, which creates a function wrapping a command. It has similar syntax to POSIX shell `alias`. For other uses, it is recommended to define a <a href='#function'>function</a>.
`fish` marks functions that have been created by `alias` by including the command used to create them in the function description. You can list `alias`-created functions by running `alias` without arguments. They must be erased using `functions -e`.
- `NAME` is the name of the alias
- `DEFINITION` is the actual command to execute. The string `$argv` will be appended.
You cannot create an alias to a function with the same name. Note that spaces need to be escaped in the call to `alias` just like at the command line, _even inside quoted parts_.
The following options are available:
- `-h` or `--help` displays help about using this command.
- `-s` or `--save` Automatically save the function created by the alias into your fish configuration directory using <a href='#funcsave'>funcsave</a>.
\subsection alias-example Example
The following code will create `rmi`, which runs `rm` with additional arguments on every invocation.
\fish
alias rmi="rm -i"
# This is equivalent to entering the following function:
function rmi --wraps rm --description 'alias rmi=rm -i'
rm -i $argv
end
# This needs to have the spaces escaped or "Chrome.app..." will be seen as an argument to "/Applications/Google":
alias chrome='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome banana'
\endfish

23
doc_src/and.txt
View File

@@ -1,23 +0,0 @@
\section and and - conditionally execute a command
\subsection and-synopsis Synopsis
\fish{synopsis}
COMMAND1; and COMMAND2
\endfish
\subsection and-description Description
`and` is used to execute a command if the previous command was successful (returned a status of 0).
`and` statements may be used as part of the condition in an <a href="#if">`if`</a> or <a href="#while">`while`</a> block. See the documentation for <a href="#if">`if`</a> and <a href="#while">`while`</a> for examples.
`and` does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable.
\subsection and-example Example
The following code runs the `make` command to build a program. If the build succeeds, `make`'s exit status is 0, and the program is installed. If either step fails, the exit status is 1, and `make clean` is run, which removes the files created by the build process.
\fish
make; and make install; or make clean
\endfish

131
doc_src/argparse.txt
View File

@@ -1,131 +0,0 @@
\section argparse argparse - parse options passed to a fish script or function
\subsection argparse-synopsis Synopsis
\fish{synopsis}
argparse [OPTIONS] OPTION_SPEC... -- [ARG...]
\endfish
\subsection argparse-description Description
This command makes it easy for fish scripts and functions to handle arguments in a manner 100% identical to how fish builtin commands handle their arguments. You pass a sequence of arguments that define the options recognized, followed by a literal `--`, then the arguments to be parsed (which might also include a literal `--`). More on this in the <a href="#argparse-usage">usage</a> section below.
Each OPTION_SPEC can be written in the domain specific language <a href="#argparse-option-specs">described below</a> or created using the companion <a href="#fish_opt">`fish_opt`</a> command. All OPTION_SPECs must appear after any argparse flags and before the `--` that separates them from the arguments to be parsed.
Each option that is seen in the ARG list will result in a var name of the form `_flag_X`, where `X` is the short flag letter and the long flag name. The OPTION_SPEC always requires a short flag even if it can't be used. So there will always be `_flag_X` var set using the short flag letter if the corresponding short or long flag is seen. The long flag name var (e.g., `_flag_help`) will only be defined, obviously, if the OPTION_SPEC includes a long flag name.
For example `_flag_h` and `_flag_help` if `-h` or `--help` is seen. The var will be set with local scope (i.e., as if the script had done `set -l _flag_X`). If the flag is a boolean (that is, does not have an associated value) the values are the short and long flags seen. If the option is not a boolean flag the values will be zero or more values corresponding to the values collected when the ARG list is processed. If the flag was not seen the flag var will not be set.
\subsection argparse-options Options
The following `argparse` options are available. They must appear before all OPTION_SPECs:
- `-n` or `--name` is the command name to insert into any error messages. If you don't provide this value `argparse` will be used.
- `-x` or `--exclusive` should be followed by a comma separated list of short of long options that are mutually exclusive. You can use this option more than once to define multiple sets of mutually exclusive options.
- `-N` or `--min-args` is followed by an integer that defines the minimum number of acceptable non-option arguments. The default is zero.
- `-X` or `--max-args` is followed by an integer that defines the maximum number of acceptable non-option arguments. The default is infinity.
- `-s` or `--stop-nonopt` causes scanning the arguments to stop as soon as the first non-option argument is seen. Using this arg is equivalent to calling the C function `getopt_long()` with the short options starting with a `+` symbol. This is sometimes known as "POSIXLY CORRECT". If this flag is not used then arguments are reordered (i.e., permuted) so that all non-option arguments are moved after option arguments. This mode has several uses but the main one is to implement a command that has subcommands.
- `-h` or `--help` displays help about using this command.
\subsection argparse-usage Usage
Using this command involves passing two sets of arguments separated by `--`. The first set consists of one or more option specifications (`OPTION_SPEC` above) and options that modify the behavior of `argparse`. These must be listed before the `--` argument. The second set are the arguments to be parsed in accordance with the option specifications. They occur after the `--` argument and can be empty. More about this below but here is a simple example that might be used in a function named `my_function`:
\fish
argparse --name=my_function 'h/help' 'n/name=' -- $argv
or return
\endfish
If `$argv` is empty then there is nothing to parse and `argparse` returns zero to indicate success. If `$argv` is not empty then it is checked for flags `-h`, `--help`, `-n` and `--name`. If they are found they are removed from the arguments and local variables (more on this <a href="argparse-local-variables">below</a>) are set so the script can determine which options were seen. Assuming `$argv` doesn't have any errors, such as a missing mandatory value for an option, then `argparse` exits with status zero. Otherwise it writes appropriate error messages to stderr and exits with a status of one.
The `--` argument is required. You do not have to include any arguments after the `--` but you must include the `--`. For example, this is acceptable:
\fish
set -l argv
argparse 'h/help' 'n/name' -- $argv
\endfish
But this is not:
\fish
set -l argv
argparse 'h/help' 'n/name' $argv
\endfish
The first `--` seen is what allows the `argparse` command to reliably separate the option specifications from the command arguments.
\subsection argparse-option-specs Option Specifications
Each option specification is a string composed of
- A short flag letter (which is mandatory). It must be an alphanumeric or "#". The "#" character is special and means that a flag of the form `-123` is valid. The short flag "#" must be followed by "-" (since the short name isn't otherwise valid since `_flag_#` is not a valid var name) and must be followed by a long flag name with no modifiers.
- A `/` if the short flag can be used by someone invoking your command else `-` if it should not be exposed as a valid short flag. If there is no long flag name these characters should be omitted. You can also specify a '#' to indicate the short and long flag names can be used and the value can be specified as an implicit int; i.e., a flag of the form `-NNN`.
- A long flag name which is optional. If not present then only the short flag letter can be used.
- Nothing if the flag is a boolean that takes no argument or is an implicit int flag, else
- `=` if it requires a value and only the last instance of the flag is saved, else
- `=?` it takes an optional value and only the last instance of the flag is saved, else
- `=+` if it requires a value and each instance of the flag is saved.
- Optionally a `!` followed by fish script to validate the value. Typically this will be a function to run. If the return status is zero the value for the flag is valid. If non-zero the value is invalid. Any error messages should be written to stdout (not stderr). See the section on <a href="#arparse-validation">Flag Value Validation</a> for more information.
See the <a href="#fish_opt">`fish_opt`</a> command for a friendlier but more verbose way to create option specifications.
In the following examples if a flag is not seen when parsing the arguments then the corresponding _flag_X var(s) will not be set.
\subsection argparse-validation Flag Value Validation
It is common to want to validate the the value provided for an option satisfies some criteria. For example, that it is a valid integer within a specific range. You can always do this after `argparse` returns but you can also request that `argparse` perform the validation by executing arbitrary fish script. To do so simply append an `!` (exclamation-mark) then the fish script to be run. When that code is executed three vars will be defined:
- `_argparse_cmd` will be set to the value of the value of the `argparse --name` value.
- `_flag_name` will be set to the short or long flag that being processed.
- `_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.
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.
Fish ships with a `_validate_int` function that accepts a `--min` and `--max` flag. Let's say your command accepts a `-m` or `--max` flag and the minimum allowable value is zero and the maximum is 5. You would define the option like this: `m/max=!_validate_int --min 0 --max 5`. The default if you just call `_validate_int` without those flags is to simply check that the value is a valid integer with no limits on the min or max value allowed.
\subsection argparse-optspec-examples Example OPTION_SPECs
Some OPTION_SPEC examples:
- `h/help` means that both `-h` and `--help` are valid. The flag is a boolean and can be used more than once. If either flag is used then `_flag_h` and `_flag_help` will be set to the count of how many times either flag was seen.
- `h-help` means that only `--help` is valid. The flag is a boolean and can be used more than once. If the long flag is used then `_flag_h` and `_flag_help` will be set to the count of how many times the long flag was seen.
- `n/name=` means that both `-n` and `--name` are valid. It requires a value and can be used at most once. If the flag is seen then `_flag_n` and `_flag_name` will be set with the single mandatory value associated with the flag.
- `n/name=?` means that both `-n` and `--name` are valid. It accepts an optional value and can be used at most once. If the flag is seen then `_flag_n` and `_flag_name` will be set with the value associated with the flag if one was provided else it will be set with no values.
- `n-name=+` means that only `--name` is valid. It requires a value and can be used more than once. If the flag is seen then `_flag_n` and `_flag_name` will be set with the values associated with each occurrence of the flag.
- `x` means that only `-x` is valid. It is a boolean can can be used more than once. If it is seen then `_flag_x` will be set to the count of how many times the flag was seen.
- `x=`, `x=?`, and `x=+` are similar to the n/name examples above but there is no long flag alternative to the short flag `-x`.
- `x-` is not valid since there is no long flag name and therefore the short flag, `-x`, has to be usable.
- `#-max` means that flags matching the regex "^--?\d+$" are valid. When seen they are assigned to the variable `_flag_max`. This allows any valid positive or negative integer to be specified by prefixing it with a single "-". Many commands support this idiom. For example `head -3 /a/file` to emit only the first three lines of /a/file.
- `n#max` means that flags matching the regex "^--?\d+$" are valid. When seen they are assigned to the variables `_flag_n` and `_flag_max`. This allows any valid positive or negative integer to be specified by prefixing it with a single "-". Many commands support this idiom. For example `head -3 /a/file` to emit only the first three lines of /a/file. You can also specify the value using either flag: `-n NNN` or `--max NNN` in this example.
After parsing the arguments the `argv` var is set with local scope to any values not already consumed during flag processing. If there are not unbound values the var is set but `count $argv` will be zero.
If an error occurs during argparse processing it will exit with a non-zero status and print error messages to stderr.
\subsection argparse-notes Notes
Prior to the addition of this builtin command in the 2.7.0 release there were two main ways to parse the arguments passed to a fish script or function. One way was to use the OS provided `getopt` command. The problem with that is that the GNU and BSD implementations are not compatible. Which makes using that external command difficult other than in trivial situations. The other way is to iterate over `$argv` and use the fish `switch` statement to decide how to handle the argument. That, however, involves a huge amount of boilerplate code. It is also borderline impossible to implement the same behavior as builtin commands.

BIN
doc_src/ascii_fish.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 12 KiB

46
doc_src/begin.txt
View File

@@ -1,46 +0,0 @@
\section begin begin - start a new block of code
\subsection begin-synopsis Synopsis
\fish{synopsis}
begin; [COMMANDS...;] end
\endfish
\subsection begin-description Description
`begin` is used to create a new block of code.
A block allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like `and`.
The block is unconditionally executed. `begin; ...; end` is equivalent to `if true; ...; end`.
`begin` does not change the current exit status itself. After the block has completed, `$status` will be set to the status returned by the most recent command.
\subsection begin-example Example
The following code sets a number of variables inside of a block scope. Since the variables are set inside the block and have local scope, they will be automatically deleted when the block ends.
\fish
begin
set -l PIRATE Yarrr
...
end
echo $PIRATE
# This will not output anything, since the PIRATE variable
# went out of scope at the end of the block
\endfish
In the following code, all output is redirected to the file out.html.
\fish
begin
echo $xml_header
echo $html_header
if test -e $file
...
end
...
end > out.html
\endfish

170
doc_src/bind.txt
View File

@@ -1,170 +0,0 @@
\section bind bind - handle fish key bindings
\subsection bind-synopsis Synopsis
\fish{synopsis}
bind [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE]
[--preset | --user]
[(-s | --silent)] [(-k | --key)] SEQUENCE COMMAND [COMMAND...]
bind [(-M | --mode) MODE] [(-k | --key)] [--preset] [--user] SEQUENCE
bind (-K | --key-names) [(-a | --all)] [--preset] [--user]
bind (-f | --function-names)
bind (-L | --list-modes)
bind (-e | --erase) [(-M | --mode) MODE]
[--preset] [--user]
(-a | --all | [(-k | --key)] SEQUENCE [SEQUENCE...])
\endfish
\subsection bind-description Description
`bind` adds a binding for the specified key sequence to the specified command.
SEQUENCE is the character sequence to bind to. These should be written as <a href="index.html#escapes">fish escape sequences</a>. For example, because pressing the Alt key and another character sends that character prefixed with an escape character, Alt-based key bindings can be written using the `\e` escape. For example, @key{Alt,w} can be written as `\ew`. The control character can be written in much the same way using the `\c` escape, for example @key{Control,X} (^X) can be written as `\cx`. Note that Alt-based key bindings are case sensitive and Control-based key bindings are not. This is a constraint of text-based terminals, not `fish`.
The default key binding can be set by specifying a `SEQUENCE` of the empty string (that is, ```''``` ). It will be used whenever no other binding matches. For most key bindings, it makes sense to use the `self-insert` function (i.e. ```bind '' self-insert```) as the default keybinding. This will insert any keystrokes not specifically bound to into the editor. Non- printable characters are ignored by the editor, so this will not result in control sequences being printable.
If the `-k` switch is used, the name of the key (such as 'down', 'up' or 'backspace') is used instead of a sequence. The names used are the same as the corresponding curses variables, but without the 'key_' prefix. (See `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.
`COMMAND` can be any fish command, but it can also be one of a set of special input functions. These include functions for moving the cursor, operating on the kill-ring, performing tab completion, etc. Use `bind --function-names` for a complete list of these input functions.
When `COMMAND` is a shellscript command, it is a good practice to put the actual code into a <a href="#function">function</a> and simply bind to the function name. This way it becomes significantly easier to test the function while editing, and the result is usually more readable as well.
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).
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.
To save custom keybindings, put the `bind` statements into <a href="index.html#initialization">config.fish</a>. 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:
- `-k` or `--key` Specify a key name, such as 'left' or 'backspace' instead of a character sequence
- `-K` or `--key-names` Display a list of available key names. Specifying `-a` or `--all` includes keys that don't have a known mapping
- `-f` or `--function-names` Display a list of available input functions
- `-L` or `--list-modes` Display a list of defined bind modes
- `-M MODE` or `--mode MODE` Specify a bind mode that the bind is used in. Defaults to "default"
- `-m NEW_MODE` or `--sets-mode NEW_MODE` Change the current mode to `NEW_MODE` after this binding is executed
- `-e` or `--erase` Erase the binding with the given sequence and mode instead of defining a new one. Multiple sequences can be specified with this flag. Specifying `-a` or `--all` with `-M` or `--mode` erases all binds in the given mode regardless of sequence. Specifying `-a` or `--all` without `-M` or `--mode` erases all binds in all modes regardless of sequence.
- `-a` or `--all` See `--erase` and `--key-names`
- `--preset` and `--user` specify if bind should operate on user or preset bindings. User bindings take precedence over preset bindings when fish looks up mappings. By default, all `bind` invocations work on the "user" level except for listing, which will show both levels. All invocations except for inserting new bindings can operate on both levels at the same time. `--preset` should only be used in full binding sets (like when working on `fish_vi_key_bindings`).
\subsection bind-functions Special input functions
The following special input functions are available:
- `accept-autosuggestion`, accept the current autosuggestion completely
- `backward-char`, moves one character to the left
- `backward-bigword`, move one whitespace-delimited word to the left
- `backward-delete-char`, deletes one character of input to the left of the cursor
- `backward-kill-bigword`, move the whitespace-delimited word to the left of the cursor to the killring
- `backward-kill-line`, move everything from the beginning of the line to the cursor to the killring
- `backward-kill-path-component`, move one path component to the left of the cursor (everything from the last "/" or whitespace exclusive) to the killring
- `backward-kill-word`, move the word to the left of the cursor to the killring
- `backward-word`, move one word to the left
- `beginning-of-buffer`, moves to the beginning of the buffer, i.e. the start of the first line
- `beginning-of-history`, move to the beginning of the history
- `beginning-of-line`, move to the beginning of the line
- `begin-selection`, start selecting text
- `capitalize-word`, make the current word begin with a capital letter
- `complete`, guess the remainder of the current token
- `complete-and-search`, invoke the searchable pager on completion options (for convenience, this also moves backwards in the completion pager)
- `delete-char`, delete one character to the right of the cursor
- `downcase-word`, make the current word lowercase
- `end-of-buffer`, moves to the end of the buffer, i.e. the end of the first line
- `end-of-history`, move to the end of the history
- `end-of-line`, move to the end of the line
- `end-selection`, end selecting text
- `forward-bigword`, move one whitespace-delimited word to the right
- `forward-char`, move one character to the right
- `forward-word`, move one word to the right
- `history-search-backward`, search the history for the previous match
- `history-search-forward`, search the history for the next match
- `kill-bigword`, move the next whitespace-delimited word to the killring
- `kill-line`, move everything from the cursor to the end of the line to the killring
- `kill-selection`, move the selected text to the killring
- `kill-whole-line`, move the line to the killring
- `kill-word`, move the next word to the killring
- `pager-toggle-search`, toggles the search field if the completions pager is visible.
- `suppress-autosuggestion`, remove the current autosuggestion
- `swap-selection-start-stop`, go to the other end of the highlighted text without changing the selection
- `transpose-chars`, transpose two characters to the left of the cursor
- `transpose-words`, transpose two words to the left of the cursor
- `upcase-word`, make the current word uppercase
- `yank`, insert the latest entry of the killring into the buffer
- `yank-pop`, rotate to the previous entry of the killring
\subsection bind-example Examples
\fish
bind <asis>\\cd</asis> 'exit'
\endfish
Causes `fish` to exit when @key{Control,D} is pressed.
\fish
bind -k ppage history-search-backward
\endfish
Performs a history search when the @key{Page Up} key is pressed.
\fish
set -g fish_key_bindings fish_vi_key_bindings
bind -M insert \\cc kill-whole-line force-repaint
\endfish
Turns on Vi key bindings and rebinds @key{Control,C} to clear the input line.
\subsection special-case-escape Special Case: The escape Character
The escape key can be used standalone, for example, to switch from insertion mode to normal mode when using Vi keybindings. Escape may also be used as a "meta" key, to indicate the start of an escape sequence, such as function or arrow keys. Custom bindings can also be defined that begin with an escape character.
fish waits for a period after receiving the escape character, to determine whether it is standalone or part of an escape sequence. While waiting, additional key presses make the escape key behave as a meta key. If no other key presses come in, it is handled as a standalone escape. The waiting period is set to 300 milliseconds (0.3 seconds) in the default key bindings and 10 milliseconds in the vi key bindings. It can be configured by setting the `fish_escape_delay_ms` variable to a value between 10 and 5000 ms. It is recommended that this be a universal variable that you set once from an interactive session.
Note: fish 2.2.0 and earlier used a default of 10 milliseconds, and provided no way to configure it. That effectively made it impossible to use escape as a meta key.

46
doc_src/block.txt
View File

@@ -1,46 +0,0 @@
\section block block - temporarily block delivery of events
\subsection block-synopsis Synopsis
\fish{synopsis}
block [OPTIONS...]
\endfish
\subsection block-description Description
`block` prevents events triggered by `fish` or the <a href="commands.html#emit">`emit`</a> command from being delivered and acted upon while the block is in place.
In functions, `block` can be useful while performing work that should not be interrupted by the shell.
The block can be removed. Any events which triggered while the block was in place will then be delivered.
Event blocks should not be confused with code blocks, which are created with `begin`, `if`, `while` or `for`
The following parameters are available:
- `-l` or `--local` Release the block automatically at the end of the current innermost code block scope
- `-g` or `--global` Never automatically release the lock
- `-e` or `--erase` Release global block
\subsection block-example Example
\fish
# Create a function that listens for events
function --on-event foo foo; echo 'foo fired'; end
# Block the delivery of events
block -g
emit foo
# No output will be produced
block -e
# 'foo fired' will now be printed
\endfish
\subsection block-notes Notes
Note that events are only received from the current fish process as there is no way to send events from one fish process to another.

25
doc_src/break.txt
View File

@@ -1,25 +0,0 @@
\section break break - stop the current inner loop
\subsection break-synopsis Synopsis
\fish{synopsis}
LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end
\endfish
\subsection break-description Description
`break` halts a currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
There are no parameters for `break`.
\subsection break-example Example
The following code searches all .c files for "smurf", and halts at the first occurrence.
\fish
for i in *.c
if grep smurf $i
echo Smurfs are present in $i
break
end
end
\endfish

14
doc_src/breakpoint.txt
View File

@@ -1,14 +0,0 @@
\section breakpoint breakpoint - Launch debug mode
\subsection breakpoint-synopsis Synopsis
\fish{synopsis}
breakpoint
\endfish
\subsection breakpoint-description Description
`breakpoint` is used to halt a running script and launch an interactive debugging prompt.
For more details, see <a href="index.html#debugging">Debugging fish scripts</a> in the `fish` manual.
There are no parameters for `breakpoint`.

24
doc_src/builtin.txt
View File

@@ -1,24 +0,0 @@
\section builtin builtin - run a builtin command
\subsection builtin-synopsis Synopsis
\fish{synopsis}
builtin [OPTIONS...] BUILTINNAME
builtin --query BUILTINNAMES...
\endfish
\subsection builtin-description Description
`builtin` forces the shell to use a builtin command, rather than a function or program.
The following parameters are available:
- `-n` or `--names` List the names of all defined builtins
- `-q` or `--query` tests if any of the specified builtins exists.
\subsection builtin-example Example
\fish
builtin jobs
# executes the jobs builtin, even if a function named jobs exists
\endfish

42
doc_src/case.txt
View File

@@ -1,42 +0,0 @@
\section case case - conditionally execute a block of commands
\subsection case-synopsis Synopsis
\fish{synopsis}
switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
\endfish
\subsection case-description Description
`switch` executes one of several blocks of commands, depending on whether a specified value matches one of several values. `case` is used together with the `switch` statement in order to determine which block should be executed.
Each `case` command is given one or more parameters. The first `case` command with a parameter that matches the string specified in the switch command will be evaluated. `case` parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expansion using filenames.
Note that fish does not fall through on case statements. Only the first matching case is executed.
Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter.
\subsection case-example Example
Say \$animal contains the name of an animal. Then this code would classify it:
\fish
switch $animal
case cat
echo evil
case wolf dog human moose dolphin whale
echo mammal
case duck goose albatross
echo bird
case shark trout stingray
echo fish
# Note that the next case has a wildcard which is quoted
case '*'
echo I have no idea what a $animal is
end
\endfish
If the above code was run with `$animal` set to `whale`, the output
would be `mammal`.
If `$animal` was set to "banana", it would print "I have no idea what a banana is".

33
doc_src/cd.txt
View File

@@ -1,33 +0,0 @@
\section cd cd - change directory
\subsection cd-synopsis Synopsis
\fish{synopsis}
cd [DIRECTORY]
\endfish
\subsection cd-description Description
`cd` changes the current working directory.
If `DIRECTORY` is supplied, it will become the new directory. If no parameter is given, the contents of the `HOME` environment variable will be used.
If `DIRECTORY` is a relative path, the paths found in the `CDPATH` environment variable array will be tried as prefixes for the specified path.
Note that the shell will attempt to change directory without requiring `cd` if the name of a directory is provided (starting with `.`, `/` or `~`, or ending with `/`).
Fish also ships a wrapper function around the builtin `cd` that understands `cd -` as changing to the previous directory. See also <a href="commands.html#prevd">`prevd`</a>. This wrapper function maintains a history of the 25 most recently visited directories in the `$dirprev` and `$dirnext` global variables. If you make those universal variables your `cd` history is shared among all fish instances.
As a special case, `cd .` is equivalent to `cd $PWD`, which is useful in cases where a mountpoint has been recycled or a directory has been removed and recreated.
\subsection cd-example Examples
\fish
cd
# changes the working directory to your home directory.
cd /usr/src/fish-shell
# changes the working directory to /usr/src/fish-shell
\endfish
\subsection cd-see-also See Also
See also the <a href="commands.html#cdh">`cdh`</a> command for changing to a recently visited directory.

16
doc_src/cdh.txt
View File

@@ -1,16 +0,0 @@
\section cdh cdh - change to a recently visited directory
\subsection cdh-synopsis Synopsis
\fish{synopsis}
cdh [ directory ]
\endfish
\subsection cdh-description Description
`cdh` with no arguments presents a list of recently visited directories. You can then select one of the entries by letter or number. You can also press @key{tab} to use the completion pager to select an item from the list. If you give it a single argument it is equivalent to `cd directory`.
Note that the `cd` command limits directory history to the 25 most recently visited directories. The history is stored in the `$dirprev` and `$dirnext` variables which this command manipulates. If you make those universal variables your `cd` history is shared among all fish instances.
\subsection cdh-see-also See Also
See also the <a href="commands.html#prevd">`prevd`</a> and <a href="commands.html#pushd">`pushd`</a> commands which also work with the recent `cd` history and are provided for compatibility with other shells.

30
doc_src/command.txt
View File

@@ -1,30 +0,0 @@
\section command command - run a program
\subsection command-synopsis Synopsis
\fish{synopsis}
command [OPTIONS] COMMANDNAME [ARGS...]
\endfish
\subsection command-description Description
`command` forces the shell to execute the program `COMMANDNAME` and ignore any functions or builtins with the same name.
The following options are available:
- `-a` or `--all` returns all the external commands that are found in `$PATH` in the order they are found.
- `-q` or `--quiet`, silences the output and prints nothing, setting only the exit code. Implies `--search`.
- `-s` or `--search` returns the name of the external command that would be executed, or nothing if no file with the specified name could be found in the `$PATH`.
With the `-s` option, `command` treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 1 if no commands could be found. Additionally passing a `-q` or `--quiet` option prevents any paths from being printed, like `type -q`, for testing only the exit status.
For basic compatibility with POSIX `command`, the `-v` flag is recognized as an alias for `-s`.
\subsection command-example Examples
`command ls` causes fish to execute the `ls` program, even if an `ls` function exists.
`command -s ls` returns the path to the `ls` program.
`command -q git; and command git log` runs `git log` only if `git` exists.

82
doc_src/commandline.txt
View File

@@ -1,82 +0,0 @@
\section commandline commandline - set or get the current command line buffer
\subsection commandline-synopsis Synopsis
\fish{synopsis}
commandline [OPTIONS] [CMD]
\endfish
\subsection commandline-description Description
`commandline` can be used to set or get the current contents of the command line buffer.
With no parameters, `commandline` returns the current value of the command line.
With `CMD` specified, the command line buffer is erased and replaced with the contents of `CMD`.
The following options are available:
- `-C` or `--cursor` set or get the current cursor position, not the contents of the buffer. If no argument is given, the current cursor position is printed, otherwise the argument is interpreted as the new cursor position.
- `-f` or `--function` inject readline functions into the reader. This option cannot be combined with any other option. It will cause any additional arguments to be interpreted as readline functions, and these functions will be injected into the reader, so that they will be returned to the reader before any additional actual key presses are read.
The following options change the way `commandline` updates the command line buffer:
- `-a` or `--append` do not remove the current commandline, append the specified string at the end of it
- `-i` or `--insert` do not remove the current commandline, insert the specified string at the current cursor position
- `-r` or `--replace` remove the current commandline and replace it with the specified string (default)
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
- `-p` or `--current-process` select the current process
- `-s` or `--current-selection` selects the current selection
- `-t` or `--current-token` select the current token
The following options change the way `commandline` prints the current commandline buffer:
- `-c` or `--cut-at-cursor` only print selection up until the current cursor position
- `-o` or `--tokenize` tokenize the selection and print one string-type token per line
If `commandline` is called during a call to complete a given string using `complete -C STRING`, `commandline` will consider the specified string to be the current contents of the command line.
The following options output metadata about the commandline state:
- `-L` or `--line` print the line that the cursor is on, with the topmost line starting at 1
- `-S` or `--search-mode` evaluates to true if the commandline is performing a history search
- `-P` or `--paging-mode` evaluates to true if the commandline is showing pager contents, such as tab completions
\subsection commandline-example Example
`commandline -j $history[3]` replaces the job under the cursor with the third item from the command line history.
If the commandline contains
\fish
>_ echo $fl___ounder >&2 | less; and echo $catfish
\endfish
(with the cursor on the "o" of "flounder")
Then the following invocations behave like this:
\fish
>_ commandline -t
$flounder
>_ commandline -ct
$fl
>_ commandline -b # or just commandline
echo $flounder >&2 | less; and echo $catfish
>_ commandline -p
echo $flounder >&2
>_ commandline -j
echo $flounder >&2 | less
\endfish

38
doc_src/commands.hdr.in
View File

@@ -1,38 +0,0 @@
/**
\page commands Commands
\htmlonly[block]
<div class="fish_left_bar">
<div class="logo"></div>
<div class="menu commands_menu">
\endhtmlonly
@command_list_toc@
\htmlonly[block]
</div>
</div>
<div class="commands fish_right_bar">
<h1 class="interior_title">Command reference</h1>
\endhtmlonly
`fish` ships with a large number of builtin commands, shellscript functions and external commands. These are all described below.
Almost all fish commands respond to the `-h` or `--help` options to display their relevant help, also accessible using the `help` and `man` commands, like so:
\fish
echo -h
echo --help
# Prints help to the terminal window
man echo
# Displays the man page in the system pager
# (normally 'less', 'more' or 'most').
help echo
# Open a web browser to show the relevant documentation
\endfish
@command_list@
\htmlonly[block]
</div>
\endhtmlonly
*/

131
doc_src/complete.txt
View File

@@ -1,131 +0,0 @@
\section complete complete - edit command specific tab-completions
\subsection complete-synopsis Synopsis
\fish{synopsis}
complete ( -c | --command | -p | --path ) COMMAND
[( -c | --command | -p | --path ) COMMAND]...
[( -e | --erase )]
[( -s | --short-option ) SHORT_OPTION]...
[( -l | --long-option | -o | --old-option ) LONG_OPTION]...
[( -a | --arguments ) OPTION_ARGUMENTS]
[( -k | --keep-order )]
[( -f | --no-files )]
[( -r | --require-parameter )]
[( -x | --exclusive )]
[( -w | --wraps ) WRAPPED_COMMAND]...
[( -n | --condition ) CONDITION]
[( -d | --description ) DESCRIPTION]
complete ( -C[STRING] | --do-complete[=STRING] )
\endfish
\subsection complete-description Description
For an introduction to specifying completions, see <a
href='index.html#completion-own'>Writing your own completions</a> in
the fish manual.
- `COMMAND` is the name of the command for which to add a completion.
- `SHORT_OPTION` is a one character option for the command.
- `LONG_OPTION` is a multi character option for the command.
- `OPTION_ARGUMENTS` is parameter containing a space-separated list of possible option-arguments, which may contain command substitutions.
- `DESCRIPTION` is a description of what the option and/or option arguments do.
- `-c COMMAND` or `--command COMMAND` specifies that `COMMAND` is the name of the command.
- `-p COMMAND` or `--path COMMAND` specifies that `COMMAND` is the absolute path of the program (optionally containing wildcards).
- `-e` or `--erase` deletes the specified completion.
- `-s SHORT_OPTION` or `--short-option=SHORT_OPTION` adds a short option to the completions list.
- `-l LONG_OPTION` or `--long-option=LONG_OPTION` adds a GNU style long option to the completions list.
- `-o LONG_OPTION` or `--old-option=LONG_OPTION` adds an old style long option to the completions list (See below for details).
- `-a OPTION_ARGUMENTS` or `--arguments=OPTION_ARGUMENTS` adds the specified option arguments to the completions list.
- `-k` or `--keep-order` preserves the order of the `OPTION_ARGUMENTS` specified via `-a` or `--arguments` instead of sorting alphabetically.
- `-f` or `--no-files` specifies that the options specified by this completion may not be followed by a filename.
- `-r` or `--require-parameter` specifies that the options specified by this completion always must have an option argument, i.e. may not be followed by another option.
- `-x` or `--exclusive` implies both `-r` and `-f`.
- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the specified command to inherit completions from the wrapped command (See below for details).
- `-n` or `--condition` specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases.
- `-CSTRING` or `--do-complete=STRING` makes complete try to find all possible completions for the specified string.
- `-C` or `--do-complete` with no argument makes complete try to find all possible completions for the current command line buffer. If the shell is not in interactive mode, an error is returned.
- `-A` and `--authoritative` no longer do anything and are silently ignored.
- `-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:
- Short options, like '`-a`'. Short options are a single character long, are preceded by a single hyphen and may be grouped together (like '`-la`', which is equivalent to '`-l -a`'). Option arguments may be specified in the following parameter ('`-w 32`') or by appending the option with the value ('`-w32`').
- Old style long options, like '`-Wall`'. Old style long options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified in the following parameter ('`-ao null`').
- GNU style long options, like '`--colors`'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('`--quoting-style shell`') or by appending the option with a '`=`' and the value ('`--quoting-style=shell`'). GNU style long options may be abbreviated so long as the abbreviation is unique ('`--h`') is equivalent to '`--help`' if help is the only long option beginning with an 'h').
The options for specifying command name and command path may be used multiple times to define the same completions for multiple commands.
The options for specifying command switches and wrapped commands may be used multiple times to define multiple completions for the command(s) in a single call.
Invoking `complete` multiple times for the same command adds the new definitions on top of any existing completions defined for the command.
When `-a` or `--arguments` is specified in conjunction with long, short, or old style options, the specified arguments are only used as completions when attempting to complete an argument for any of the specified options. If `-a` or `--arguments` is specified without any long, short, or old style options, the specified arguments are used when completing any argument to the command (except when completing an option argument that was specified with `-r` or `--require-parameter`).
Command substitutions found in `OPTION_ARGUMENTS` are not expected to return a space-separated list of arguments. Instead they must return a newline-separated list of arguments, and each argument may optionally have a tab character followed by the argument description. Any description provided in this way overrides a description given with `-d` or `--description`.
The `-w` or `--wraps` options causes the specified command to inherit completions from another command. The inheriting command is said to "wrap" the inherited command. The wrapping command may have its own completions in addition to inherited ones. A command may wrap multiple commands, and wrapping is transitive: if A wraps B, and B wraps C, then A automatically inherits all of C's completions. Wrapping can be removed using the `-e` or `--erase` options. Note that wrapping only works for completions specified with `-c` or `--command` and are ignored when specifying completions with `-p` or `--path`.
When erasing completions, it is possible to either erase all completions for a specific command by specifying `complete -c COMMAND -e`, or by specifying a specific completion option to delete by specifying either a long, short or old style option.
\subsection complete-example Example
The short style option `-o` for the `gcc` command requires that a file follows it. This can be done using writing:
\fish
complete -c gcc -s o -r
\endfish
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:
\fish
complete -c grep -s d -x -a "read skip recurse"
\endfish
The `su` command takes any username as an argument. Usernames are given as the first colon-separated field in the file /etc/passwd. This can be specified as:
\fish
complete -x -c su -d "Username" -a "(cat /etc/passwd | cut -d : -f 1)"
\endfish
The `rpm` command has several different modes. If the `-e` or `--erase` flag has been specified, `rpm` should delete one or more packages, in which case several switches related to deleting packages are valid, like the `nodeps` switch.
This can be written as:
\fish
complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps -d "Don't check dependencies"
\endfish
where `__fish_contains_opt` is a function that checks the command line buffer for the presence of a specified set of options.
To implement an alias, use the `-w` or `--wraps` option:
\fish
complete -c hub -w git
\endfish
Now hub inherits all of the completions from git. Note this can also be specified in a function declaration.

48
doc_src/contains.txt
View File

@@ -1,48 +0,0 @@
\section contains contains - test if a word is present in a list
\subsection contains-synopsis Synopsis
\fish{synopsis}
contains [OPTIONS] KEY [VALUES...]
\endfish
\subsection contains-description Description
`contains` tests whether the set `VALUES` contains the string `KEY`. If so, `contains` exits with status 0; if not, it exits with status 1.
The following options are available:
- `-i` or `--index` print the word index
Note that, like GNU tools and most of fish's builtins, `contains` interprets all arguments starting with a `-` as options to contains, until it reaches an argument that is `--` (two dashes). See the examples below.
\subsection contains-example Example
If $animals is a list of animals, the following will test if it contains a cat:
\fish
if contains cat $animals
echo Your animal list is evil!
end
\endfish
This code will add some directories to $PATH if they aren't yet included:
\fish
for i in ~/bin /usr/local/bin
if not contains $i $PATH
set PATH $PATH $i
end
end
\endfish
While this will check if `hasargs` was run with the `-q` option:
\fish
function hasargs
if contains -- -q $argv
echo '$argv contains a -q option'
end
end
\endfish
The `--` here stops `contains` from treating `-q` to an option to itself. Instead it treats it as a normal string to check.

26
doc_src/continue.txt
View File

@@ -1,26 +0,0 @@
\section continue continue - skip the remainder of the current iteration of the current inner loop
\subsection continue-synopsis Synopsis
\fish{synopsis}
LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end
\endfish
\subsection continue-description Description
`continue` skips the remainder of the current iteration of the current inner loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
\subsection continue-example Example
The following code removes all tmp files that do not contain the word smurf.
\fish
for i in *.tmp
if grep smurf $i
continue
end
# This "rm" is skipped over if "continue" is executed.
rm $i
# As is this "echo"
echo $i
end
\endfish

25
doc_src/count.txt
View File

@@ -1,25 +0,0 @@
\section count count - count the number of elements of an array
\subsection count-synopsis Synopsis
\fish{synopsis}
count $VARIABLE
\endfish
\subsection count-description Description
`count` prints the number of arguments that were passed to it. This is usually used to find out how many elements an environment variable array contains.
`count` does not accept any options, not even `-h` or `--help`.
`count` exits with a non-zero exit status if no arguments were passed to it, and with zero if at least one argument was passed.
\subsection count-example Example
\fish
count $PATH
# Returns the number of directories in the users PATH variable.
count *.txt
# Returns the number of files in the current working directory ending with the suffix '.txt'.
\endfish

14
doc_src/dirh.txt
View File

@@ -1,14 +0,0 @@
\section dirh dirh - print directory history
\subsection dirh-synopsis Synopsis
\fish{synopsis}
dirh
\endfish
\subsection dirh-description Description
`dirh` prints the current directory history. The current position in the history is highlighted using the color defined in the `fish_color_history_current` environment variable.
`dirh` does not accept any parameters.
Note that the `cd` command limits directory history to the 25 most recently visited directories. The history is stored in the `$dirprev` and `$dirnext` variables.

15
doc_src/dirs.txt
View File

@@ -1,15 +0,0 @@
\section dirs dirs - print directory stack
\subsection dirs-synopsis Synopsis
\fish{synopsis}
dirs
dirs -c
\endfish
\subsection dirs-description Description
`dirs` prints the current directory stack, as created by the <a href="#pushd">`pushd`</a> command.
With "-c", it clears the directory stack instead.
`dirs` does not accept any parameters.

24
doc_src/disown.txt
View File

@@ -1,24 +0,0 @@
\section disown disown - remove a process from the list of jobs
\subsection disown-synopsis Synopsis
\fish{synopsis}
disown [ PID ... ]
\endfish
\subsection disown-description Description
`disown` removes the specified <a href="index.html#syntax-job-control">job</a> from the list of jobs. The job itself continues to exist, but fish does not keep track of it any longer.
Jobs in the list of jobs are sent a hang-up signal when fish terminates, which usually causes the job to terminate; `disown` allows these processes to continue regardless.
If no process is specified, the most recently-used job is removed (like `bg` and `fg`). If one or more `PID`s 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.
`disown` returns 0 if all specified jobs were disowned successfully, and 1 if any problems were encountered.
\subsection disown-example Example
`firefox &; disown` will start the Firefox web browser in the background and remove it from the job list, meaning it will not be closed when the fish process is closed.
`disown (jobs -p)` removes all jobs from the job list without terminating them.

60
doc_src/echo.txt
View File

@@ -1,60 +0,0 @@
\section echo echo - display a line of text
\subsection echo-synopsis Synopsis
\fish{synopsis}
echo [OPTIONS] [STRING]
\endfish
\subsection echo-description Description
`echo` displays a string of text.
The following options are available:
- `-n`, Do not output a newline
- `-s`, Do not separate arguments with spaces
- `-E`, Disable interpretation of backslash escapes (default)
- `-e`, Enable interpretation of backslash escapes
\subsection echo-escapes Escape Sequences
If `-e` is used, the following sequences are recognized:
- `\` backslash
- `\a` alert (BEL)
- `\b` backspace
- `\c` produce no further output
- `\e` escape
- `\f` form feed
- `\n` new line
- `\r` carriage return
- `\t` horizontal tab
- `\v` vertical tab
- `\0NNN` byte with octal value NNN (1 to 3 digits)
- `\xHH` byte with hexadecimal value HH (1 to 2 digits)
\subsection echo-example Example
\fish
echo 'Hello World'
\endfish
Print hello world to stdout
\fish
echo -e 'Top\\nBottom'
\endfish
Print Top and Bottom on separate lines, using an escape sequence

23
doc_src/else.txt
View File

@@ -1,23 +0,0 @@
\section else else - execute command if a condition is not met
\subsection else-synopsis Synopsis
\fish{synopsis}
if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
\endfish
\subsection else-description Description
`if` will execute the command `CONDITION`. If the condition's exit status is 0, the commands `COMMANDS_TRUE` will execute. If it is not 0 and `else` is given, `COMMANDS_FALSE` will be executed.
\subsection else-example Example
The following code tests whether a file `foo.txt` exists as a regular file.
\fish
if test -f foo.txt
echo foo.txt exists
else
echo foo.txt does not exist
end
\endfish

28
doc_src/emit.txt
View File

@@ -1,28 +0,0 @@
\section emit emit - Emit a generic event
\subsection emit-synopsis Synopsis
\fish{synopsis}
emit EVENT_NAME [ARGUMENTS...]
\endfish
\subsection emit-description Description
`emit` emits, or fires, an event. Events are delivered to, or caught by, special functions called event handlers. The arguments are passed to the event handlers as function arguments.
\subsection emit-example Example
The following code first defines an event handler for the generic event named 'test_event', and then emits an event of that type.
\fish
function event_test --on-event test_event
echo event test: $argv
end
emit test_event something
\endfish
\subsection emit-notes Notes
Note that events are only sent to the current fish process as there is no way to send events from one fish process to another.

19
doc_src/end.txt
View File

@@ -1,19 +0,0 @@
\section end end - end a block of commands.
\subsection end-synopsis Synopsis
\fish{synopsis}
begin; [COMMANDS...] end
if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
while CONDITION; COMMANDS...; end
for VARNAME in [VALUES...]; COMMANDS...; end
switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
\endfish
\subsection end-description Description
`end` ends a block of commands.
For more information, read the
documentation for the block constructs, such as `if`, `for` and `while`.
The `end` command does not change the current exit status. Instead, the status after it will be the status returned by the most recent command.

21
doc_src/eval.txt
View File

@@ -1,21 +0,0 @@
\section eval eval - evaluate the specified commands
\subsection eval-synopsis Synopsis
\fish{synopsis}
eval [COMMANDS...]
\endfish
\subsection eval-description Description
`eval` evaluates the specified parameters as a command. If more than one parameter is specified, all parameters will be joined using a space character as a separator.
If your command does not need access to stdin, consider using `source` instead.
\subsection eval-example Example
The following code will call the ls command. Note that `fish` does not support the use of shell variables as direct commands; `eval` can be used to work around this.
\fish
set cmd ls
eval $cmd
\endfish

15
doc_src/exec.txt
View File

@@ -1,15 +0,0 @@
\section exec exec - execute command in current process
\subsection exec-synopsis Synopsis
\fish{synopsis}
exec COMMAND [OPTIONS...]
\endfish
\subsection exec-description Description
`exec` replaces the currently running shell with a new command. On successful completion, `exec` never returns. `exec` cannot be used inside a pipeline.
\subsection exec-example Example
`exec emacs` starts up the emacs text editor, and exits `fish`. When emacs exits, the session will terminate.

12
doc_src/exit.txt
View File

@@ -1,12 +0,0 @@
\section exit exit - exit the shell
\subsection exit-synopsis Synopsis
\fish{synopsis}
exit [STATUS]
\endfish
\subsection exit-description Description
`exit` causes fish to exit. If `STATUS` is supplied, it will be converted to an integer and used as the exit code. Otherwise, the exit code will be that of the last command executed.
If exit is called while sourcing a file (using the <a href="#source">source</a> builtin) the rest of the file will be skipped, but the shell itself will not exit.

10
doc_src/false.txt
View File

@@ -1,10 +0,0 @@
\section false false - return an unsuccessful result
\subsection false-synopsis Synopsis
\fish{synopsis}
false
\endfish
\subsection false-description Description
`false` sets the exit status to 1.

306
doc_src/faq.hdr
View File

@@ -1,306 +0,0 @@
/**
\page faq Frequently asked questions
\htmlonly[block]
<div class="fish_left_bar">
<div class="logo"></div>
<div class="menu faq_menu">
\endhtmlonly
- <a href='#faq-envvar'>How do I set or clear an environment variable?</a>
- <a href='#faq-login-cmd'>How do I run a command every login? What's fish's equivalent to `.bashrc`?</a>
- <a href='#faq-prompt'>How do I set my prompt?</a>
- <a href='#faq-cmd-history'>How do I run a command from history?</a>
- <a href='#faq-subcommand'>How do I run a subcommand? The backtick doesn't work!</a>
- <a href='#faq-pkg-config'>My command (pkg-config) gives its output as a single long string?</a>
- <a href='#faq-exit-status'>How do I get the exit status of a command?</a>
- <a href='#faq-single-env'>How do I set an environment variable for just one command?</a>
- <a href='#faq-exported-uvar'>Why doesn't `set -Ux` (exported universal variables) seem to work?</a>
- <a href='#faq-customize-colors'>How do I customize my syntax highlighting colors?</a>
- <a href='#faq-update-manpage-completions'>How do I update man page completions?</a>
- <a href='#faq-cd-implicit'>I accidentally entered a directory path and fish changed directory. What happened?</a>
- <a href='#faq-open'>The open command doesn't work.</a>
- <a href='#faq-default'>How do I make fish my default shell?</a>
- <a href='#faq-titlebar'>I'm seeing weird output before each prompt when using screen. What's wrong?</a>
- <a href='#faq-greeting'>How do I change the greeting message?</a>
- <a href='#faq-history'>Why doesn't history substitution ("!$" etc.) work?</a>
- <a href='#faq-cd-minus'>How can I use `-` as a shortcut for `cd -`?</a>
- <a href='#faq-uninstalling'>How do I uninstall fish?</a>
- <a href='#faq-third-party'>Where can I find extra tools for fish?</a>
\htmlonly[block]
</div>
</div>
<div class="faq fish_right_bar">
<h1 class="interior_title">Frequently Asked Questions</h1>
\endhtmlonly
\section faq-envvar How do I set or clear an environment variable?
Use the <a href="commands.html#set">`set`</a> command:
\fish{cli-dark}
set -x key value
set -e key
\endfish
\section faq-login-cmd How do I run a command every login? What's fish's equivalent to .bashrc?
Edit the file `~/.config/fish/config.fish`, creating it if it does not exist (Note the leading period).
<hr>
\section faq-prompt How do I set my prompt?
The prompt is the output of the `fish_prompt` function. Put it in `~/.config/fish/functions/fish_prompt.fish`. For example, a simple prompt is:
\fish{cli-dark}
function fish_prompt
set_color $fish_color_cwd
echo -n (prompt_pwd)
set_color normal
echo -n ' > '
end
\endfish
You can also use the Web configuration tool, <a href="commands.html#fish_config">`fish_config`</a>, to preview and choose from a gallery of sample prompts.
\section faq-cmd-history How do I run a command from history?
Type some part of the command, and then hit the @cursor_key{&uarr;,up} or @cursor_key{&darr;,down} arrow keys to navigate through history matches.
<hr>
\section faq-subcommand How do I run a subcommand? The backtick doesn't work!
`fish` uses parentheses for subcommands. For example:
\fish{cli-dark}
for i in (ls)
echo $i
end
\endfish
\section faq-pkg-config My command (pkg-config) gives its output as a single long string?
Unlike other shells, fish splits command substitutions only on newlines, not spaces or tabs or the characters in $IFS.
That means if you run
\fish{cli-dark}
echo x(printf '%s ' a b c)x
\endfish
It will print `xa b c x`. But if you do
\fish{cli-dark}
echo x(printf '%s\n' a b c)x
\endfish
it will print `xax xbx xcx`.
In the overwhelming majority of cases, splitting on spaces is unwanted, so this is an improvement.
However sometimes, especially with `pkg-config` and related tools, splitting on spaces is needed.
In these cases use `string split " "` like:
\fish{cli-dark}
g++ example_01.cpp (pkg-config --cflags --libs gtk+-2.0 | string split " ")
\endfish
\section faq-exit-status How do I get the exit status of a command?
Use the `$status` variable. This replaces the `$?` variable used in some other shells.
\fish{cli-dark}
somecommand
if test $status -eq 7
echo "That's my lucky number!"
end
\endfish
If you are just interested in success or failure, you can run the command directly as the if-condition:
\fish{cli-dark}
if somecommand
echo "Command succeeded"
else
echo "Command failed"
end
\endfish
See the documentation for <a href="commands.html#test">`test`</a> and <a href="commands.html#if">`if`</a> for more information.
<hr>
\section faq-single-env How do I set an environment variable for just one command?
<i>`SOME_VAR=1 command` produces an error: `Unknown command "SOME_VAR=1"`.</i>
Use the `env` command.
`env SOME_VAR=1 command`
You can also declare a local variable in a block:
\fish{cli-dark}
begin
set -lx SOME_VAR 1
command
end
\endfish
\section faq-exported-uvar Why doesn't `set -Ux` (exported universal variables) seem to work?
A global variable of the same name already exists.
Environment variables such as `EDITOR` or `TZ` can be set universally using `set -Ux`. However, if
there is an environment variable already set before fish starts (such as by login scripts or system
administrators), it is imported into fish as a global variable. The <a
href="index.html#variables-scope">variable scopes</a> are searched from the "inside out", which
means that local variables are checked first, followed by global variables, and finally universal
variables.
This means that the global value takes precedence over the universal value.
To avoid this problem, consider changing the setting which fish inherits. If this is not possible,
add a statement to your <a href="index.html#">user initialization file</a> (usually
`~/.config/fish/config.fish`):
\fish{cli-dark}
set -gx EDITOR vim
\endfish
\section faq-customize-colors How do I customize my syntax highlighting colors?
Use the web configuration tool, <a href="commands.html#fish_config">`fish_config`</a>, or alter the <a href="index.html#variables-color">`fish_color` family of environment variables</a>.
<hr>
\section faq-update-manpage-completions How do I update man page completions?
Use the <a href="commands.html#fish_update_completions">`fish_update_completions`</a> command.
<hr>
\section faq-cd-implicit I accidentally entered a directory path and fish changed directory. What happened?
If fish is unable to locate a command with a given name, and it starts with '`.`', '`/`' or '`~`', fish will test if a directory of that name exists. If it does, it is implicitly assumed that you want to change working directory. For example, the fastest way to switch to your home directory is to simply press `~` and enter.
<hr>
\section faq-open The open command doesn't work.
The `open` command uses the MIME type database and the `.desktop` files used by Gnome and KDE to identify filetypes and default actions. If at least one of these environments is installed, but the open command is not working, this probably means that the relevant files are installed in a non-standard location. Consider <a href="index.html#more-help">asking for more help</a>.
<hr>
\section faq-default How do I make fish my default shell?
If you installed fish manually (e.g. by compiling it, not by using a package manager), you first need to add fish to the list of shells by executing the following command (assuming you installed fish in /usr/local):
\fish{cli-dark}
echo /usr/local/bin/fish | sudo tee -a /etc/shells
\endfish
If you installed a prepackaged version of fish, the package manager should have already done this for you.
In order to change your default shell, type:
\fish{cli-dark}
chsh -s /usr/local/bin/fish
\endfish
You may need to adjust the above path to e.g. `/usr/bin/fish`. Use the command `which fish` if you are unsure of where fish is installed.
Unfortunately, there is no way to make the changes take effect at once. You will need to log out and back in again.
<hr>
\section faq-titlebar I'm seeing weird output before each prompt when using screen. What's wrong?
Quick answer:
Run the following command in fish:
\fish{cli-dark}
function fish_title; end; funcsave fish_title
\endfish
Problem solved!
The long answer:
Fish is trying to set the titlebar message of your terminal. While screen itself supports this feature, your terminal does not. Unfortunately, when the underlying terminal doesn't support setting the titlebar, screen simply passes through the escape codes and text to the underlying terminal instead of ignoring them. It is impossible to detect and resolve this problem from inside fish since fish has no way of knowing what the underlying terminal type is. For now, the only way to fix this is to unset the titlebar message, as suggested above.
Note that fish has a default titlebar message, which will be used if the fish_title function is undefined. So simply unsetting the fish_title function will not work.
<hr>
\section faq-greeting How do I change the greeting message?
Change the value of the variable `fish_greeting` or create a `fish_greeting` function. For example, to remove the greeting use:
\fish{cli-dark}
set fish_greeting
\endfish
<hr>
\section faq-history Why doesn't history substitution ("!$" etc.) work?
Because history substitution is an awkward interface that was invented before interactive line editing was even possible. Fish drops it in favor of perfecting the interactive history recall interface. Switching requires a small change of habits: if you want to modify an old line/word, first recall it, then edit. E.g. don't type "sudo !!" - first press Up, then Home, then type "sudo ".
Fish history recall is very simple yet effective:
- As in any modern shell, the Up arrow, @cursor_key{&uarr;,Up} recalls whole lines, starting from the last line executed. A single press replaces "!!", later presses replace "!-3" and the like.
- If the line you want is far back in the history, type any part of the line and then press Up one or more times. This will constrain the recall to lines that include this text, and you will get to the line you want much faster. This replaces "!vi", "!?bar.c" and the like.
- @key{Alt,&uarr;,Up} recalls individual arguments, starting from the last argument in the last line executed. A single press replaces "!$", later presses replace "!!:4" and the like.
- If the argument you want is far back in history (e.g. 2 lines back - that's a lot of words!), type any part of it and then press @key{Alt,&uarr;,Up}. This will show only arguments containing that part and you will get what you want much faster. Try it out, this is very convenient!
- If you want to reuse several arguments from the same line ("!!:3*" and the like), consider recalling the whole line and removing what you don't need (@key{Alt,D} and @key{Alt,Backspace} are your friends).
See <a href='index.html#editor'>documentation</a> for more details about line editing in fish.
<hr>
\section faq-cd-minus How can I use `-` as a shortcut for `cd -`?
In fish versions prior to 2.5.0 it was possible to create a function named `-` that would do `cd -`. Changes in the 2.5.0 release included several bug fixes that enforce the rule that a bare hyphen is not a valid function (or variable) name. However, you can achieve the same effect via an abbreviation:
\fish{cli-dark}
abbr -a -- - 'cd -'
\endfish
<hr>
\section faq-uninstalling Uninstalling fish
Should you wish to uninstall fish, first ensure fish is not set as your shell. Run `chsh -s /bin/bash` if you are not sure.
Next, do the following (assuming fish was installed to /usr/local):
\fish{cli-dark}
rm -Rf /usr/local/etc/fish /usr/local/share/fish ~/.config/fish
rm /usr/local/share/man/man1/fish*.1
cd /usr/local/bin
rm -f fish fish_indent
\endfish
<hr>
\section faq-reserved-chars Unicode private-use characters reserved by fish
Fish reserves the <a href="http://www.unicode.org/faq/private_use.html">Unicode private-use character range</a> from U+F600 thru U+F73F for internal use. Any attempt to feed characters in that range to fish will result in them being replaced by the Unicode "replacement character" U+FFFD. This includes both interactive input as well as any file read by fish (but not programs run by fish).
<hr>
\section faq-third-party Where can I find extra tools for fish?
The fish user community extends fish in unique and useful ways via scripts that aren't always appropriate for bundling with the fish package. Typically because they solve a niche problem unlikely to appeal to a broad audience. You can find those extensions, including prompts, themes and useful functions, in various third-party repositories. These include:
- <a href="https://github.com/jorgebucaran/fisher">Fisher</a>
- <a href="https://github.com/tuvistavie/fundle">Fundle</a>
- <a href="https://github.com/oh-my-fish/oh-my-fish">Oh My Fish</a>
- <a href="https://github.com/justinmayer/tacklebox">Tacklebox</a>
This is not an exhaustive list and the fish project has no opinion regarding the merits of the repositories listed above or the scripts found therein.
\htmlonly[block]
</div>
\endhtmlonly
*/

15
doc_src/fg.txt
View File

@@ -1,15 +0,0 @@
\section fg fg - bring job to foreground
\subsection fg-synopsis Synopsis
\fish{synopsis}
fg [PID]
\endfish
\subsection fg-description Description
`fg` brings the specified <a href="index.html#syntax-job-control">job</a> to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground.
\subsection fg-example Example
`fg` will put the last job in the foreground.

34
doc_src/fish.txt
View File

@@ -1,34 +0,0 @@
\section fish fish - the friendly interactive shell
\subsection fish-synopsis Synopsis
\fish{synopsis}
fish [OPTIONS] [-c command] [FILE [ARGUMENTS...]]
\endfish
\subsection fish-description Description
`fish` is a command-line shell written mainly with interactive use in mind. The full manual is available <a href='index.html'>in HTML</a> by using the <a href='#help'>help</a> command from inside fish.
The following options are available:
- `-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-level=DEBUG_LEVEL` specify the verbosity level of fish. A higher number means higher verbosity. The default level is 1.
- `-i` or `--interactive` specify that fish is to run in interactive mode
- `-l` or `--login` specify that fish is to run as a login shell
- `-n` or `--no-execute` do not execute any commands, only perform syntax checking
- `-p` or `--profile=PROFILE_FILE` when fish exits, output timing information on all executed commands to the specified file
- `-v` or `--version` display version and exit
- `-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 feature flags (separated by a comma). These are how fish stages changes that might break scripts.
The fish exit status is generally the exit status of the last foreground command. If fish is exiting because of a parse error, the exit status is 127.

30
doc_src/fish_breakpoint_prompt.txt
View File

@@ -1,30 +0,0 @@
\section fish_breakpoint_prompt fish_breakpoint_prompt - define the appearance of the command line prompt when in the context of a `breakpoint` command
\subsection fish_breakpoint_prompt-synopsis Synopsis
\fish{synopsis}
function fish_breakpoint_prompt
...
end
\endfish
\subsection fish_breakpoint_prompt-description Description
By defining the `fish_breakpoint_prompt` function, the user can choose a custom prompt when asking for input in response to a `breakpoint` command. The `fish_breakpoint_prompt` function is executed when the prompt is to be shown, and the output is used as a prompt.
The exit status of commands within `fish_breakpoint_prompt` will not modify the value of <a href="index.html#variables-status">$status</a> outside of the `fish_breakpoint_prompt` function.
`fish` ships with a default version of this function that displays the function name and line number of the current execution context.
\subsection fish_breakpoint_prompt-example Example
A simple prompt that is a simplified version of the default debugging prompt:
\fish
function fish_breakpoint_prompt -d "Write out the debug prompt"
set -l function (status current-function)
set -l line (status current-line-number)
set -l prompt "$function:$line >"
echo -ns (set_color $fish_color_status) "BP $prompt" (set_color normal) ' '
end
\endfish

18
doc_src/fish_config.txt
View File

@@ -1,18 +0,0 @@
\section fish_config fish_config - start the web-based configuration interface
\subsection fish_config-description Description
`fish_config` starts the web-based configuration interface.
The web interface allows you to view your functions, variables and history, and to make changes to your prompt and color configuration.
`fish_config` starts a local web server and then opens a web browser window; when you have finished, close the browser window and then press the Enter key to terminate the configuration session.
`fish_config` optionally accepts name of the initial configuration tab. For e.g. `fish_config history` will start configuration interface with history tab.
If the `BROWSER` environment variable is set, it will be used as the name of the web browser to open instead of the system default.
\subsection fish_config-example Example
`fish_config` opens a new web browser window and allows you to configure certain fish settings.

28
doc_src/fish_indent.txt
View File

@@ -1,28 +0,0 @@
\section fish_indent fish_indent - indenter and prettifier
\subsection fish_indent-synopsis Synopsis
\fish{synopsis}
fish_indent [OPTIONS]
\endfish
\subsection fish_indent-description Description
`fish_indent` is used to indent a piece of fish code. `fish_indent` reads commands from standard input and outputs them to standard output or a specified file.
The following options are available:
- `-w` or `--write` indents a specified file and immediately writes to that file.
- `-i` or `--no-indent` do not indent commands; only reformat to one job per line.
- `-v` or `--version` displays the current fish version and then exits.
- `--ansi` colorizes the output using ANSI escape sequences, appropriate for the current $TERM, using the colors defined in the environment (such as `$fish_color_command`).
- `--html` outputs HTML, which supports syntax highlighting if the appropriate CSS is defined. The CSS class names are the same as the variable names, such as `fish_color_command`.
- `-d` or `--debug-level=DEBUG_LEVEL` enables debug output and specifies a verbosity level (like `fish -d`). 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.
- `--dump-parse-tree` dumps information about the parsed statements to stderr. This is likely to be of interest only to people working on the fish source code.

35
doc_src/fish_key_reader.txt
View File

@@ -1,35 +0,0 @@
\section fish_key_reader fish_key_reader - explore what characters keyboard keys send
\subsection fish_key_reader-synopsis Synopsis
\fish{synopsis}
fish_key_reader [OPTIONS]
\endfish
\subsection fish_key_reader-description Description
`fish_key_reader` is used to study input received from the terminal and can help with key binds. The program is interactive and works on standard input. Individual characters themselves and their hexadecimal values are displayed.
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 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-level=DEBUG_LEVEL` enables debug output and specifies a verbosity level (like `fish -d`). 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.
- `-h` or `--help` prints usage information.
- `-v` or `--version` prints fish_key_reader's version and exits.
\subsection fish_key_reader-usage-notes Usage Notes
The delay in milliseconds since the previous character was received is included in the diagnostic information written to stderr. This information may be useful to determine the optimal `fish_escape_delay_ms` setting or learn the amount of lag introduced by tools like `ssh`, `mosh` or `tmux`.
`fish_key_reader` intentionally disables handling of many signals. To terminate `fish_key_reader` in `--continuous` mode do:
- press `Ctrl-C` twice, or
- press `Ctrl-D` twice, or
- type `exit`, or
- type `quit`

37
doc_src/fish_mode_prompt.txt
View File

@@ -1,37 +0,0 @@
\section fish_mode_prompt fish_mode_prompt - define the appearance of the mode indicator
\subsection fish_mode_prompt-synopsis Synopsis
The fish_mode_prompt function will output the mode indicator for use in vi-mode.
\subsection fish_mode_prompt-description Description
The default `fish_mode_prompt` function will output indicators about the current Vi editor mode displayed to the left of the regular prompt. Define your own function to customize the appearance of the mode indicator. You can also define an empty `fish_mode_prompt` function to remove the Vi mode indicators. The `$fish_bind_mode variable` can be used to determine the current mode. It
will be one of `default`, `insert`, `replace_one`, or `visual`.
\subsection fish_mode_prompt-example Example
\fish
function fish_mode_prompt
switch $fish_bind_mode
case default
set_color --bold red
echo 'N'
case insert
set_color --bold green
echo 'I'
case replace_one
set_color --bold green
echo 'R'
case visual
set_color --bold brmagenta
echo 'V'
case '*'
set_color --bold red
echo '?'
end
set_color normal
end
\endfish
Outputting multiple lines is not supported in `fish_mode_prompt`.

54
doc_src/fish_opt.txt
View File

@@ -1,54 +0,0 @@
\section fish_opt fish_opt - create an option spec for the argparse command
\subsection fish_opt-synopsis Synopsis
\fish{synopsis}
fish_opt [ -h | --help ]
fish_opt ( -s X | --short=X ) [ -l LONG | --long=LONG ] [ --long-only ] \
[ -o | --optional-val ] [ -r | --required-val ] [ --multiple-vals ]
\endfish
\subsection fish_opt-description Description
This command provides a way to produce option specifications suitable for use with the <a href="#argparse">`argparse`</a> command. You can, of course, write the option specs by hand without using this command. But you might prefer to use this for the clarity it provides.
The following `argparse` options are available:
- `-s` or `--short` takes a single letter that is used as the short flag in the option being defined. This option is mandatory.
- `-l` or `--long` takes a string that is used as the long flag in the option being defined. This option is optional and has no default. If no long flag is defined then only the short flag will be allowed when parsing arguments using the option spec.
- `--long-only` means the option spec being defined will only allow the long flag name to be used. The short flag name must still be defined (i.e., `--short` must be specified) but it cannot be used when parsing args using this option spec.
- `-o` or `--optional` means the option being defined can take a value but it is optional rather than required. If the option is seen more than once when parsing arguments only the last value seen is saved. This means the resulting flag variable created by `argparse` will zero elements if no value was given with the option else it will have exactly one element.
- `-r` or `--required` means the option being defined requires a value. If the option is seen more than once when parsing arguments only the last value seen is saved. This means the resulting flag variable created by `argparse` will have exactly one element.
- `--multiple-vals` means the option being defined requires a value each time it is seen. Each instance is stored. This means the resulting flag variable created by `argparse` will have one element for each instance of this option in the args.
- `-h` or `--help` displays help about using this command.
\subsection fish_opt-examples Examples
Define a single option spec for the boolean help flag:
\fish
set -l options (fish_opt -s h -l help)
argparse $options -- $argv
\endfish
Same as above but with a second flag that requires a value:
\fish
set -l options (fish_opt -s h -l help)
set options $options (fish_opt -s m -l max --required-val)
argparse $options -- $argv
\endfish
Same as above but with a third flag that can be given multiple times saving the value of each instance seen and only the long flag name (`--token`) can be used:
\fish
set -l options (fish_opt --short=h --long=help)
set options $options (fish_opt --short=m --long=max --required-val)
set options $options (fish_opt --short=t --long=token --multiple-vals --long-only)
argparse $options -- $argv
\endfish

29
doc_src/fish_prompt.txt
View File

@@ -1,29 +0,0 @@
\section fish_prompt fish_prompt - define the appearance of the command line prompt
\subsection fish_prompt-synopsis Synopsis
\fish{synopsis}
function fish_prompt
...
end
\endfish
\subsection fish_prompt-description Description
By defining the `fish_prompt` function, the user can choose a custom prompt. The `fish_prompt` function is executed when the prompt is to be shown, and the output is used as a prompt.
The exit status of commands within `fish_prompt` will not modify the value of <a href="index.html#variables-status">$status</a> outside of the `fish_prompt` function.
`fish` ships with a number of example prompts that can be chosen with the `fish_config` command.
\subsection fish_prompt-example Example
A simple prompt:
\fish
function fish_prompt -d "Write out the prompt"
printf '%s@%s%s%s%s> ' (whoami) (hostname | cut -d . -f 1) \
(set_color $fish_color_cwd) (prompt_pwd) (set_color normal)
end
\endfish

26
doc_src/fish_right_prompt.txt
View File

@@ -1,26 +0,0 @@
\section fish_right_prompt fish_right_prompt - define the appearance of the right-side command line prompt
\subsection fish_right_prompt-synopsis Synopsis
\fish{synopsis}
function fish_right_prompt
...
end
\endfish
\subsection fish_right_prompt-description Description
`fish_right_prompt` is similar to `fish_prompt`, except that it appears on the right side of the terminal window.
Multiple lines are not supported in `fish_right_prompt`.
\subsection fish_right_prompt-example Example
A simple right prompt:
\fish
function fish_right_prompt -d "Write out the right prompt"
date '+%m/%d/%y'
end
\endfish

9
doc_src/fish_update_completions.txt
View File

@@ -1,9 +0,0 @@
\section fish_update_completions fish_update_completions - Update completions using manual pages
\subsection fish_update_completions-description Description
`fish_update_completions` parses manual pages installed on the system, and attempts to create completion files in the `fish` configuration directory.
This does not overwrite custom completions.
There are no parameters for `fish_update_completions`.

12
doc_src/fish_vi_mode.txt
View File

@@ -1,12 +0,0 @@
\section fish_vi_mode fish_vi_mode - Enable vi mode
\subsection fish_vi_mode-synopsis Synopsis
\fish{synopsis}
fish_vi_mode
\endfish
\subsection fish_vi_mode-description Description
This function is deprecated. Please call `fish_vi_key_bindings directly`
`fish_vi_mode` enters a vi-like command editing mode. To always start in vi mode, add `fish_vi_mode` to your `config.fish` file.

36
doc_src/for.txt
View File

@@ -1,36 +0,0 @@
\section for for - perform a set of commands multiple times.
\subsection for-synopsis Synopsis
\fish{synopsis}
for VARNAME in [VALUES...]; COMMANDS...; end
\endfish
\subsection for-description Description
`for` is a loop construct. It will perform the commands specified by `COMMANDS` multiple times. On each iteration, the local variable specified by `VARNAME` is assigned a new value from `VALUES`. If `VALUES` is empty, `COMMANDS` will not be executed at all. The `VARNAME` is visible when the loop terminates and will contain the last value assigned to it. If `VARNAME` does not already exist it will be set in the local scope. For our purposes if the `for` block is inside a function there must be a local variable with the same name. If the `for` block is not nested inside a function then global and universal variables of the same name will be used if they exist.
\subsection for-example Example
\fish
for i in foo bar baz; echo $i; end
# would output:
foo
bar
baz
\endfish
\subsection for-notes Notes
The `VARNAME` was local to the for block in releases prior to 3.0.0. This means that if you did something like this:
\fish
for var in a b c
if break_from_loop
break
end
end
echo $var
\endfish
The last value assigned to `var` when the loop terminated would not be available outside the loop. What `echo $var` would write depended on what it was set to before the loop was run. Likely nothing.

20
doc_src/funced.txt
View File

@@ -1,20 +0,0 @@
\section funced funced - edit a function interactively
\subsection funced-synopsis Synopsis
\fish{synopsis}
funced [OPTIONS] NAME
\endfish
\subsection funced-description Description
`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 @key{Alt,Enter}. Pressing @key{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
- `-e command` or `--editor command` Open the function body inside the text editor given by the command (for example, `-e vi`). The special command `fish` will use the built-in editor (same as specifying `-i`).
- `-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.

12
doc_src/funcsave.txt
View File

@@ -1,12 +0,0 @@
\section funcsave funcsave - save the definition of a function to the user's autoload directory
\subsection funcsave-synopsis Synopsis
\fish{synopsis}
funcsave FUNCTION_NAME
\endfish
\subsection funcsave-description Description
`funcsave` saves the current definition of a function to a file in the fish configuration directory. This function will be automatically loaded by current and future fish sessions. This can be useful if you have interactively created a new function and wish to save it for later use.
Note that because fish loads functions on-demand, saved functions will not function as <a href="index.html#event">event handlers</a> until they are run or sourced otherwise. To activate an event handler for every new shell, add the function to your <a href="index.html#initialization">shell initialization file</a> instead of using `funcsave`.

101
doc_src/function.txt
View File

@@ -1,101 +0,0 @@
\section function function - create a function
\subsection function-synopsis Synopsis
\fish{synopsis}
function NAME [OPTIONS]; BODY; end
\endfish
\subsection function-description Description
`function` creates a new function `NAME` with the body `BODY`.
A function is a list of commands that will be executed when the name of the function is given as a command.
The following options are available:
- `-a NAMES` or `--argument-names NAMES` assigns the value of successive command-line arguments to the names given in NAMES.
- `-d DESCRIPTION` or `--description=DESCRIPTION` is a description of what the function does, suitable as a completion description.
- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the function to inherit completions from the given wrapped command. See the documentation for <a href="#complete">`complete`</a> for more information.
- `-e` or `--on-event EVENT_NAME` tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.
- `-v` or `--on-variable VARIABLE_NAME` tells fish to run this function when the variable VARIABLE_NAME changes value.
- `-j PGID` or `--on-job-exit PGID` tells fish to run this function when the job with group ID PGID exits. Instead of PGID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.
- `-p PID` or `--on-process-exit PID` tells fish to run this function when the fish child process
with process ID PID exits. Instead of a PID, for backward compatibility,
"`%self`" can be specified as an alias for `$fish_pid`, and the function will be run when the
current fish instance exits.
- `-s` or `--on-signal SIGSPEC` tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP).
- `-S` or `--no-scope-shadowing` allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents is independent of the calling function.
- `-V` or `--inherit-variable NAME` snapshots the value of the variable `NAME` and defines a local variable with that same name and value when the function is 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.
If the user enters any additional arguments after the function, they are inserted into the environment <a href="index.html#variables-arrays">variable array</a> `$argv`. If the `--argument-names` option is provided, the arguments are also assigned to names specified in that option.
By using one of the event handler switches, a function can be made to run automatically at specific events. The user may generate new events using the <a href="#emit">emit</a> builtin. Fish generates the following named events:
- `fish_prompt`, which is emitted whenever a new fish prompt is about to be displayed.
- `fish_command_not_found`, which is emitted whenever a command lookup failed.
- `fish_preexec`, which is emitted right before executing an interactive command. The commandline is passed as the first parameter.
Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines.
- `fish_postexec`, which is emitted right after executing an interactive command. The commandline is passed as the first parameter.
Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines.
- `fish_exit` is emitted right before fish exits.
\subsection function-example Example
\fish
function ll
ls -l $argv
end
\endfish
will run the `ls` command, using the `-l` option, while passing on any additional files and switches to `ls`.
\fish
function mkdir -d "Create a directory and set CWD"
command mkdir $argv
if test $status = 0
switch $argv[(count $argv)]
case '-*'
case '*'
cd $argv[(count $argv)]
return
end
end
end
\endfish
This will run the `mkdir` command, and if it is successful, change the current working directory to the one just created.
\fish
function notify
set -l job (jobs -l -g)
or begin; echo "There are no jobs" >&2; return 1; end
function _notify_job_$job --on-job-exit $job --inherit-variable job
echo -n \a # beep
functions -e _notify_job_$job
end
end
\endfish
This will beep when the most recent job completes.
\subsection function-notes Notes
Note that events are only received from the current fish process as there is no way to send events from one fish process to another.

69
doc_src/functions.txt
View File

@@ -1,69 +0,0 @@
\section functions functions - print or erase functions
\subsection functions-synopsis Synopsis
\fish{synopsis}
functions [ -a | --all ] [ -n | --names ]
functions [ -D | --details ] [ -v ] FUNCTION
functions -c OLDNAME NEWNAME
functions -d DESCRIPTION FUNCTION
functions [ -e | -q ] FUNCTIONS...
\endfish
\subsection functions-description Description
`functions` prints or erases functions.
The following options are available:
- `-a` or `--all` lists all functions, even those whose name starts with an underscore.
- `-c OLDNAME NEWNAME` or `--copy OLDNAME NEWNAME` creates a new function named NEWNAME, using the definition of the OLDNAME function.
- `-d DESCRIPTION` or `--description=DESCRIPTION` changes the description of this function.
- `-e` or `--erase` causes the specified functions to be erased.
- `-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, and `n/a` if the function isn't available. If the `--verbose` option is also specified then five lines are written:
-# the pathname as already described,
-# `autoloaded`, `not-autoloaded` or `n/a`,
-# the line number within the file or zero if not applicable,
-# `scope-shadowing` if the function shadows the vars in the calling function (the normal case if it wasn't defined with `--no-scope-shadowing`), else `no-scope-shadowing`, or `n/a` if the function isn't defined,
-# the function description minimally escaped so it is a single line or `n/a` if the function isn't defined.
You should not assume that only five lines will be written since we may add additional information to the output in the future.
- `-n` or `--names` lists the names of all defined functions.
- `-q` or `--query` tests if the specified functions exist.
- `-v` or `--verbose` will make some output more verbose.
- `-H` or `--handlers` will show all event handlers.
- `-t` or `--handlers-type TYPE` will show all event handlers matching the given type
The default behavior of `functions`, when called with no arguments, is to print the names of all defined functions. Unless the `-a` option is given, no functions starting with underscores are not included in the output.
If any non-option parameters are given, the definition of the specified functions are printed.
Automatically loaded functions cannot be removed using `functions -e`. Either remove the definition file or change the $fish_function_path variable to remove autoloaded functions.
Copying a function using `-c` copies only the body of the function, and does not attach any event notifications from the original function.
Only one function's description can be changed in a single invocation of `functions -d`.
The exit status of `functions` is the number of functions specified in the argument list that do not exist, which can be used in concert with the `-q` option.
\subsection functions-example Examples
\fish
functions -n
# Displays a list of currently-defined functions
functions -c foo bar
# Copies the 'foo' function to a new function called 'bar'
functions -e bar
# Erases the function `bar`
\endfish

79
doc_src/history.txt
View File

@@ -1,79 +0,0 @@
\section history history - Show and manipulate command history
\subsection history-synopsis Synopsis
\fish{synopsis}
history search [ --show-time ] [ --case-sensitive ] [ --exact | --prefix | --contains ] [ --max=n ] [ --null ] [ -R | --reverse ] [ "search string"... ]
history delete [ --show-time ] [ --case-sensitive ] [ --exact | --prefix | --contains ] "search string"...
history merge
history save
history clear
history ( -h | --help )
\endfish
\subsection history-description Description
`history` is used to search, delete, and otherwise manipulate the history of interactive commands.
The following operations (sub-commands) are available:
- `search` returns history items matching the search string. If no search string is provided it returns all history items. This is the default operation if no other operation is specified. You only have to explicitly say `history search` if you wish to search for one of the subcommands. The `--contains` search option will be used if you don't specify a different search option. Entries are ordered newest to oldest unless you use the `--reverse` flag. If stdout is attached to a tty the output will be piped through your pager by the history function. The history builtin simply writes the results to stdout.
- `delete` deletes history items. Without the `--prefix` or `--contains` options, the exact match of the specified text will be deleted. If you don't specify `--exact` a prompt will be displayed before any items are deleted asking you which entries are to be deleted. You can enter the word "all" to delete all matching entries. You can enter a single ID (the number in square brackets) to delete just that single entry. You can enter more than one ID separated by a space to delete multiple entries. Just press [enter] to not delete anything. Note that the interactive delete behavior is a feature of the history function. The history builtin only supports `--exact --case-sensitive` deletion.
- `merge` immediately incorporates history changes from other sessions. Ordinarily `fish` ignores history changes from sessions started after the current one. This command applies those changes immediately.
- `save` immediately writes all changes to the history file. The shell automatically saves the history file; this option is provided for internal use and should not normally need to be used by the user.
- `clear` clears the history file. A prompt is displayed before the history is erased asking you to confirm you really want to clear all history unless `builtin history` is used.
The following options are available:
These flags can appear before or immediately after one of the sub-commands listed above.
- `-C` or `--case-sensitive` does a case-sensitive search. The default is case-insensitive. Note that prior to fish 2.4.0 the default was case-sensitive.
- `-c` or `--contains` searches or deletes items in the history that contain the specified text string. This is the default for the `--search` flag. This is not currently supported by the `delete` subcommand.
- `-e` or `--exact` searches or deletes items in the history that exactly match the specified text string. This is the default for the `delete` subcommand. Note that the match is case-insensitive by default. If you really want an exact match, including letter case, you must use the `-C` or `--case-sensitive` flag.
- `-p` or `--prefix` searches or deletes items in the history that begin with the specified text string. This is not currently supported by the `--delete` flag.
- `-t` or `--show-time` prepends each history entry with the date and time the entry was recorded. By default it uses the strftime format `# %c%n`. You can specify another format; e.g., `--show-time="%Y-%m-%d %H:%M:%S "` or `--show-time="%a%I%p"`. The short option, `-t`, doesn't accept a strftime format string; it only uses the default format. Any strftime format is allowed, including `%s` to get the raw UNIX seconds since the epoch.
- `-z` or `--null` causes history entries written by the search operations to be terminated by a NUL character rather than a newline. This allows the output to be processed by `read -z` to correctly handle multiline history entries.
- `-<number>` `-n <number>` or `--max=<number>` limits the matched history items to the first "n" matching entries. This is only valid for `history search`.
- `-R` or `--reverse` causes the history search results to be ordered oldest to newest. Which is the order used by most shells. The default is newest to oldest.
- `-h` or `--help` display help for this command.
\subsection history-examples Example
\fish
history clear
# Deletes all history items
history search --contains "foo"
# Outputs a list of all previous commands containing the string "foo".
history delete --prefix "foo"
# Interactively deletes commands which start with "foo" from the history.
# You can select more than one entry by entering their IDs separated by a space.
\endfish
\subsection customizing-the-histfile Customizing the name of the history file
By default interactive commands are logged to `$XDG_DATA_HOME/fish/fish_history` (typically `~/.local/share/fish/fish_history`).
You can set the `fish_history` variable to another name for the current shell session. The default value (when the variable is unset) is `fish` which corresponds to `$XDG_DATA_HOME/fish/fish_history`. If you set it to e.g. `fun`, the history would be written to `$XDG_DATA_HOME/fish/fun_history`. An empty string means history will not be stored at all. This is similar to the private session features in web browsers.
You can change `fish_history` at any time (by using `set -x fish_history "session_name"`) and it will take effect right away. If you set it to `"default"`, it will use the default session name (which is `"fish"`).
Other shells such as bash and zsh use a variable named `HISTFILE` for a similar purpose. Fish uses a different name to avoid conflicts and signal that the behavior is different (session name instead of a file path). Also, if you set the var to anything other than `fish` or `default` it will inhibit importing the bash history. That's because the most common use case for this feature is to avoid leaking private or sensitive history when giving a presentation.
\subsection history-notes Notes
If you specify both `--prefix` and `--contains` the last flag seen is used.
Note that for backwards compatibility each subcommand can also be specified as a long option. For example, rather than `history search` you can type `history --search`. Those long options are deprecated and will be removed in a future release.

39
doc_src/if.txt
View File

@@ -1,39 +0,0 @@
\section if if - conditionally execute a command
\subsection if-synopsis Synopsis
\fish{synopsis}
if CONDITION; COMMANDS_TRUE...;
[else if CONDITION2; COMMANDS_TRUE2...;]
[else; COMMANDS_FALSE...;]
end
\endfish
\subsection if-description Description
`if` will execute the command `CONDITION`. If the condition's exit status is 0, the commands `COMMANDS_TRUE` will execute. If the exit status is not 0 and `else` is given, `COMMANDS_FALSE` will be executed.
You can use <a href="#and">`and`</a> or <a href="#or">`or`</a> in the condition. See the second example below.
The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable.
\subsection if-example Example
The following code will print `foo.txt exists` if the file foo.txt exists and is a regular file, otherwise it will print `bar.txt exists` if the file bar.txt exists and is a regular file, otherwise it will print `foo.txt and bar.txt do not exist`.
\fish
if test -f foo.txt
echo foo.txt exists
else if test -f bar.txt
echo bar.txt exists
else
echo foo.txt and bar.txt do not exist
end
\endfish
The following code will print "foo.txt exists and is readable" if foo.txt is a regular file and readable
\fish
if test -f foo.txt
and test -r foo.txt
echo "foo.txt exists and is readable"
end
\endfish

1449
doc_src/index.hdr.in
View File

File diff suppressed because it is too large Load Diff

35
doc_src/isatty.txt
View File

@@ -1,35 +0,0 @@
\section isatty isatty - test if a file descriptor is a tty.
\subsection isatty-synopsis Synopsis
\fish{synopsis}
isatty [FILE DESCRIPTOR]
\endfish
\subsection isatty-description Description
`isatty` tests if a file descriptor is a tty.
`FILE DESCRIPTOR` may be either the number of a file descriptor, or one of the strings `stdin`, `stdout`, or `stderr`.
If the specified file descriptor is a tty, the exit status of the command is zero. Otherwise, the exit status is non-zero. No messages are printed to standard error.
\subsection isatty-examples Examples
From an interactive shell, the commands below exit with a return value of zero:
\fish
isatty
isatty stdout
isatty 2
echo | isatty 1
\endfish
And these will exit non-zero:
\fish
echo | isatty
isatty 9
isatty stdout > file
isatty 2 2> file
\endfish

33
doc_src/jobs.txt
View File

@@ -1,33 +0,0 @@
\section jobs jobs - print currently running jobs
\subsection jobs-synopsis Synopsis
\fish{synopsis}
jobs [OPTIONS] [PID]
\endfish
\subsection jobs-description Description
`jobs` prints a list of the currently running <a href="index.html#syntax-job-control">jobs</a> and their status.
jobs accepts the following switches:
- `-c` or `--command` prints the command name for each process in jobs.
- `-g` or `--group` only prints the group ID of each job.
- `-l` or `--last` prints only the last job to be started.
- `-p` or `--pid` prints the process ID for each process in all jobs.
- `-q` or `--quiet` prints no output for evaluation of jobs by exit code only.
On systems that supports this feature, jobs will print the CPU usage of each job since the last command was executed. The CPU usage is expressed as a percentage of full CPU activity. Note that on multiprocessor systems, the total activity may be more than 100\%.
The exit code of the `jobs` builtin is `0` if there are running background jobs and `1` otherwise.
\subsection prints no output.
\subsection jobs-example Example
`jobs` outputs a summary of the current jobs.

106
doc_src/math.txt
View File

@@ -1,106 +0,0 @@
\section math math - Perform mathematics calculations
\subsection math-synopsis Synopsis
\fish{synopsis}
math [-sN | --scale=N] [--] EXPRESSION
\endfish
\subsection math-description Description
`math` is used to perform mathematical calculations. It supports all the usual operations such as addition, subtraction, etc. As well as functions like `abs()`, `sqrt()` and `log2()`.
By default, the output is as a float with trailing zeroes trimmed. To get a fixed representation, the `--scale` option can be used, including `--scale=0` for integer output.
Keep in mind that parameter expansion takes before expressions are evaluated. This can be very useful in order to perform calculations involving shell variables or the output of command substitutions, but it also means that parenthesis (`()`) and the asterisk (`*`) glob character have to be escaped or quoted.
`math` ignores whitespace between arguments and takes its input as multiple arguments (internally joined with a space), so `math 2 +2` and `math "2 + 2"` work the same. `math 2 2` is an error.
The following options are available:
- `-sN` or `--scale=N` sets the scale of the result. `N` must be an integer. A scale of zero causes results to be rounded down to the nearest integer. So `3/2` returns `1` rather than `2` which `1.5` would normally round to. This is for compatibility with `bc` which was the basis for this command prior to fish 3.0.0. Scale values greater than zero causes the result to be rounded using the usual rules to the specified number of decimal places.
\subsection return-values Return Values
If the expression is successfully evaluated and doesn't over/underflow or return NaN the return `status` is zero (success) else one.
\subsection math-syntax Syntax
`math` knows some operators, constants, functions and can (obviously) read numbers.
For numbers, `.` is always the radix character regardless of locale - `2.5`, not `2,5`. Scientific notation (`10e5`) is also available.
\subsection math-operators Operators
`math` knows the following operators:
- `+` for addition and `-` for subtraction.
- `*` for multiplication, `/` for division. (Note that `*` is the glob character and needs to be quoted or escaped)
- `^` for exponentiation.
- `%` for modulo.
- `(` and `)` for grouping. (These need to be quoted or escaped because `()` denotes a command substitution.)
They are all used in an infix manner - `5 + 2`, not `+ 5 2`.
\subsection math-constants Constants
`math` knows the following constants:
- `e` - Euler's number.
- `pi` - You know that one. Half of Tau. (Tau is not implemented)
Use them without a leading `$` - `pi - 3` should be about 0.
\subsection math-functions Functions
`math` supports the following functions:
- `abs`
- `acos`
- `asin`
- `atan`
- `atan2`
- `ceil`
- `cos`
- `cosh`
- `exp` - the base-e exponential function
- `fac` - factorial
- `floor`
- `ln`
- `log` or `log10` - the base-10 logarithm
- `ncr`
- `npr`
- `pow(x,y)` returns x to the y (and can be written as `x ^ y`)
- `round` - rounds to the nearest integer, away from 0
- `sin`
- `sinh`
- `sqrt`
- `tan`
- `tanh`
All of the trigonometric functions use radians.
\subsection math-example Examples
`math 1+1` outputs 2.
`math $status - 128` outputs the numerical exit status of the last command minus 128.
`math 10 / 6` outputs `1.666667`.
`math -s0 10.0 / 6.0` outputs `1`.
`math -s3 10 / 6` outputs `1.666`.
`math "sin(pi)"` outputs `0`.
`math 5 \* 2` or `math "5 * 2"` or `math 5 "*" 2` all output `10`.
\subsection math-notes Compatibility notes
Fish 1.x and 2.x releases relied on the `bc` command for handling `math` expressions. Starting with fish 3.0.0 fish uses the tinyexpr library and evaluates the expression without the involvement of any external commands.
You don't need to use `--` before the expression even if it begins with a minus sign which might otherwise be interpreted as an invalid option. If you do insert `--` before the expression it will cause option scanning to stop just like for every other command and it won't be part of the expression.

32
doc_src/nextd.txt
View File

@@ -1,32 +0,0 @@
\section nextd nextd - move forward through directory history
\subsection nextd-synopsis Synopsis
\fish{synopsis}
nextd [ -l | --list ] [POS]
\endfish
\subsection nextd-description Description
`nextd` moves forwards `POS` positions in the history of visited directories; if the end of the history has been hit, a warning is printed.
If the `-l` or `--list` flag is specified, the current directory history is also displayed.
Note that the `cd` command limits directory history to the 25 most recently visited directories. The history is stored in the `$dirprev` and `$dirnext` variables which this command manipulates.
You may be interested in the <a href="commands.html#cdh">`cdh`</a> command which provides a more intuitive way to navigate to recently visited directories.
\subsection nextd-example Example
\fish
cd /usr/src
# Working directory is now /usr/src
cd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
prevd
# Working directory is now /usr/src
nextd
# Working directory is now /usr/src/fish-shell
\endfish

23
doc_src/not.txt
View File

@@ -1,23 +0,0 @@
\section not not - negate the exit status of a job
\subsection not-synopsis Synopsis
\fish{synopsis}
not COMMAND [OPTIONS...]
\endfish
\subsection not-description Description
`not` negates the exit status of another command. If the exit status is zero, `not` returns 1. Otherwise, `not` returns 0.
\subsection not-example Example
The following code reports an error and exits if no file named spoon can be found.
\fish
if not test -f spoon
echo There is no spoon
exit 1
end
\endfish

17
doc_src/open.txt
View File

@@ -1,17 +0,0 @@
\section open open - open file in its default application
\subsection open-synopsis Synopsis
\fish{synopsis}
open FILES...
\endfish
\subsection open-description Description
`open` opens a file in its default application, using the appropriate tool for the operating system. On GNU/Linux, this requires the common but optional `xdg-open` utility, from the `xdg-utils` package.
Note that this function will not be used if a command by this name exists (which is the case on macOS or Haiku).
\subsection open-example Example
`open *.txt` opens all the text files in the current directory using your system's default text editor.

23
doc_src/or.txt
View File

@@ -1,23 +0,0 @@
\section or or - conditionally execute a command
\subsection or-synopsis Synopsis
\fish{synopsis}
COMMAND1; or COMMAND2
\endfish
\subsection or-description Description
`or` is used to execute a command if the previous command was not successful (returned a status of something other than 0).
`or` statements may be used as part of the condition in an <a href="#if">`and`</a> or <a href="#while">`while`</a> block. See the documentation
for <a href="#if">`if`</a> and <a href="#while">`while`</a> for examples.
`or` does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable.
\subsection or-example Example
The following code runs the `make` command to build a program. If the build succeeds, the program is installed. If either step fails, `make clean` is run, which removes the files created by the build process.
\fish
make; and make install; or make clean
\endfish

28
doc_src/popd.txt
View File

@@ -1,28 +0,0 @@
\section popd popd - move through directory stack
\subsection popd-synopsis Synopsis
\fish{synopsis}
popd
\endfish
\subsection popd-description Description
`popd` removes the top directory from the directory stack and changes the working directory to the new top directory. Use <a href="#pushd">`pushd`</a> to add directories to the stack.
You may be interested in the <a href="commands.html#cdh">`cdh`</a> command which provides a more intuitive way to navigate to recently visited directories.
\subsection popd-example Example
\fish
pushd /usr/src
# Working directory is now /usr/src
# Directory stack contains /usr/src
pushd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
# Directory stack contains /usr/src /usr/src/fish-shell
popd
# Working directory is now /usr/src
# Directory stack contains /usr/src
\endfish

32
doc_src/prevd.txt
View File

@@ -1,32 +0,0 @@
\section prevd prevd - move backward through directory history
\subsection prevd-synopsis Synopsis
\fish{synopsis}
prevd [ -l | --list ] [POS]
\endfish
\subsection prevd-description Description
`prevd` moves backwards `POS` positions in the history of visited directories; if the beginning of the history has been hit, a warning is printed.
If the `-l` or `--list` flag is specified, the current history is also displayed.
Note that the `cd` command limits directory history to the 25 most recently visited directories. The history is stored in the `$dirprev` and `$dirnext` variables which this command manipulates.
You may be interested in the <a href="commands.html#cdh">`cdh`</a> command which provides a more intuitive way to navigate to recently visited directories.
\subsection prevd-example Example
\fish
cd /usr/src
# Working directory is now /usr/src
cd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
prevd
# Working directory is now /usr/src
nextd
# Working directory is now /usr/src/fish-shell
\endfish

70
doc_src/printf.txt
View File

@@ -1,70 +0,0 @@
\section printf printf - display text according to a format string
\subsection printf-synopsis Synopsis
\fish{synopsis}
printf format [argument...]
\endfish
\subsection printf-description Description
printf formats the string FORMAT with ARGUMENT, and displays the result.
The string FORMAT should contain format specifiers, each of which are replaced with successive arguments according to the specifier. Specifiers are detailed below, and are taken from the C library function `printf(3)`.
Unlike `echo`, `printf` does not append a new line unless it is specified as part of the string.
Valid format specifiers are:
- `%%d`: Argument will be used as decimal integer (signed or unsigned)
- `%%i`: Argument will be used as a signed integer
- `%%o`: An octal unsigned integer
- `%%u`: An unsigned decimal integer
- `%%x` or `%%X`: An unsigned hexadecimal integer
- `%%f`, `%%g` or `%%G`: A floating-point number
- `%%e` or `%%E`: A floating-point number in scientific (XXXeYY) notation
- `%%s`: A string
- `%%b`: As a string, interpreting backslash escapes, except that octal escapes are of the form \0 or \0ooo.
`%%` signifies a literal "%".
Note that conversion may fail, e.g. "102.234" will not losslessly convert to an integer, causing printf to print an error.
printf also knows a number of backslash escapes:
- `\"` double quote
- `\\` backslash
- `\a` alert (bell)
- `\b` backspace
- `\c` produce no further output
- `\e` escape
- `\f` form feed
- `\n` new line
- `\r` carriage return
- `\t` horizontal tab
- `\v` vertical tab
- `\ooo` octal number (ooo is 1 to 3 digits)
- `\xhh` hexadecimal number (hhh is 1 to 2 digits)
- `\uhhhh` 16-bit Unicode character (hhhh is 4 digits)
- `\Uhhhhhhhh` 32-bit Unicode character (hhhhhhhh is 8 digits)
The `format` argument is re-used as many times as necessary to convert all of the given arguments. If a format specifier is not appropriate for the given argument, an error is printed. For example, `printf '%d' "102.234"` produces an error, as "102.234" cannot be formatted as an integer.
This file has been imported from the printf in GNU Coreutils version 6.9. If you would like to use a newer version of printf, for example the one shipped with your OS, try `command printf`.
\subsection printf-example Example
\fish
printf '%s\\t%s\\n' flounder fish
\endfish
Will print "flounder fish" (separated with a tab character), followed by a newline character. This is useful for writing completions, as fish expects completion scripts to output the option followed by the description, separated with a tab character.
\fish
printf '%s: %d' "Number of bananas in my pocket" 42
\endfish
Will print "Number of bananas in my pocket: 42", _without_ a newline.

31
doc_src/prompt_pwd.txt
View File

@@ -1,31 +0,0 @@
\section prompt_pwd prompt_pwd - Print pwd suitable for prompt
\subsection prompt_pwd-synopsis Synopsis
\fish{synopsis}
prompt_pwd
\endfish
\subsection prompt_pwd-description Description
prompt_pwd is a function to print the current working directory in a way suitable for prompts. It will replace the home directory with "~" and shorten every path component but the last to a default of one character.
To change the number of characters per path component, set $fish_prompt_pwd_dir_length to the number of characters. Setting it to 0 or an invalid value will disable shortening entirely.
\subsection prompt_pwd-example Examples
\fish{cli-dark}
>_ cd ~/
>_ echo $PWD
<outp>/home/alfa</outp>
>_ prompt_pwd
<outp>~</outp>
>_ cd /tmp/banana/sausage/with/mustard
>_ prompt_pwd
<outp>/t/b/s/w/mustard</outp>
>_ set -g fish_prompt_pwd_dir_length 3
>_ prompt_pwd
<outp>/tmp/ban/sau/wit/mustard</outp>
\endfish

28
doc_src/psub.txt
View File

@@ -1,28 +0,0 @@
\section psub psub - perform process substitution
\subsection psub-synopsis Synopsis
\fish{synopsis}
COMMAND1 ( COMMAND2 | psub [-F | --fifo] [-f | --file] [-s SUFFIX])
\endfish
\subsection psub-description Description
Some shells (e.g., ksh, bash) feature a syntax that is a mix between command substitution and piping, called process substitution. It is used to send the output of a command into the calling command, much like command substitution, but with the difference that the output is not sent through commandline arguments but through a named pipe, with the filename of the named pipe sent as an argument to the calling program. `psub` combined with a regular command substitution provides the same functionality.
The following options are available:
- `-f` or `--file` will cause psub to use a regular file instead of a named pipe to communicate with the calling process. This will cause `psub` to be significantly slower when large amounts of data are involved, but has the advantage that the reading process can seek in the stream. This is the default.
- `-F` or `--fifo` will cause psub to use a named pipe rather than a file. You should only use this if the command produces no more than 8 KiB of output. The limit on the amount of data a FIFO can buffer varies with the OS but is typically 8 KiB, 16 KiB or 64 KiB. If you use this option and the command on the left of the psub pipeline produces more output a deadlock is likely to occur.
- `-s` or `--suffix` will append SUFFIX to the filename.
\subsection psub-example Example
\fish
diff (sort a.txt | psub) (sort b.txt | psub)
# shows the difference between the sorted versions of files `a.txt` and `b.txt`.
source-highlight -f esc (cpp main.c | psub -f -s .c)
# highlights `main.c` after preprocessing as a C source.
\endfish

44
doc_src/pushd.txt
View File

@@ -1,44 +0,0 @@
\section pushd pushd - push directory to directory stack
\subsection pushd-synopsis Synopsis
\fish{synopsis}
pushd [DIRECTORY]
\endfish
\subsection pushd-description Description
The `pushd` function adds `DIRECTORY` to the top of the directory stack and makes it the current working directory. <a href="#popd">`popd`</a> will pop it off and return to the original directory.
Without arguments, it exchanges the top two directories in the stack.
`pushd +NUMBER` rotates the stack counter-clockwise i.e. from bottom to top
`pushd -NUMBER` rotates clockwise i.e. top to bottom.
See also `dirs` and `dirs -c`.
You may be interested in the <a href="commands.html#cdh">`cdh`</a> command which provides a more intuitive way to navigate to recently visited directories.
\subsection pushd-example Example
\fish
pushd /usr/src
# Working directory is now /usr/src
# Directory stack contains /usr/src
pushd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
# Directory stack contains /usr/src /usr/src/fish-shell
pushd /tmp/
# Working directory is now /tmp
# Directory stack contains /tmp /usr/src /usr/src/fish-shell
pushd +1
# Working directory is now /usr/src
# Directory stack contains /usr/src /usr/src/fish-shell /tmp
popd
# Working directory is now /usr/src/fish-shell
# Directory stack contains /usr/src/fish-shell /tmp
\endfish

Some files were not shown because too many files have changed in this diff Show More