.. _aliases:

********************
Built-in Aliases
********************
This page describes the xonsh built-in commands and aliases.

Well-known commands
====================

``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.


``ls``
--------------------
The ``ls`` command is aliased to ``['ls', '--color=auto', '-v']`` on Linux.  On macOS,
FreeBSD, and DragonFlyBSD it is instead aliased to ``['ls', '-G']``.
On NetBSD and OpenBSD no ``ls`` alias is defined.


``grep``
--------------------
The ``grep`` command is aliased to ``['grep', '--color=auto']``.


``timeit``
--------------------
Runs timing study on arguments. Similar to IPython's ``%timeit`` magic.


``exit``, ``quit``, ``EOF``
----------------------------------
The commands ``exit``, ``EOF`` 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.

``exit N`` sets the shell's exit code to ``N`` and stops the rest of the
current script:

.. code-block:: xonshcon

    @ xonsh -c 'echo 1; exit 42; echo 3'
    1
    @ @.lastcmd.rtn
    42


Xonsh-specific Aliases
=======================

``history``
--------------------
Tools for dealing with xonsh history. See `the history tutorial <history.html>`_
for more information all the history command and all of its sub-commands.

.. command-help:: xonsh.history.main.history_main


``showcmd``
--------------------
Displays how commands and arguments are evaluated. Use ``-e`` to expand aliases.

.. code-block:: xonshcon

    @ showcmd echo The @('args') @(['list', 'is']) $(echo here) "and" --say="hello" to @([]) you
    ['echo', 'The', 'args', 'list', 'is', 'here', 'and', '--say="hello"', 'to', 'you']
    @ showcmd ls
    ls
    @ showcmd -e ls
    ['ls', '--group-directories-first', '-A', '--color']


``xonfig``
--------------------
Manages xonsh configuration information.

.. command-help:: xonsh.xonfig.xonfig_main

``xontrib``
--------------------
Manages xonsh extensions. More information is available at :doc:`xontrib`


.. _aliases-xcontext:

``xcontext``
--------------------

.. code-block:: xonshcon

    @ xcontext
    [Current xonsh session]
    xxonsh: /home/snail/.local/xonsh-env/bin/xonsh
    xpython: /home/snail/.local/xonsh-env/bin/python # Python 3.12.10
    xpip: /home/snail/.local/xonsh-env/bin/python -m pip

    [Current commands environment]
    xonsh: /home/snail/.local/xonsh-env/bin/xonsh
    python: /usr/bin/python # Python 3.11.6
    pip: /usr/bin/pip

    CONDA_DEFAULT_ENV: my-env

Report information about the current xonsh environment, including paths to the Python interpreter, pip, xonsh itself, and relevant environment variables.

By default, symlinks in the displayed paths are resolved to their real targets; pass ``--no-resolve`` (``-n``) to show the raw paths instead.


.. _aliases-xpip:

``xpip``
--------------------
Runs the ``pip`` package manager for xonsh itself. Useful for installations where xonsh is in an
isolated environment (e.g. conda, mamba, homebrew).

.. code-block:: xonshcon

    @ which pip
    /usr/bin/pip  # system pip
    @ which xpip
    /home/snail/.local/xonsh-env/bin/python -m pip  # current xonsh session pip
    @ xpip install fire
    @ import fire
    @ fire
    <module 'fire' from '/home/snail/.local/xonsh-env/lib/python3.11/site-packages/fire/__init__.py'>


``xpython``
--------------------

Alias to the Python interpreter that is currently running xonsh (``sys.executable``). This is useful for running Python modules or scripts in the same environment as the shell itself, especially in complex setups like AppImage.

.. code-block:: xonshcon

    @ python -V
    Python 3.12.10
    @ xpython -V
    Python 3.11.9
    @ which python
    /opt/homebrew/bin/python
    @ which xpython
    /home/snail/.local/xonsh-env/bin/python


.. _aliases-xxonsh:

``xxonsh``
--------------------

Launches exactly the same ``xonsh`` that was used to start the current session.

See :ref:`launch-xxonsh` for a worked example of using it as a building block to
launch ``tmux`` with this exact xonsh (the ``xtmux`` recipe).

