diff --git a/doc_src/cmds/bind.rst b/doc_src/cmds/bind.rst index bdd72a46d..32d2793cc 100644 --- a/doc_src/cmds/bind.rst +++ b/doc_src/cmds/bind.rst @@ -39,7 +39,7 @@ Note that special input functions cannot be combined with ordinary shell script If no ``SEQUENCE`` is provided, all bindings (or just the bindings in the given ``MODE``) are printed. If ``SEQUENCE`` is provided but no ``COMMAND``, just the binding matching that sequence is printed. -To save custom keybindings, put the ``bind`` statements into :ref:`config.fish `. Alternatively, fish also automatically executes a function called ``fish_user_key_bindings`` if it exists. +To save custom keybindings, put the ``bind`` statements into :ref:`config.fish `. 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. diff --git a/doc_src/cmds/fish_config.rst b/doc_src/cmds/fish_config.rst index 2d3ebad30..69bb1f023 100644 --- a/doc_src/cmds/fish_config.rst +++ b/doc_src/cmds/fish_config.rst @@ -37,7 +37,7 @@ Example ``fish_config prompt show`` demos the available sample prompts. -``fish_config prompt choose disco`` makes the disco prompt the prompt for the current session. This can also be used in :ref:`config.fish ` to set the prompt. +``fish_config prompt choose disco`` makes the disco prompt the prompt for the current session. This can also be used in :ref:`config.fish ` to set the prompt. ``fish_config prompt save`` saves the current prompt to an :ref:`autoloaded ` file. diff --git a/doc_src/cmds/funcsave.rst b/doc_src/cmds/funcsave.rst index 84cdc9691..4cd56efc3 100644 --- a/doc_src/cmds/funcsave.rst +++ b/doc_src/cmds/funcsave.rst @@ -17,6 +17,6 @@ Description ``funcsave`` saves a function to a file in the fish configuration directory. This function will be :ref:`automatically loaded ` by current and future fish sessions. This can be useful if you have interactively created a new function and wish to save it for later use. -Note that because fish loads functions on-demand, saved functions will not function as :ref:`event handlers ` until they are run or sourced otherwise. To activate an event handler for every new shell, add the function to your :ref:`shell initialization file ` instead of using ``funcsave``. +Note that because fish loads functions on-demand, saved functions will not function as :ref:`event handlers ` until they are run or sourced otherwise. To activate an event handler for every new shell, add the function to your :ref:`configuration file ` instead of using ``funcsave``. This is typically used together with :ref:`funced `, which will open the function in your editor and load it in the current seession afterwards. diff --git a/doc_src/faq.rst b/doc_src/faq.rst index 6fd463c20..7721409c3 100644 --- a/doc_src/faq.rst +++ b/doc_src/faq.rst @@ -64,7 +64,7 @@ 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 :ref:`user initialization file ` (usually +add a statement to your :ref:`configuration file ` (usually ``~/.config/fish/config.fish``):: set -gx EDITOR vim @@ -306,7 +306,7 @@ This problem may show up as messages like "``Received message too long``", "``op failed: not a terminal``", "``Bad packet length``", or "``Connection refused``" with strange output in ``ssh_exchange_identification`` messages in the debug log. -This usually happens because fish reads the :ref:`user configuration file ` (``~/.config/fish/config.fish``) *always*, +This usually happens because fish reads the :ref:`user configuration file ` (``~/.config/fish/config.fish``) *always*, whether it's in an interactive or login or non-interactive or non-login shell. This simplifies matters, but it also means when config.fish generates output, it will do that even in non-interactive shells like the one ssh/scp/rsync start when they connect. diff --git a/doc_src/index.rst b/doc_src/index.rst index 7b03103fe..3f40b2229 100644 --- a/doc_src/index.rst +++ b/doc_src/index.rst @@ -102,22 +102,22 @@ For a script written in another language, just replace ``/bin/bash`` with the in This line is only needed when scripts are executed without specifying the interpreter. For functions inside fish or when executing a script with ``fish /path/to/script``, a shebang is not required (but it doesn't hurt!). -.. _initialization: +.. _configuration: -Initialization files +Configuration files ==================== -On startup, Fish evaluates a number of configuration files, which can be used to control the behavior of the shell. The location of these is controlled by a number of environment variables, and their default or usual location is given below. +When fish is started, it reads and runs its configuration files. Where these are depends on build configuration and environment variables. + +The main file is ``~/.config/fish/config.fish`` (or more precisely ``$XDG_CONFIG_HOME/fish/config.fish``). Configuration files are evaluated in the following order: -- Configuration shipped with fish, which should not be edited, in ``$__fish_data_dir/config.fish`` (usually ``/usr/share/fish/config.fish``). - - Configuration snippets in files ending in ``.fish``, in the directories: - ``$__fish_config_dir/conf.d`` (by default, ``~/.config/fish/conf.d/``) - ``$__fish_sysconf_dir/conf.d`` (by default, ``/etc/fish/conf.d/``) - - Directories for third-party software vendors to ship their own configuration snippets for their software. Fish searches the directories in the ``XDG_DATA_DIRS`` environment variable for a ``fish/vendor_conf.d`` directory; if this variable is not defined, the default is usually to search ``/usr/share/fish/vendor_conf.d`` and ``/usr/local/share/fish/vendor_conf.d`` + - Directories for third-party software vendors to ship their own configuration snippets for their software. Fish searches the directories in the ``XDG_DATA_DIRS`` environment variable for a ``fish/vendor_conf.d`` directory; if that variable is not defined, the default is ``/usr/share/fish/vendor_conf.d`` and ``/usr/local/share/fish/vendor_conf.d``, unless your distribution customized this. If there are multiple files with the same name in these directories, only the first will be executed. They are executed in order of their filename, sorted (like globs) in a natural order (i.e. "01" sorts before "2"). @@ -125,10 +125,6 @@ Configuration files are evaluated in the following order: - System-wide configuration files, where administrators can include initialization that should be run for all users on the system - similar to ``/etc/profile`` for POSIX-style shells - in ``$__fish_sysconf_dir`` (usually ``/etc/fish/config.fish``). - User initialization, usually in ``~/.config/fish/config.fish`` (controlled by the ``XDG_CONFIG_HOME`` environment variable, and accessible as ``$__fish_config_dir``). -These paths are controlled by parameters set at build, install, or run time, and may vary from the defaults listed above. - -If you are unsure where to put your own customisations, use ``~/.config/fish/config.fish``. - ``~/.config/fish/config.fish`` is sourced *after* the snippets. This is so users can copy snippets and override some of their behavior. These files are all executed on the startup of every shell. If you want to run a command only on starting an interactive shell, use the exit status of the command ``status --is-interactive`` to determine if the shell is interactive. If you want to run a command only when using a login shell, use ``status --is-login`` instead. This will speed up the starting of non-interactive or non-login shells. diff --git a/doc_src/interactive.rst b/doc_src/interactive.rst index 9adffdf80..c695b1eb0 100644 --- a/doc_src/interactive.rst +++ b/doc_src/interactive.rst @@ -367,7 +367,7 @@ In addition to the standard bindings listed here, you can also define your own w # Just clear the commandline on control-c bind \cc 'commandline -r ""' -Put ``bind`` statements into :ref:`config.fish ` or a function called ``fish_user_key_bindings``. +Put ``bind`` statements into :ref:`config.fish ` or a function called ``fish_user_key_bindings``. The key sequence (the ``\cc``) here depends on your setup, in particular the terminal. To find out what the terminal sends use :ref:`fish_key_reader `:: diff --git a/doc_src/language.rst b/doc_src/language.rst index f7488bf67..aeb0ee0e0 100644 --- a/doc_src/language.rst +++ b/doc_src/language.rst @@ -972,7 +972,7 @@ To see universal variables in action, start two fish sessions side by side, and :ref:`Universal variables ` are stored in the file ``.config/fish/fish_variables``. Do not edit this file directly, as your edits may be overwritten. Edit the variables through fish scripts or by using fish interactively instead. -Do not append to universal variables in :ref:`config.fish `, because these variables will then get longer with each new shell instance. Instead, simply set them once at the command line. +Do not append to universal variables in :ref:`config.fish `, because these variables will then get longer with each new shell instance. Instead, simply set them once at the command line. .. _variables-functions: @@ -1500,7 +1500,7 @@ To specify a signal handler for the WINCH signal, write:: echo Got WINCH signal! end -Please note that event handlers only become active when a function is loaded, which means you need to otherwise :ref:`source ` or execute a function instead of relying on :ref:`autoloading `. One approach is to put it into your :ref:`initialization file `. +Please note that event handlers only become active when a function is loaded, which means you need to otherwise :ref:`source ` or execute a function instead of relying on :ref:`autoloading `. One approach is to put it into your :ref:`configuration file `. For more information on how to define new event handlers, see the documentation for the :ref:`function ` command. diff --git a/doc_src/tutorial.rst b/doc_src/tutorial.rst index 4820ccf73..2f1049fd2 100644 --- a/doc_src/tutorial.rst +++ b/doc_src/tutorial.rst @@ -710,7 +710,7 @@ It is possible to directly create functions and variables in ``config.fish`` fil However, it is more common and efficient to use autoloading functions and universal variables. -If you want to organize your configuration, fish also reads commands in .fish files in ``~/.config/fish/conf.d/``. See :ref:`initialization ` for the details. +If you want to organize your configuration, fish also reads commands in .fish files in ``~/.config/fish/conf.d/``. See :ref:`Configuration Files ` for the details. Autoloading Functions ---------------------