Run Control File¶

Xonsh allows you to customize your shell behavior with run control files, called “xonshrc” files. These files are written either in the Xonsh language or in Python and are executed exactly once at startup.

Xonsh RC Basics¶

The control file usually contains:

Assignment statements setting environment variables. This includes standard OS environment variables that affect other programs and many that Xonsh uses for itself.
xontrib commands to load selected add-ins (xontribs).
Xonsh function definitions.
Alias definitions, many of which invoke the above functions with specified arguments.

First of all, you need to know about the home directory ~/.xonshrc control file. This file is commonly used to put configurations for the user interactive prompt and it is executed automatically only for interactive Xonsh sessions.

There are also a few places where Xonsh looks for run control files. These files will be executed automatically in both interactive and non-interactive modes, and you need to use the $XONSH_INTERACTIVE and $XONSH_LOGIN environment variables to determine what code you want to execute in each mode. Here is the list of run control files and directories:

Cross-desktop group (XDG) compliant ~/.config/xonsh/rc.xsh control file.
The system-wide control file /etc/xonsh/xonshrc for Linux and macOS and in %ALLUSERSPROFILE%\xonsh\xonshrc on Windows. It controls options that are applied to all users of Xonsh on a given system.
The home-based directory ~/.config/xonsh/rc.d/ and system /etc/xonsh/rc.d/ can contain .xsh or .py files. They will be executed at startup in order. This allows for drop-in configuration where your configuration can be split across scripts and common and local configurations more easily separated.

In addition:

Use xonsh --no-rc to prevent using control files.
Use xonsh --rc snail.xsh to run only a certain control file.
Use xonsh -i script.xsh to run xonsh in interactive mode with loading all possible control files.
Use xonsh --rc rc1.xsh rc2.xsh -- script.xsh to run scripts with multiple control files.
You can create autoloadable xontrib as alternative to run control file and reuse it as python package.

The options set per user override settings in the system-wide control file.

xonsh RC also lets you account for the operating system, so you can ship a single file across systems and gate snippets by platform and execution mode — see Cross-platform xonsh RC.

Xonsh provides 2 wizards to create your own “xonshrc”. xonfig web provides basic settings, and xonfig wizard steps you through all the available options.

xonfig web¶

This helps you choose a color theme, customized prompt and add-in packages (“xontribs”). It initializes your personal run control file (usually at ~/.xonshrc). To invoke it (from a xonsh prompt):

@ xonfig web
Web config started at 'http://localhost:8421'. Hit Ctrl+C to stop.
127.0.0.1 - - [23/Aug/2020 15:04:39] "GET / HTTP/1.1" 200 -

This will open your default browser on a page served from a local server. You can exit the server by typing Ctrl+c at any time.

The page has:

Colors:: shows the color themes built into Xonsh. Simply click on a sample to select it. Although color names are standardized across various terminal applications, their actual appearance is not and do vary widely. Seeing is believing!
Prompts:: shows various sample prompts. It is recommended to select one but to then edit the xonshrc file to further refine your prompt.
Xontribs:: are community-contributed add-ins often used to enhance command completion and line editing, but can affect any aspect of Xonsh behavior. Choose one or more to suit your needs but note that they will require installation of additional packages. You can extend Xonsh by writing your own xontrib, and are invited/urged to do so!
Save:: Click to write the configuration choices to your ~/.xonshrc. This will add a few tagged lines to your run control file, but will not overwrite it completely, so you can run xonfig web at any time.

xonfig wizard¶

This imports settings and tools you have defined in your existing (POSIX) shell. It also walks you through setting all known environment variables and xontribs in a question-and-answer format. Run it from a xonsh prompt:

@ xonfig wizard

Real world sample xonshrc¶

The following is a real-world example of such a file.

Download xonshrc

# adjust some paths
$PATH.append('/home/snail/sandbox/bin')
$LD_LIBRARY_PATH = ['/home/snail/.local/lib', '/home/snail/miniconda3/lib', '']

