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,

{"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,

{"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:

# 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 config.json

{"env": {
  "EDITOR": "xo",
  "PAGER": "more"
  },
 "xontribs": ["mpl"],
 "foreign_shells": [
  {"shell": "bash",
   "login": true,
   "extra_args": ["--rcfile", "/path/to/rcfile"]
   },
  {"shell": "zsh"}
  ]
}