Main entry points of the xonsh history.

class xonsh.history.main.HistoryAlias(threadable=True, **kwargs)[source]

Try ‘history <command> –help’ for more info

exception Error(message: str, errno=1)

Special case, when raised, the traceback will not be shown. Instead the process with exit with error code and message


Exception.add_note(note) – add a note to the exception


Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.


Sub-classes should return constructed ArgumentParser

static clear()[source]

One-time wipe of session history

create_parser(func=None, has_args=False, allowed_params=None, **kwargs) ArgParser

create root parser

static delete(pattern)[source]

Delete all commands matching a pattern


regex pattern to match against command history

static diff(a, b, reopen=False, verbose=False, _stdout=None)[source]

Diff two xonsh history files


The first file to diff


The second file to diff

reopen: -r, –reopen

make lazy file loading reopen files each time

verbose: -v, –verbose

whether to print even more information

err(*args, **kwargs)

Write text to error stream

static file(_stdout)[source]

Display the current history filename

static flush(_stdout)[source]

Flush the current history to disk

static gc(size: tuple[int, str] = None, force=False, blocking=True)[source]

Launches a new history garbage collector

size-s, –size

Next two arguments represent the history size and units; e.g. “–size 8128 commands”

force-f, –force

perform garbage collection even if history much bigger than configured limit

blocking-n, –non-blocking

makes the gc non-blocking, and thus return sooner. By default it runs on main thread blocking input.

static id_cmd(_stdout)[source]

Display the current session id

static info(to_json=False, _stdout=None)[source]

Display information about the current history

to_json: -j, –json

print in JSON format

static off()[source]

History will not be saved for this session

static on()[source]

History will be saved for the rest of the session (default)

out(*args, **kwargs)

Write text to output stream

static pull(show_commands=False, _stdout=None)[source]

Pull history from other parallel sessions.

show_commands: -c, –show-commands

show pulled commands

show(session: str = 'session', slices: list[int] = None, datetime_format: str | None = None, start_time: str | None = None, end_time: str | None = None, location: str | None = None, reverse=False, numerate=False, timestamp=False, null_byte=False, _stdout=None, _stderr=None, _unparsed=None)[source]

Display history of a session, default command


The history session to get. (all is an alias for xonsh)


integer or slice notation to get only portions of history.


the datetime format to be used for filtering and printing

start_time: –start-time, +T

show only commands after timestamp

end_time: -T, –end-time

show only commands before timestamp

location: -l, –location

The history file location (bash or zsh)

reverse: -r, –reverse

Reverses the direction

numerate: -n, –numerate

Numerate each command

timestamp: -t, –ts, –time-stamp

show command timestamps

null_byte: -0, –nb, –null-byte

separate commands by the null character for piping history to external filters


remaining args from parser.parse_known_args

transfer(source: str, source_file: str | None = None, target: str | None = None, target_file: str | None = None)[source]

Transfer entries between history backends.


Name of the source history backend

source_file–source-file, –sf

Override the default location of the history file of the backend.

target–target, -t

Name of the target history backend. (default: $XONSH_HISTORY_BACKEND)

target_file–target-file, –tf

Path to the location of the history file.


It will not remove duplicate entries, use $HISTCONTROL for managing such entries.

write_to(stream: str, *args, **kwargs)
xonsh_complete(command, **kwargs)
property parser
class xonsh.history.main.SessionAction(*args, **kwargs)[source]

Set the choices lazily

xonsh.history.main.construct_history(backend=None, **kwargs) History[source]

Construct the history backend object.