Built-in Aliases¶
This page describes the xonsh built-in commands and aliases.
cd¶
Changes the directory. If no directory is specified (i.e. if there are no arguments) then this changes to the current user’s home directory.
pushd¶
Adds a directory to the top of the directory stack, or rotates the stack, making the new top of the stack the current working directory.
usage: pushd [-h] [-n] [-q] [+N|-N|dir]
Adds a directory to the top of the directory stack, or rotates the stack,
making the new top of the stack the current working directory.
On Windows, if the path is a UNC path (begins with `\\<server>\<share>`) and if the `DisableUNCCheck` registry
value is not enabled, creates a temporary mapped drive letter and sets the working directory there, emulating
behavior of `PUSHD` in `CMD.EXE`
positional arguments:
+N|-N|dir * dir :
Makes dir be the top of the stack,
making it the new current directory as if it had been supplied as an argument to the cd builtin.
* +N :
Brings the Nth directory (counting from the left of the list printed by dirs, starting with zero)
to the top of the list by rotating the stack.
* -N :
Brings the Nth directory (counting from the right of the list printed by dirs, starting with zero)
to the top of the list by rotating the stack.
options:
-h, --help show this help message and exit
-n, --cd Suppresses the normal change of directory when adding directories to the stack,
so that only the stack is manipulated.
-q, --quiet Do not call dirs, regardless of $PUSHD_SILENT
popd¶
Removes entries from the directory stack.
usage: popd [-h] [-n] [-q] [+N|-N]
When no arguments are given, popd removes the top directory from the stack
and performs a cd to the new top directory.
The elements are numbered from 0 starting at the first directory listed with ``dirs``;
that is, popd is equivalent to popd +0.
positional arguments:
+N|-N Removes the Nth directory (counting from the left/right of the list printed by dirs w.r.t. -/+ prefix),
starting with zero.
options:
-h, --help show this help message and exit
-n, --cd Suppresses the normal change of directory when removing directories from the stack,
so that only the stack is manipulated.
-q, --quiet Do not call dirs, regardless of $PUSHD_SILENT
dirs¶
Displays the list of currently remembered directories. Can also be used to clear the directory stack.
usage: dirs [-h] [-c] [-p] [-v] [-l] [N]
Manage the list of currently remembered directories.
positional arguments:
N Displays the Nth directory (counting from the left/right according to +/x prefix respectively),
starting with zero
options:
-h, --help show this help message and exit
-c Clears the directory stack by deleting all of the entries.
-p Print the directory stack with one entry per line.
-v Print the directory stack with one entry per line,
prefixing each entry with its index in the stack.
-l Produces a longer listing; the default listing format
uses a tilde to denote the home directory.
jobs¶
Display a list of all current jobs.
fg¶
Bring the currently active job to the foreground, or, if a single number is given as an argument, bring that job to the foreground.
bg¶
Resume execution of the currently active job in the background, or, if a single number is given as an argument, resume that job in the background.
disown¶
The behavior of this command matches the behavior of zsh’s disown command which is as follows:
Remove the specified jobs from the job table; the shell will no longer report their status, and will not complain if you try to exit an interactive shell with them running or stopped. If no job is specified, disown the current job. If the jobs are currently stopped and the $AUTO_CONTINUE option is set ($AUTO_CONTINUE = True), a warning is printed containing information about how to make them running after they have been disowned. If one of the latter two forms is used, the jobs will automatically be made running, independent of the setting of the $AUTO_CONTINUE option.
EOF, exit, and quit¶
The commands EOF, exit, and quit all alias the same action, which is to
leave xonsh in a safe manner. Typing Ctrl-d is the same as typing EOF and
pressing enter.
exec and xexec¶
usage: xexec [-h] [-l] [-c] [-a NAME] ...
exec (also aliased as xexec) uses the os.execvpe() function to
replace the xonsh process with the specified program.
This provides the functionality of the bash 'exec' builtin::
>>> exec bash -l -i
bash $
positional arguments:
command program to launch along its arguments
options:
-h, --help show this help message and exit
-l, --login the shell places a dash at the
beginning of the zeroth argument passed to command to simulate login
shell.
-c, --clean causes command to be executed with an empty environment.
-a NAME, --name NAME the shell passes name as the zeroth argument
to the executed command.
Notes
-----
This command **is not** the same as the Python builtin function
exec(). That function is for running Python code. This command,
which shares the same name as the sh-lang statement, is for launching
a command directly in the same process. In the event of a name conflict,
please use the xexec command directly or dive into subprocess mode
explicitly with ![exec command]. For more details, please see
http://xon.sh/faq.html#exec.
source¶
Executes the contents of the provided files in the current context. This, of course, only works on xonsh and Python files.
source-bash¶
Like the source command but for Bash files. This is a thin wrapper around
the source-foreign alias where the shell argument is automatically set
to bash.
source-zsh¶
Like the source command but for ZSH files. This is a thin wrapper around
the source-foreign alias where the shell argument is automatically set
to zsh.
source-foreign¶
Like the source command but for files in foreign (non-xonsh) languages.
It will pick up the environment and any aliases.
usage: source-foreign [-h] [-i] [-l] [--envcmd ENVCMD] [--aliascmd ALIASCMD] [--extra-args EXTRA_ARGS] [-u] [-p PREVCMD] [--postcmd POSTCMD] [--funcscmd FUNCSCMD]
[--sourcer SOURCER] [--use-tmpfile] [--seterrprevcmd SETERRPREVCMD] [--seterrpostcmd SETERRPOSTCMD] [--overwrite-aliases]
[--suppress-skip-message] [--show] [-d] [-n]
shell files_or_code [files_or_code ...]
Sources a file written in a foreign shell language.
positional arguments:
shell Name or path to the foreign shell
files_or_code file paths to source or code in the target language.
options:
-h, --help show this help message and exit
-i, --interactive whether the sourced shell should be interactive
-l, --login whether the sourced shell should be login
--envcmd ENVCMD command to print environment
--aliascmd ALIASCMD command to print aliases
--extra-args EXTRA_ARGS
extra arguments needed to run the shell
-u, --unsafe whether the source shell should be run safely, and not raise any errors, even if they occur.
-p PREVCMD, --prevcmd PREVCMD
command(s) to run before any other commands, replaces traditional source.
--postcmd POSTCMD command(s) to run after all other commands
--funcscmd FUNCSCMD code to find locations of all native functions in the shell language.
--sourcer SOURCER the source command in the target shell language.
If this is not set, a default value will attempt to be
looked up based on the shell name.
--use-tmpfile whether the commands for source shell should be written to a temporary file.
--seterrprevcmd SETERRPREVCMD
command(s) to set exit-on-error before any other commands.
--seterrpostcmd SETERRPOSTCMD
command(s) to set exit-on-error after all other commands.
--overwrite-aliases flag for whether or not sourced aliases should replace the current xonsh aliases.
--suppress-skip-message
flag for whether or not skip messages should be suppressed.
--show show the script output.
-d, --dry-run Will not actually source the file.
-n, --non-interactive
Deprecated: The default mode runs in non-interactive mode.
history¶
Tools for dealing with xonsh history. See the history tutorial for more information all the history command and all of its sub-commands.
usage: history [-h] {show,id,file,info,pull,flush,off,on,clear,delete,gc,transfer} ...
Try 'history <command> --help' for more info
options:
-h, --help show this help message and exit
commands:
{show,id,file,info,pull,flush,off,on,clear,delete,gc,transfer}
show Display history of a session, default command
id Display the current session id
file Display the current history filename
info Display information about the current history
pull Pull history from other parallel sessions.
flush Flush the current history to disk
off History will not be saved for this session
on History will be saved for the rest of the session (default)
clear One-time wipe of session history
delete Delete all commands matching a pattern
gc Launches a new history garbage collector
transfer Transfer entries between history backends.
timeit¶
Runs timing study on arguments. Similar to IPython’s %timeit magic.
scp-resume¶
Simple alias defined as ['rsync', '--partial', '-h', '--progress', '--rsh=ssh'].
showcmd¶
Displays how commands and arguments are evaluated.
ipynb¶
Simple alias defined as ['ipython', 'notebook', '--no-browser'].
trace¶
Provides an interface to printing lines of source code prior to their execution.
usage: trace [-h] {on,start,add,off,stop,del,rm,color,ls} ...
Tool for tracing xonsh code as it runs.
options:
-h, --help show this help message and exit
commands:
{on,start,add,off,stop,del,rm,color,ls}
on (start, add) begins tracing selected files.
off (stop, del, rm)
removes selected files fom tracing.
color (ls) output color management for tracer
xpip¶
Runs the pip package manager for xonsh itself. Useful for installations where xonsh is in an
isolated environment (eg conda, homebrew).
In general, use xpip if you’re configuring or adding features to xonsh, and use pip if
you’re doing Python development.
xonfig¶
Manages xonsh configuration information.
usage: xonfig [-h] {info,web,wizard,styles,colors,tutorial} ...
Manage xonsh configuration.
options:
-h, --help show this help message and exit
commands:
{info,web,wizard,styles,colors,tutorial}
info Displays configuration information
web Launch configurator in browser.
wizard Launch configurator in terminal
styles Prints available xonsh color styles
colors Preview color style
tutorial Launch tutorial in browser.
xthread and xunthread¶
Use xthread and xunthread to run command as threadable or unthreadable e.g.
@ !(xthread ssh host -T "echo 1")
Windows cmd Aliases¶
The following aliases on Windows are expanded to ['cmd', '/c', alias]:
{'cls': ['cmd', '/c', 'cls'],
'copy': ['cmd', '/c', 'copy'],
'del': ['cmd', '/c', 'del'],
'dir': ['cmd', '/c', 'dir'],
'erase': ['cmd', '/c', 'erase'],
'md': ['cmd', '/c', 'md'],
'mkdir': ['cmd', '/c', 'mkdir'],
'mklink': ['cmd', '/c', 'mklink'],
'move': ['cmd', '/c', 'move'],
'rd': ['cmd', '/c', 'rd'],
'ren': ['cmd', '/c', 'ren'],
'rename': ['cmd', '/c', 'rename'],
'rmdir': ['cmd', '/c', 'rmdir'],
'time': ['cmd', '/c', 'time'],
'type': ['cmd', '/c', 'type'],
'vol': ['cmd', '/c', 'vol'],
}
activate/deactivate on Windows with Anaconda¶
On Windows with an Anaconda Python distribution, activate and
deactivate are aliased to ['source-bat activate'] and ['source-bat deactivate'].
This makes it possible to use the same commands to activate/deactivate conda environments as
in cmd.exe.
sudo on Windows¶
On Windows, if no executables named sudo are found, Xonsh adds a sudo alias
that poly fills the “run as Admin” behavior with the help of ShellExecuteEx and
ctypes. It doesn’t support any actual sudo parameters and just takes the
command to run.
ls¶
The ls command is aliased to ['ls', '--color=auto', '-v'] normally. On Mac OSX
it is instead aliased to ['ls', '-G'].
grep¶
The grep command is aliased to ['grep', '--color=auto'].
xontrib¶
Manages xonsh extensions. More information is available at Tutorial: Extensions (Xontribs)