xonsh/docs/xonshconfig.rst

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 alais 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