# alias to quit AwesomeWM from the terminal
@aliases.register('qa')
def _quit_awesome(args, stdin=None):
    lines = $(ps ux | grep "gnome-session --session=awesome").splitlines()
    pids = [l.split()[1] for l in lines]
    for pid in pids:
        kill @(pid)

# some customization options, see https://xon.sh/envvars.html for details
$MULTILINE_PROMPT = '`·.,¸,.·*¯`·.,¸,.·*¯'
$XONSH_SHOW_TRACEBACK = True
$XONSH_STORE_STDOUT = True
$XONSH_HISTORY_MATCH_ANYWHERE = True
$COMPLETIONS_CONFIRM = True
$XONSH_AUTOPAIR = True

Real world sample rc.py¶

The following is a real-world example of such a file. This can be set by env XONSHRC=rc.py xonsh or xonsh --rc=rc.py

Download rc.py

from xonsh.built_ins import XSH

env = XSH.env
# adjust some paths
env["PATH"].append("/home/snail/sandbox/bin")
env["LD_LIBRARY_PATH"] = ["/home/snail/.local/lib", "/home/snail/miniconda3/lib"]

# alias to quit AwesomeWM from the terminal
@XSH.aliases.register("qa")
def _quit_awesome(args, stdin=None):
    print("awesome python code")

# setting aliases as list are faster since they don't involve parser.
XSH.aliases["gc"] = ["git", "commit"]

# some customization options, see https://xon.sh/envvars.html for details
env["MULTILINE_PROMPT"] = "`·.,¸,.·*¯`·.,¸,.·*¯"
env["XONSH_SHOW_TRACEBACK"] = True
env["XONSH_STORE_STDOUT"] = True
env["XONSH_HISTORY_MATCH_ANYWHERE"] = True
env["COMPLETIONS_CONFIRM"] = True
env["XONSH_AUTOPAIR"] = True

Snippets for xonshrc¶

The following are useful snippets and code that tweaks and adjust xonsh in various ways. If you have any useful tricks, feel free to share them.

Adjust how git branch label behaves¶

Xonsh adds a colored branch name to the prompt when working with git or hg repositories. This behavior can be controlled with the $PROMPT environment variable. See how to customize the prompt . The branch name changes color if the work dir is dirty or not. This is controlled by the {branch_color} formatter string.

The following snippet reimplements the formatter also to include untracked files when considering if a git directory is dirty.

from xonsh.prompt.vc import git_dirty_working_directory
$VC_GIT_INCLUDE_UNTRACKED = True
$PROMPT_FIELDS['branch_color'] = lambda: ('{BOLD_INTENSE_RED}'
                                               if git_dirty_working_directory()
                                               else '{BOLD_INTENSE_GREEN}')

Get better colors from the `ls` command¶

The colors of the ls command may be hard to read in a dark terminal. If so, this is an excellent addition to the xonshrc file.

$LS_COLORS='rs=0:di=01;36:ln=01;36:mh=00:pi=40;33:so=01;35:do=01;35:bd=40;33;01:cd=40;33;01:or=40;31;01:su=37;41:sg=30;43:ca=30;41:tw=30;42:ow=34;42:st=37;44:ex=01;32:'

Make JSON data directly pastable¶

With the following snippet, xonsh will understand JSON data such as { "name": "Tyler", "active": false, "age": null }. Note that this injects names into Python’s builtins module, which is rather hacky and might break other functionality. Use at your own risk.

import builtins
builtins.true = True
builtins.false = False
builtins.null = None

Display different date information every 10th time¶

For a compact shell prompts, some people prefer a very condensed time format. But when you have a lengthy shell session you might want the date to show up in your logs every now and then…

import time
def get_shelldate():
    get_shelldate.fulldate %= 10
    get_shelldate.fulldate += 1
    if get_shelldate.fulldate == 1:
        return time.strftime('%d%m%Y')
    return time.strftime('%H:%M')
get_shelldate.fulldate = 0

$PROMPT_FIELDS['shelldate'] = get_shelldate