Mnemonic: think of the initial ‘x’ as ‘c’—xxonsh stands for (c)urrent xonsh.

``xreset``
--------------------
Clean the xonsh context. All user variables will be deleted.

.. code-block:: xonshcon
    @ a=1
    @ a
    1
    @ xreset
    @ a
    Not found


``trace``
--------------------
Provides an interface to printing lines of source code prior to their execution.

.. command-help:: xonsh.tracer.tracermain


``exec`` and  ``xexec``
-------------------------

.. command-help:: xonsh.aliases.xexec


.. _command-decorators:

Command Decorators
==================

``@error_raise`` and ``@error_ignore``
----------------------------------------
Use ``@error_raise`` to raise an exception if the command returns a non-zero exit code —
similar to ``$XONSH_SUBPROC_CMD_RAISE_ERROR`` but scoped to a single command, and it
raises unconditionally (even inside ``&&``/``||`` chains and even when
``$XONSH_SUBPROC_RAISE_ERROR`` is disabled).  Use ``@error_ignore`` to explicitly suppress
the raise — it also wins over the chain-result check performed by
``$XONSH_SUBPROC_RAISE_ERROR``.

.. code-block:: xonshcon

    @ r = !(@error_raise ls nonono)
    subprocess.CalledProcessError: Command '['@error_raise', 'ls', 'nonono']' returned non-zero exit status 1.

    @ r = !(@error_ignore ls nonono)

``@thread`` and ``@unthread``
-----------------------------
Use ``@thread`` and ``@unthread`` to run command as threadable or unthreadable e.g to have a result of SSH command:

.. code-block:: xonshcon

    @ !(@thread ssh host -T "echo 1")


``@path`` and ``@paths``
-----------------------------
Use ``@path`` and ``@paths`` to get Path object(s) from the command output.

.. code-block:: xonshcon

    @ dir = $(@path echo '/bin')
      dir.exists()
    @ dirs = $(@paths echo '/bin\n/etc')
      [p.exists() for p in dirs]


``@lines``
-----------
Return output as list of lines.

.. code-block:: xonshcon

    @ lines = $(@lines cat file)


``@json``
----------
Parses JSON and returns a JSON object.

