fish-shell/doc_src/cmds/source.rst

.. _cmd-source:

source - evaluate contents of file
==================================

Synopsis
--------

| **source** *FILE* [*arguments*...]
| ``somecommand`` | **source**


Description
-----------

``source`` evaluates the commands of the specified file in the current shell as a new block of code. This is different from starting a new process to perform the commands (i.e. ``fish < FILE``) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments are specified after the file name, they will be inserted into the ``$argv`` variable. The ``$argv`` variable will not include the name of the sourced file.

fish will search the working directory to resolve relative paths but will not search ``$PATH``.

If no file is specified and stdin is not the terminal, or if the file name ``-`` is used, stdin will be read.

The exit status of ``source`` is the exit status of the last job to execute. If something goes wrong while opening or reading the file, ``source`` exits with a non-zero status.

``.`` (a single period) is an alias for the ``source`` command. The use of ``.`` is deprecated in favour of ``source``, and ``.`` will be removed in a future version of fish.

``source`` creates a new :ref:`local scope<variables-scope>`; ``set --local`` within a sourced block will not affect variables in the enclosing scope.


Example
-------


::

    source ~/.config/fish/config.fish
    # Causes fish to re-read its initialization file.


Caveats
-------

In fish versions prior to 2.3.0, the ``$argv`` variable would have a single element (the name of the sourced file) if no arguments are present. Otherwise, it would contain arguments without the name of the sourced file. That behavior was very confusing and unlike other shells such as bash and zsh.
docs: Add labels to all commands This allows us to use :ref: references, which don't require hardcoding it as html [ci skip] 2019-03-31 09:05:09 +00:00			`.. _cmd-source:`

doc: homogenize commands titles 2020-03-31 15:37:38 +00:00			`source - evaluate contents of file`
			`==================================`
Switch command docs from \section to reStructuredText 2018-12-17 01:39:33 +00:00
Migrate the 'synopsis' sections to .rst format 2018-12-18 01:58:24 +00:00			`Synopsis`
			`--------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
More synopsis work. A great leap forward 2021-12-22 01:24:47 +00:00			`\| source FILE [arguments...]`
			\| ``somecommand`` \| source
Migrate the 'synopsis' sections to .rst format 2018-12-18 01:58:24 +00:00
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Convert \\subsection sections into rst format 2018-12-19 02:44:30 +00:00			`Description`
Fix command section separator line lengths 2019-01-03 04:10:47 +00:00			`-----------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
More synopsis work. A great leap forward 2021-12-22 01:24:47 +00:00			``source`` evaluates the commands of the specified file in the current shell as a new block of code. This is different from starting a new process to perform the commands (i.e. ``fish < FILE``) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments are specified after the file name, they will be inserted into the ``$argv`` variable. The ``$argv`` variable will not include the name of the sourced file.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
doc: document relative path support for `source`. [ci skip] 2019-10-14 16:00:12 +00:00			fish will search the working directory to resolve relative paths but will not search ``$PATH``.

docs: don't quote code snippets The added single quotes don't look great in HTML, and it's already clear that the monospaced text is to be interpreted literally. 2020-04-13 20:54:33 +00:00			If no file is specified and stdin is not the terminal, or if the file name ``-`` is used, stdin will be read.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
docs: standardise on exit status terminology Exit status is used in the POSIX specification and is preferred over return code/return status/exit code. [ci skip] 2019-09-17 08:31:39 +00:00			The exit status of ``source`` is the exit status of the last job to execute. If something goes wrong while opening or reading the file, ``source`` exits with a non-zero status.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			``.`` (a single period) is an alias for the ``source`` command. The use of ``.`` is deprecated in favour of ``source``, and ``.`` will be removed in a future version of fish.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
docs: source creates a new local scope Discussed in #4443. 2019-09-17 08:25:12 +00:00			``source`` creates a new :ref:`local scope<variables-scope>`; ``set --local`` within a sourced block will not affect variables in the enclosing scope.

Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Convert \\subsection sections into rst format 2018-12-19 02:44:30 +00:00			`Example`
Fix command section separator line lengths 2019-01-03 04:10:47 +00:00			`-------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch \fish sections to rst format 2018-12-19 03:14:04 +00:00

			`::`

			`source ~/.config/fish/config.fish`
			`# Causes fish to re-read its initialization file.`

Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
docs: Fix remaining "\subsection" markup See #5696. [ci skip] 2019-03-24 18:44:45 +00:00			`Caveats`
			`-------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
docs: slight grammar improvement in source docs [ci skip] 2019-09-17 08:35:33 +00:00			In fish versions prior to 2.3.0, the ``$argv`` variable would have a single element (the name of the sourced file) if no arguments are present. Otherwise, it would contain arguments without the name of the sourced file. That behavior was very confusing and unlike other shells such as bash and zsh.