mirror of
https://github.com/xonsh/xonsh.git
synced 2025-03-04 08:24:40 +01:00
81f0f50496
comes with occasional code cleanup and micro optimizations fixes `xonsh.tools.CommandCache.all_commands`
121 lines
4.6 KiB
ReStructuredText
121 lines
4.6 KiB
ReStructuredText
Static Configuration File
|
|
=========================
|
|
In addition to the run control file, xonsh allows you to have a static config file.
|
|
This JSON-formatted file lives at ``$XONSH_CONFIG_DIR/config.json``, which is
|
|
normally ``~/.config/xonsh/config.json``. The purpose of this file is to allow
|
|
users to set runtime parameters *before* anything else happens. This includes
|
|
loading data from various foreign shells or setting critical environment
|
|
variables.
|
|
|
|
This is a dictionary or JSON object at its top-level. It has the following
|
|
top-level keys. All top-level keys are optional.
|
|
|
|
``env``
|
|
--------
|
|
This is a simple string-keyed dictionary that lets you set environment
|
|
variables. For example,
|
|
|
|
.. code:: json
|
|
|
|
{"env": {
|
|
"EDITOR": "xo",
|
|
"PAGER": "more"
|
|
}
|
|
}
|
|
|
|
|
|
``xontribs``
|
|
------------
|
|
This is a list (JSON array) of xontrib names (strings) to load prior to
|
|
loading any run control files. For example,
|
|
|
|
.. code:: json
|
|
|
|
{"xontribs": ["mpl", "example"]}
|
|
|
|
|
|
``foreign_shells``
|
|
--------------------
|
|
This is a list (JSON Array) of dicts (JSON objects) that represent the
|
|
foreign shells to inspect for extra start up information, such as environment
|
|
variables, aliases, and foreign shell functions. The suite of data gathered
|
|
may be expanded in the future. Each shell dictionary unpacked and passed into
|
|
the ``xonsh.foreign_shells.foreign_shell_data()`` function. Thus, these
|
|
dictionaries have the following structure:
|
|
|
|
:shell: *str, required* - The name or path of the shell, such as "bash" or "/bin/sh".
|
|
:interactive: *bool, optional* - Whether the shell should be run in interactive mode.
|
|
``default=true``
|
|
:login: *bool, optional* - Whether the shell should be a login shell.
|
|
``default=false``
|
|
:envcmd: *str, optional* - The command to generate environment output with.
|
|
``default="env"``
|
|
:aliascmd: *str, optional* - The command to generate alias output with.
|
|
``default="alias"``
|
|
:extra_args: *list of str, optional* - Addtional command line options to pass
|
|
into the shell. ``default=[]``
|
|
:currenv: *dict or null, optional* - Manual override for the current environment.
|
|
``default=null``
|
|
:safe: *bool, optional* - Flag for whether or not to safely handle exceptions
|
|
and other errors. ``default=true``
|
|
:prevcmd: *str, optional* - An additional command or script to run before
|
|
anything else, useful for sourcing and other commands that may require
|
|
environment recovery. ``default=''``
|
|
:postcmd: *str, optional* - A command to run after everything else, useful for
|
|
cleaning up any damage that the ``prevcmd`` may have caused. ``default=''``
|
|
:funcscmd: *str or None, optional* - This is a command or script that can be
|
|
used to determine the names and locations of any functions that are native
|
|
to the foreign shell. This command should print *only* a whitespace
|
|
separated sequence of pairs function name & filenames where the functions
|
|
are defined. If this is None (null), then a default script will attempted
|
|
to be looked up based on the shell name. Callable wrappers for these
|
|
functions will be returned in the aliases dictionary. ``default=null``
|
|
:sourcer: *str or None, optional* - How to source a foreign shell file for
|
|
purposes of calling functions in that shell. If this is None, a default
|
|
value will attempt to be looked up based on the shell name. ``default=null``
|
|
:runcmd: *str or None, optional* - Command line switches to use when
|
|
running the script, such as ``-c`` for Bash and ``/C`` for cmd.exe.
|
|
``default=null``
|
|
:seterrprevcmd: *str or None, optional* - Command that enables exit-on-error
|
|
for the shell before all other commands. For example, this is "set -e" in Bash.
|
|
To disable this exit-on-error behavior, simply pass in an empty string.
|
|
``default=null``
|
|
:seterrpostcmd: *str or None, optional* - Command that enables exit-on-error
|
|
for the shell after all other commands. For example, this is
|
|
"if errorlevel 1 exit 1" in cmd.exe. To disable this exit-on-error behavior,
|
|
simply pass in an empty string. ``default=null``
|
|
|
|
|
|
Some examples can be seen below:
|
|
|
|
.. code:: json
|
|
|
|
# load bash then zsh
|
|
{"foreign_shells": [
|
|
{"shell": "/bin/bash"},
|
|
{"shell": "zsh"}
|
|
]
|
|
}
|
|
|
|
# load bash as a login shell with custom rcfile
|
|
{"foreign_shells": [
|
|
{"shell": "bash",
|
|
"login": true,
|
|
"extra_args": ["--rcfile", "/path/to/rcfile"]
|
|
}
|
|
]
|
|
}
|
|
|
|
# disable all foreign shell loading via an empty list
|
|
{"foreign_shells": []}
|
|
|
|
|
|
Putting it all together
|
|
-----------------------
|
|
The following ecample shows a fully fleshed out config file.
|
|
|
|
:download:`Download config.json <xonshconfig.json>`
|
|
|
|
.. include:: xonshconfig.json
|
|
:code: json
|
|
|