.. code-block:: xonshcon

    @ data = $(@json curl https://example.com/data.json)


``@jsonl``
-----------
Parses JSON lines and returns a list of JSON objects.

.. code-block:: xonshcon

    @ items = $(@jsonl cat data.jsonl)


``@yaml``
----------
Parses YAML and returns a dict.

.. code-block:: xonshcon

    @ config = $(@yaml cat config.yaml)


``@toml``
----------
Parses TOML and returns a dict.

.. code-block:: xonshcon

    @ config = $(@toml cat pyproject.toml)


``@xml``
---------
Parses XML and returns an :class:`xml.etree.ElementTree.Element`. Navigate it
with ``.tag``, ``.attrib``, ``.text``, ``.find()``, ``.findall()``, etc.

.. code-block:: xonshcon

    @ feed = $(@xml curl -s https://github.com/xonsh/xonsh/releases.atom)
      ns = {'a': 'http://www.w3.org/2005/Atom'}
      [e.find('a:title', ns).text for e in feed.findall('a:entry', ns)[:5]]
    ['v0.23.6', 'v0.23.5', 'v0.23.4', 'v0.23.3', 'v0.23.2']


``@lxml``
----------
Parses XML with `lxml <https://lxml.de/>`_ and returns an ``lxml.etree._Element``.
Adds full XPath, richer error messages, and faster parsing on top of the
stdlib ``@xml``. Registered only when ``lxml`` is installed
(``xpip install lxml``).

.. code-block:: xonshcon

    @ feed = $(@lxml curl -s https://github.com/xonsh/xonsh/releases.atom)
      ns = {'a': 'http://www.w3.org/2005/Atom'}
      feed.xpath('//a:entry/a:title/text()', namespaces=ns)[:5]
    ['v0.23.6', 'v0.23.5', 'v0.23.4', 'v0.23.3', 'v0.23.2']


Directory Stack
====================


``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.

.. command-help:: xonsh.dirstack.pushd


``popd``
--------------------
Removes entries from the directory stack.

.. command-help:: xonsh.dirstack.popd


``dirs``
--------------------
Displays the list of currently remembered directories.  Can also be used to clear the
directory stack.

.. command-help:: xonsh.dirstack.dirs


Jobs
====================

``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.



Source Aliases
====================


``source``
--------------------
Executes the contents of the provided files in the current context. This, of course,
only works on xonsh and Python files (``*.xsh``, ``*.py``). Use ``-e`` to ignore
extension.


``source-foreign``
--------------------
Like the ``source`` command but for files in foreign (non-xonsh) languages.
It will pick up the environment and any aliases.

Supported shells: ``bash``, ``zsh``, ``sh`` (also ``dash``, ``ash``,
``ksh``, ``mksh``, ``pdksh``), and ``cmd`` on Windows. Absolute paths
like ``/bin/bash`` or ``/bin/sh`` are canonicalised to the same
defaults.

The convenience wrappers below pre-set the ``shell`` and ``--sourcer``
arguments for the most common cases — every flag accepted by
``source-foreign`` is available on them as well.

.. command-help:: xonsh.aliases.source_foreign


``source-sh``
^^^^^^^^^^^^^^^
Thin wrapper around ``source-foreign sh`` with ``--sourcer .`` (the POSIX
dot builtin, since ``/bin/sh`` on dash-based distros does not understand
``source``). Use this to source ``/etc/profile`` and similar POSIX
configuration files. Also covers ``dash``, ``ash``, ``ksh``, ``mksh``,
and ``pdksh`` (env and aliases are picked up; shell-specific function
listing is not).


``source-bash``
^^^^^^^^^^^^^^^^^
Thin wrapper around ``source-foreign bash`` with ``--sourcer source``.


``source-zsh``
^^^^^^^^^^^^^^^^
Thin wrapper around ``source-foreign zsh`` with ``--sourcer source``.


Windows Aliases
================

cmd-based Aliases
------------------
The following aliases on Windows are expanded to ``['cmd', '/c', alias]``:

.. code-block:: python

    {'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-cmd', 'activate.bat']`` and ``['source-cmd', 'deactivate.bat']``.
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.


User Aliases with Descriptions
==============================

Every alias can carry a one-line description. It surfaces in the tab-completion
dropdown next to the alias name, and in the ``cmd?`` / ``cmd??`` help output.

For callable aliases, the function's docstring is used automatically:

.. code-block:: xonshcon

    @ @aliases.register('qwe')
      def _qwe():
          """List files in long format."""
          ls -la

    @ qw<TAB>
    qwe  List files in long format.

For string and list aliases — which have nowhere to attach a docstring —
use the dict form:

.. code-block:: xonshcon

    @ aliases['qwe'] = {'alias': 'ls -la', 'doc': 'List files'}
    @ aliases |= {
          'psg':  {'alias': ['ps', 'aux'], 'doc': 'Process list'},
          'g':    {'alias': 'git',         'doc': 'Git wrapper'},
      }

The dict form recognises two keys: ``'alias'`` (required, the alias value
itself — string, list, or callable) and ``'doc'`` (optional, the one-line
description). Other keys are reserved for future use and currently ignored.

When ``'doc'`` is set on a callable alias, it overrides the function's own
``__doc__`` — handy for showing a shorter summary in completions while
keeping a longer docstring in the source:

.. code-block:: xonshcon

    @ def _bar():
          """Long, detailed description of bar..."""
          echo bar
    @ aliases['bar'] = {'alias': _bar, 'doc': 'Short summary'}
    @ ba<TAB>
    bar  Short summary

Reassigning an alias without a ``'doc'`` clears the previous description, so
descriptions never accidentally stick to a different value bound under the
same name.

By default, the description shows in the dropdown only when the alias has a
docstring (or an explicit ``'doc'``). To also show the binary path for
non-alias commands, set ``$CMD_COMPLETIONS_SHOW_DESC = True``.


See also
========

* :doc:`callable_aliases` -- writing callable aliases in depth
* :doc:`subprocess` -- subprocess operators and capturing modes
* :doc:`xonsh RC <xonshrc>` -- defining aliases in RC files
