mirror of
https://github.com/xonsh/xonsh.git
synced 2025-03-04 08:24:40 +01:00
Config rewrite; move platform guides into tips and tricks
This commit is contained in:
Bob Hyman
parent
f034d3dc06
commit
eb2b8f5791
7 changed files with 370 additions and 475 deletions
|
|
@ -1,25 +0,0 @@
|
|||
Dependencies
|
||||
------------
|
||||
Xonsh currently has the following external dependencies,
|
||||
|
||||
*Run Time:*
|
||||
|
||||
#. Python v3.5+
|
||||
|
||||
Pip supports "extra" dependencies in the form of ``xonsh[ptk,linux]``, where
|
||||
the list in the brackets identify the optional features
|
||||
|
||||
Xonsh currently has the following extras
|
||||
|
||||
#. ``ptk``: prompt-toolkit >= 2.0: *advanced readline library, line-editing*
|
||||
#. ``pygments``: pygments >=2.2: *syntax-highlighting*
|
||||
#. ``proctitle``: setproctitle: *change the title of terminal to reflect the current subprocess*
|
||||
#. ``linux``: distro: *linux specific platform information*
|
||||
#. ``mac``: gnureadline: *GNU's featureful version of readline*
|
||||
|
||||
In addition, xonsh integrates with Jupyter, an in-browser REPL, enabling the use of xonsh in jupyter notebooks
|
||||
|
||||
Development Dependencies
|
||||
------------------------
|
||||
|
||||
If you want to develop xonsh, it is extremely recommended to install the dependencies listed in `requirements/docs.txt <https://github.com/xonsh/xonsh/blob/master/requirements/docs.txt>`_ (to generate documentation) and `requirements/tests.txt <https://github.com/xonsh/xonsh/blob/master/requirements/tests.txt>`_ (to run the test suite).
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
|
||||
Installation and Configuration
|
||||
==============================
|
||||
Installation
|
||||
============
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
|
@ -32,14 +32,15 @@ Installation in specialized environments
|
|||
jupyter
|
||||
editors
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
Configuration and Customization
|
||||
================================
|
||||
|
||||
Xonsh uses a startup configuration file and provides a configuration wizard to help you set this up.
|
||||
Xonsh uses startup configuration files and provides configuration wizards to help you set them up.
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:maxdepth: 2
|
||||
|
||||
xonshrc
|
||||
xonshrc
|
||||
customization
|
||||
platform-issues
|
||||
|
|
|
|||
123
docs/linux.rst
123
docs/linux.rst
|
|
@ -1,123 +0,0 @@
|
|||
==========================
|
||||
Linux Guide
|
||||
==========================
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
You can install xonsh using ``conda``, ``pip``, or from source.
|
||||
|
||||
**conda:**
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ conda config --add channels conda-forge
|
||||
$ conda install xonsh
|
||||
|
||||
|
||||
**pip:**
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install xonsh
|
||||
|
||||
|
||||
**source:** Download the source `from github <https://github.com/xonsh/xonsh>`_
|
||||
(`zip file <https://github.com/xonsh/xonsh/archive/master.zip>`_), then run
|
||||
the following from the source directory,
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install .
|
||||
|
||||
|
||||
Debian/Ubuntu users can install xonsh from the repository with:
|
||||
|
||||
**apt:**
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ apt install xonsh
|
||||
|
||||
|
||||
Xonsh is available on bionic bever (version 0.6.0) and artful aardvark
|
||||
(version 0.5.12).
|
||||
|
||||
Fedora users can install xonsh from the repository with:
|
||||
|
||||
**dnf:**
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ dnf install xonsh
|
||||
|
||||
|
||||
Arch Linux users can install xonsh from the official community repository with:
|
||||
|
||||
**pacman:**
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pacman -S xonsh
|
||||
|
||||
Note that some of these may require ``sudo``.
|
||||
If you run into any problems, please let us know!
|
||||
|
||||
.. include:: dependencies.rst
|
||||
|
||||
Customization
|
||||
=============
|
||||
|
||||
See the `xonsh customization guide <customization.html>`_ for more details on setting up ``xonsh``!
|
||||
|
||||
|
||||
Possible conflicts with Bash
|
||||
============================
|
||||
|
||||
Depending on how your installation of Bash is configured, Xonsh may have trouble
|
||||
loading certain shell modules. Particularly if you see errors similar to this
|
||||
when launching Xonsh:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
bash: module: line 1: syntax error: unexpected end of file
|
||||
bash: error importing function definition for `BASH_FUNC_module'
|
||||
bash: scl: line 1: syntax error: unexpected end of file
|
||||
bash: error importing function definition for `BASH_FUNC_scl'
|
||||
bash: module: line 1: syntax error: unexpected end of file
|
||||
bash: error importing function definition for `BASH_FUNC_module'
|
||||
bash: scl: line 1: syntax error: unexpected end of file
|
||||
bash: error importing function definition for `BASH_FUNC_scl'
|
||||
|
||||
...You can correct the problem by unsetting the modules, by adding the following
|
||||
lines to your ``~/.bashrc file``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
unset module
|
||||
unset scl
|
||||
|
||||
|
||||
Default Ubuntu .bashrc breaks Foreign Shell Functions
|
||||
=====================================================
|
||||
Xonsh supports importing functions from foreign shells using the
|
||||
`ForeignShellFunctionAlias` class, which calls functions as if they were
|
||||
aliases. This is implemented by executing a command that sources the file
|
||||
containing the function definition and then immediately calls the function with
|
||||
any necessary arguments.
|
||||
|
||||
The default user `~/.bashrc` file in Ubuntu 15.10 has the following snippet at
|
||||
the top, which causes the script to exit immediately if not run interactively.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# If not running interactively, don't do anything
|
||||
case $- in
|
||||
*i*) ;;
|
||||
*) return;;
|
||||
esac
|
||||
|
||||
This means that any function you have added to the file after this point will be
|
||||
registered as a xonsh alias but will fail on execution. Previous versions of
|
||||
Ubuntu have a different test for interactivity at the top of the file that
|
||||
yields the same problem.
|
||||
114
docs/osx.rst
114
docs/osx.rst
|
|
@ -1,114 +0,0 @@
|
|||
==========================
|
||||
OSX Guide
|
||||
==========================
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
You can install xonsh using a package manager including homebrew, macports, conda, pip, or from source.
|
||||
|
||||
**homebrew:**
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ brew install xonsh
|
||||
|
||||
|
||||
**MacPorts:**
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo port install xonsh
|
||||
|
||||
**conda:**
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ conda config --add channels conda-forge
|
||||
$ conda install xonsh
|
||||
|
||||
|
||||
**pip:**
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip3 install xonsh
|
||||
|
||||
|
||||
**source:** Download the source `from github <https://github.com/xonsh/xonsh>`_
|
||||
(`zip file <https://github.com/xonsh/xonsh/archive/master.zip>`_), then run
|
||||
the following from the source directory,
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip3 install xonsh
|
||||
|
||||
Extras for macOS
|
||||
==================
|
||||
readline
|
||||
--------
|
||||
|
||||
On macOS, it is *strongly* recommended to install the ``gnureadline`` library if using the readline shell. ``gnureadline`` can be installed via pip:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip3 install gnureadline
|
||||
|
||||
Path Helper
|
||||
-----------
|
||||
|
||||
macOS provides a `path helper
|
||||
<http://www.softec.lu/site/DevelopersCorner/MasteringThePathHelper>`_,
|
||||
which by default configures paths in bash and other POSIX or C shells. Without
|
||||
including these paths, common tools including those installed by Homebrew
|
||||
may be unavailable. See ``/etc/profile`` for details on how it is done.
|
||||
To ensure the path helper is invoked on xonsh (for all users), add the
|
||||
following to ``/etc/xonshrc``::
|
||||
|
||||
source-bash $(/usr/libexec/path_helper -s)
|
||||
|
||||
To incorporate the whole functionality of ``/etc/profile``::
|
||||
|
||||
source-bash --seterrprevcmd "" /etc/profile
|
||||
|
||||
|
||||
|
||||
Tab completion
|
||||
--------------
|
||||
Xonsh has support for using bash completion files on the shell, to use it you need to install the bash-completion package. The regular bash-completion package uses v1 which mostly works, but `occasionally has rough edges <https://github.com/xonsh/xonsh/issues/2111>`_ so we recommend using bash-completion v2.
|
||||
|
||||
Bash completion comes from <https://github.com/scop/bash-completion> which suggests you use a package manager to install it, this manager will also install a new version of bash without affecting /bin/bash. Xonsh also needs to be told where the bash shell file that builds the completions is, this has to be added to $BASH_COMPLETIONS. The package includes completions for many Unix commands.
|
||||
|
||||
Common packaging systems for MacOs include
|
||||
|
||||
- Homebrew where the bash-completion2 package needs to be installed.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ brew install bash-completion2
|
||||
|
||||
This will install the bash_completion file in `/usr/local/share/bash-completion/bash_completion` which is in the current xonsh code and so should just work.
|
||||
|
||||
- `MacPorts <https://trac.macports.org/wiki/howto/bash-completion>`_ where the bash-completion port needs to be installed.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo port install bash-completion
|
||||
|
||||
|
||||
|
||||
This includes a bash_completion file that needs to be added to the environment.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ $BASH_COMPLETIONS.insert(0, '/opt/local/share/bash-completion/bash_completion')
|
||||
|
||||
Note that the `bash completion project page <https://github.com/scop/bash-completion>`_ gives the script to be called as in .../profile.d/bash_completion.sh which will the call the script mentioned above and one in $XDG_CONFIG_HOME . Currently xonsh seems only to be able to read the first script directly.
|
||||
|
||||
|
||||
.. include:: dependencies.rst
|
||||
|
||||
Customization
|
||||
=============
|
||||
|
||||
See the `xonsh customization guide <customization.html>`_ for more details on setting up ``xonsh``!
|
||||
227
docs/platform-issues.rst
Normal file
227
docs/platform-issues.rst
Normal file
|
|
@ -0,0 +1,227 @@
|
|||
Platform-specific tips and tricks
|
||||
==================================
|
||||
|
||||
Linux
|
||||
------
|
||||
|
||||
Possible conflicts with Bash
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Depending on how your installation of Bash is configured, Xonsh may have trouble
|
||||
loading certain shell modules. If you see errors similar to this
|
||||
when launching Xonsh:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
bash: module: line 1: syntax error: unexpected end of file
|
||||
bash: error importing function definition for 'BASH_FUNC_module'
|
||||
bash: scl: line 1: syntax error: unexpected end of file
|
||||
bash: error importing function definition for 'BASH_FUNC_scl'
|
||||
bash: module: line 1: syntax error: unexpected end of file
|
||||
bash: error importing function definition for 'BASH_FUNC_module'
|
||||
bash: scl: line 1: syntax error: unexpected end of file
|
||||
bash: error importing function definition for 'BASH_FUNC_scl'
|
||||
|
||||
...You can correct the problem by unsetting the modules, by adding the following
|
||||
lines to your ``~/.bashrc file``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
unset module
|
||||
unset scl
|
||||
|
||||
|
||||
Default Ubuntu .bashrc breaks Foreign Shell Functions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Xonsh supports importing functions from foreign shells using the
|
||||
`ForeignShellFunctionAlias` class, which calls functions as if they were
|
||||
aliases. This is implemented by executing a command that sources the file
|
||||
containing the function definition and then immediately calls the function with
|
||||
any necessary arguments.
|
||||
|
||||
The default user `~/.bashrc` file in Ubuntu 15.10 has the following snippet at
|
||||
the top, which causes the script to exit immediately if not run interactively.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# If not running interactively, don't do anything
|
||||
case $- in
|
||||
*i*) ;;
|
||||
*) return;;
|
||||
esac
|
||||
|
||||
This means that any function you have added to the file after this point will be
|
||||
registered as a xonsh alias but will fail on execution if the
|
||||
shell is not running interactively. Previous versions of
|
||||
Ubuntu have a different test for interactivity at the top of the file that
|
||||
yields the same problem.
|
||||
|
||||
|
||||
MacOS, OSX
|
||||
----------
|
||||
|
||||
readline
|
||||
^^^^^^^^
|
||||
|
||||
[ed note: This recommendation seems to be `out of date <https://pypi.org/project/gnureadline/>`_.
|
||||
It's retained in the current docs in case you have an older version of Python or MacOS. But if
|
||||
you have Mac platform experience and can clarify, please open an issue or even a PR to correct the documentation.]
|
||||
|
||||
On macOS, it is *strongly* recommended to install the ``gnureadline`` library if using the readline shell. ``gnureadline`` can be installed via pip:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip3 install gnureadline
|
||||
|
||||
Path Helper
|
||||
^^^^^^^^^^^
|
||||
|
||||
macOS provides a `path helper
|
||||
<http://www.softec.lu/site/DevelopersCorner/MasteringThePathHelper>`_,
|
||||
which by default configures paths in bash and other POSIX or C shells. Without
|
||||
including these paths, common tools including those installed by Homebrew
|
||||
may be unavailable. See ``/etc/profile`` for details on how it is done.
|
||||
To ensure the path helper is invoked on xonsh (for all users), add the
|
||||
following to ``/etc/xonshrc``::
|
||||
|
||||
source-bash $(/usr/libexec/path_helper -s)
|
||||
|
||||
To incorporate the whole functionality of ``/etc/profile``::
|
||||
|
||||
source-bash --seterrprevcmd "" /etc/profile
|
||||
|
||||
|
||||
|
||||
Tab completion
|
||||
^^^^^^^^^^^^^^
|
||||
Xonsh has support for using bash completion files on the shell, to use it you need to install
|
||||
the bash-completion package.
|
||||
The regular bash-completion package uses v1 which mostly works, but `occasionally has rough edges <https://github.com/xonsh/xonsh/issues/2111>`_ so we recommend using bash-completion v2.
|
||||
|
||||
Bash completion comes from <https://github.com/scop/bash-completion> which suggests you use a package manager to install it, this manager will also install a new version of bash without affecting /bin/bash. Xonsh also needs to be told where the bash shell file that builds the completions is, this has to be added to $BASH_COMPLETIONS. The package includes completions for many Unix commands.
|
||||
|
||||
Common packaging systems for MacOs include
|
||||
|
||||
- Homebrew where the bash-completion2 package needs to be installed.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ brew install bash-completion2
|
||||
|
||||
This will install the bash_completion file in `/usr/local/share/bash-completion/bash_completion` which is in the current xonsh code and so should just work.
|
||||
|
||||
- `MacPorts <https://trac.macports.org/wiki/howto/bash-completion>`_ where the bash-completion port needs to be installed.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo port install bash-completion
|
||||
|
||||
|
||||
|
||||
This includes a bash_completion file that needs to be added to the environment.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ $BASH_COMPLETIONS.insert(0, '/opt/local/share/bash-completion/bash_completion')
|
||||
|
||||
Note that the `bash completion project page <https://github.com/scop/bash-completion>`_ gives the script to be called as in .../profile.d/bash_completion.sh which will the call the script mentioned above and one in $XDG_CONFIG_HOME . Currently xonsh seems only to be able to read the first script directly.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Windows
|
||||
-------
|
||||
|
||||
Windows Terminal
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
If you are running a supported version of Windows (which is now Windows 10, version 2004 or later),
|
||||
we recommend the Windows Terminal (``wt.exe``) rather than the time-honored ``cmd.exe``. This provides
|
||||
unicode rendering, better ansi terminal compatibility and all the conveniences you expect
|
||||
from the terminal application in other platforms.
|
||||
|
||||
You can install it from the `Microsoft Store<https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701>`_
|
||||
or from `Github<https://github.com/microsoft/terminal>`_.
|
||||
|
||||
By default Windows Terminal runs Powershell, but comes with a profile tab that runs `cmd.exe` instead, and you can add one for Xonsh as well.
|
||||
|
||||
Nice colors
|
||||
^^^^^^^^^^^
|
||||
|
||||
The dark red and blue colors are completely unreadable in `cmd.exe`.
|
||||
|
||||
.. image:: _static/intensify-colors-on-win-false.png
|
||||
:width: 396 px
|
||||
:alt: intensify-colors-win-false
|
||||
:align: center
|
||||
|
||||
Xonsh has some tricks to fix colors. This is controlled by the
|
||||
:ref:`$INTENSIFY_COLORS_ON_WIN <intensify_colors_on_win>`
|
||||
environment variable which is ``True`` by default.
|
||||
|
||||
|
||||
:ref:`$INTENSIFY_COLORS_ON_WIN <intensify_colors_on_win>` has the following effect:b
|
||||
|
||||
On Windows 10:
|
||||
Windows 10 supports true color in the terminal, so on Windows 10 Xonsh will use
|
||||
a style with hard coded colors instead of the terminal colors.
|
||||
|
||||
On older Windows:
|
||||
Xonsh replaces some of the unreadable dark colors with more readable
|
||||
alternatives (e.g. blue becomes cyan).
|
||||
|
||||
|
||||
Avoid locking the working directory
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Python (like other processes on Windows) locks the current working directory so
|
||||
it can't be deleted or renamed. ``cmd.exe`` has this behaviour as well, but it
|
||||
is quite annoying for a shell.
|
||||
|
||||
The :ref:`free_cwd <free_cwd>` xontrib (add-on) for xonsh solves some of this problem. It
|
||||
works by hooking the prompt to reset the current working directory to the root
|
||||
drive folder whenever the shell is idle. It only works with the prompt-toolkit
|
||||
back-end. To enable that behaviour run the following:
|
||||
|
||||
Add this line to your ``~/.xonshrc`` file to have it always enabled.
|
||||
|
||||
.. code-block:: xonshcon
|
||||
|
||||
>>> xontrib load free_cwd
|
||||
|
||||
|
||||
Name space conflicts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Due to ambiguity with the Python ``dir`` builtin, to list the current directory
|
||||
you must explicitly request the ``.``, like this:
|
||||
|
||||
.. code-block:: xonshcon
|
||||
|
||||
>>> dir .
|
||||
Volume in drive C is Windows
|
||||
Volume Serial Number is 30E8-8B86
|
||||
|
||||
Directory of C:\Users\snail\xonsh
|
||||
|
||||
2015-05-12 03:04 <DIR> .
|
||||
2015-05-12 03:04 <DIR> ..
|
||||
2015-05-01 01:31 <DIR> xonsh
|
||||
0 File(s) 0 bytes
|
||||
3 Dir(s) 11,008,000,000 bytes free
|
||||
|
||||
|
||||
|
||||
Many people create a ``d`` alias for the ``dir`` command to save
|
||||
typing and avoid the ambiguity altogether:
|
||||
|
||||
.. code-block:: xonshcon
|
||||
|
||||
>>> aliases['d'] = ['cmd', '/c', 'dir']
|
||||
|
||||
You can add aliases to your ``~/.xonshrc`` to have it always
|
||||
available when xonsh starts.
|
||||
|
||||
|
||||
183
docs/windows.rst
183
docs/windows.rst
|
|
@ -1,183 +0,0 @@
|
|||
==========================
|
||||
Windows Guide
|
||||
==========================
|
||||
|
||||
Installation
|
||||
================
|
||||
|
||||
The easy way
|
||||
----------------
|
||||
|
||||
The easiest way to install xonsh on windows is through the `Anaconda Python
|
||||
Distribution <https://www.anaconda.com/download/>`__ and the conda package manager.
|
||||
|
||||
.. note::
|
||||
|
||||
Xonsh is not supported on legacy Python (2.7).
|
||||
|
||||
Install xonsh with the following command:
|
||||
|
||||
.. code-block:: bat
|
||||
|
||||
> conda config --add channels conda-forge
|
||||
> conda install xonsh
|
||||
|
||||
This will install xonsh and all the recommended dependencies. Next, run xonsh:
|
||||
|
||||
.. code-block:: bat
|
||||
|
||||
> xonsh
|
||||
snail@home ~ $
|
||||
|
||||
|
||||
Install from source
|
||||
-------------------
|
||||
|
||||
To install xonsh from source on Windows, first install `Python v3.4+`_ from
|
||||
http://python.org. Remember to select "Add python to PATH" during installation.
|
||||
|
||||
Next, install the prompt_toolkit dependency via ``pip``:
|
||||
|
||||
.. code-block:: bat
|
||||
|
||||
> pip install prompt-toolkit
|
||||
|
||||
Download the latest `xonsh-master.zip`_ from github and unzip it
|
||||
to ``xonsh-master``.
|
||||
|
||||
Now install xonsh:
|
||||
|
||||
.. code-block:: bat
|
||||
|
||||
> cd xonsh-master
|
||||
> pip install .
|
||||
|
||||
Next, run xonsh:
|
||||
|
||||
.. code-block:: bat
|
||||
|
||||
> xonsh
|
||||
snail@home ~ $
|
||||
|
||||
.. _Python v3.4+: https://www.python.org/downloads/windows/
|
||||
.. _xonsh-master.zip: https://github.com/xonsh/xonsh/archive/master.zip
|
||||
.. _cmder: http://cmder.net/
|
||||
.. _conemu: https://conemu.github.io/
|
||||
|
||||
|
||||
Tips and Tricks
|
||||
================
|
||||
|
||||
Nice colors
|
||||
----------------------
|
||||
|
||||
The dark red and blue colors are completely unreadable in Windows' default
|
||||
terminal.
|
||||
|
||||
.. image:: _static/intensify-colors-on-win-false.png
|
||||
:width: 396 px
|
||||
:alt: intensify-colors-win-false
|
||||
:align: center
|
||||
|
||||
There are ways to `configure the colors`_ of the old terminal, but to give new users the
|
||||
best experience Xonsh has some tricks to fix colors. This is controlled by the
|
||||
:ref:`$INTENSIFY_COLORS_ON_WIN <intensify_colors_on_win>`
|
||||
environment variable which is ``True`` by default.
|
||||
|
||||
.. _configure the colors: https://blogs.msdn.microsoft.com/commandline/2017/08/11/introducing-the-windows-console-colortool/
|
||||
|
||||
:ref:`$INTENSIFY_COLORS_ON_WIN <intensify_colors_on_win>` has the following effect:b
|
||||
|
||||
On Windows 10:
|
||||
Windows 10 supports true color in the terminal, so on Windows 10 Xonsh will use
|
||||
a style with hard coded colors instead of the terminal colors.
|
||||
|
||||
On older Windows:
|
||||
Xonsh replaces some of the unreadable dark colors with more readable
|
||||
alternatives (e.g. blue becomes cyan).
|
||||
|
||||
|
||||
**The new Windows terminal**
|
||||
|
||||
The best option on windows is to use the new `Windows Terminal
|
||||
<https://github.com/microsoft/terminal>`__ developed by Microsoft as an open
|
||||
source project. The new terminal supports has many nice features including
|
||||
Unicode rendering.
|
||||
|
||||
It is highly recommended and can easily be `installed from the Windows Store`_:
|
||||
|
||||
|
||||
.. image:: _static/windows_terminal2.png
|
||||
:alt: Unicode support in Windows terminal
|
||||
:align: center
|
||||
|
||||
|
||||
.. _installed from the Windows Store: https://blogs.msdn.microsoft.com/commandline/2017/08/11/introducing-the-windows-console-colortool/
|
||||
|
||||
|
||||
|
||||
Avoid locking the working directory
|
||||
-----------------------------------
|
||||
|
||||
Python (like other processes on Windows) locks the current working directory so
|
||||
it can't be deleted or renamed. ``cmd.exe`` has this behaviour as well, but it
|
||||
is quite annoying for a shell.
|
||||
|
||||
The :ref:`free_cwd <free_cwd>` xontrib (add-on) for xonsh solves some of this problem. It
|
||||
works by hooking the prompt to reset the current working directory to the root
|
||||
drive folder whenever the shell is idle. It only works with the prompt-toolkit
|
||||
back-end. To enable that behaviour run the following:
|
||||
|
||||
Add this line to your ``~/.xonshrc`` file to have it always enabled.
|
||||
|
||||
.. code-block:: xonshcon
|
||||
|
||||
>>> xontrib load free_cwd
|
||||
|
||||
|
||||
Name space conflicts
|
||||
--------------------
|
||||
|
||||
Due to ambiguity with the Python ``dir`` builtin, to list the current directory
|
||||
via the ``cmd.exe`` builtin you must explicitly request the ``.``, like this:
|
||||
|
||||
.. code-block:: xonshcon
|
||||
|
||||
>>> dir .
|
||||
Volume in drive C is Windows
|
||||
Volume Serial Number is 30E8-8B86
|
||||
|
||||
Directory of C:\Users\snail\xonsh
|
||||
|
||||
2015-05-12 03:04 <DIR> .
|
||||
2015-05-12 03:04 <DIR> ..
|
||||
2015-05-01 01:31 <DIR> xonsh
|
||||
0 File(s) 0 bytes
|
||||
3 Dir(s) 11,008,000,000 bytes free
|
||||
|
||||
|
||||
|
||||
Many people create a ``d`` alias for the ``dir`` command to save
|
||||
typing and avoid the ambiguity altogether:
|
||||
|
||||
.. code-block:: xonshcon
|
||||
|
||||
>>> aliases['d'] = ['cmd', '/c', 'dir']
|
||||
|
||||
You can add aliases to your ``~/.xonshrc`` to have it always
|
||||
available when xonsh starts.
|
||||
|
||||
|
||||
|
||||
Unicode support for Windows
|
||||
----------------------------
|
||||
|
||||
Python's utf-8 unicode is not compatible with the default console "conhost" on Windows.
|
||||
|
||||
Luckily, Microsoft is developing a new `Windows terminal <https://github.com/microsoft/terminal>`__ as an open source project. The new terminal supports all the nice features of
|
||||
that you find in linux terminals. It is highly recommended and can easily be `installed from the Windows Store`_:
|
||||
|
||||
.. image:: _static/windows_terminal.png
|
||||
:alt: Unicode support in Windows terminal
|
||||
:align: center
|
||||
|
||||
160
docs/xonshrc.rst
160
docs/xonshrc.rst
|
|
@ -1,32 +1,28 @@
|
|||
Run Control File
|
||||
=========================
|
||||
Xonsh allows you to have run control files to customize your shell behavior. These are called ``xonshrc`` files.
|
||||
Xonsh allows you to customize your shell behavior with run control files, called "xonshrc" files.
|
||||
These files are written in the xonsh language (a superset of Python) and are executed exactly once at startup.
|
||||
The control file usually contains:
|
||||
|
||||
* Assignment statements setting `environment variables <envvars.html>`_. This includes standard OS environment variables that affect other programs and many that Xonsh uses for itself.
|
||||
* ``xonfig`` commands to load selected add-ins ("`xontribs<tutorial_xontrib.html#loading-xontribs>`")
|
||||
* Xonsh function defintions
|
||||
* `Alias definitions <aliases.html>`_, many of which invoke the above functions with specified arguments.
|
||||
|
||||
The system-wide ``xonshrc`` file controls options that are applied to all users of Xonsh on a given system.
|
||||
You can create this file in ``/etc/xonshrc`` for Linux and OSX and in ``%ALLUSERSPROFILE%\xonsh\xonshrc`` on Windows.
|
||||
|
||||
Xonsh also allows you to have a run control file in your home directory.
|
||||
It can either be directly in the home directory at ``~/.xonshrc`` or for XDG compliance at ``~/.config/rc.xsh``.
|
||||
The options set in the local ``xonshrc`` only apply to the current user and will override any conflicting settings set in the system-wide control file.
|
||||
Xonsh also allows a per-user run control file in your home directory, either
|
||||
directly in the home directory at ``~/.xonshrc`` or, for XDG compliance, at ``~/.config/rc.xsh``.
|
||||
The options set per user override settings in the system-wide control file.
|
||||
|
||||
These files are written in the xonsh language (a superset of Python). They are executed exactly once at startup.
|
||||
The control file usually contains:
|
||||
|
||||
* Assignment statements setting `environment variables <envvars.html>`_. This includes standard OS environment variables that affect other programs and many that Xonsh uses for itself.
|
||||
* Xonsh function defintions
|
||||
* `Alias definitions <aliases.html>`_, many of which invoke the above functions with specified arguments.
|
||||
|
||||
The following is a real-world example of such a file.
|
||||
|
||||
:download:`Download xonshrc <xonshrc.xsh>`
|
||||
|
||||
.. include:: xonshrc.xsh
|
||||
:code: xonsh
|
||||
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
|
||||
-----------
|
||||
|
||||
Xonsh provides a configuration wizard which helps you choose a color theme, customized prompt and add-in packages ("xontribs"). It
|
||||
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):
|
||||
|
||||
.. code-block:: xonshcon
|
||||
|
|
@ -42,7 +38,8 @@ 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 run control file to further refine your prompt.
|
||||
: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
|
||||
|
|
@ -50,6 +47,121 @@ The page has:
|
|||
: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 (ordinary) shell such as ``bash``.
|
||||
It also walks you through setting all known environment variables and xontribs
|
||||
in a question-and-answer format:
|
||||
|
||||
.. code-block:: xonshcon
|
||||
|
||||
$ xonfig wizard
|
||||
|
||||
Welcome to the xonsh configuration wizard!
|
||||
------------------------------------------
|
||||
This will present a guided tour through setting up the xonsh static
|
||||
config file. Xonsh will automatically ask you if you want to run this
|
||||
wizard if the configuration file does not exist. However, you can
|
||||
always rerun this wizard with the xonfig command:
|
||||
|
||||
$ xonfig wizard
|
||||
|
||||
This wizard will load an existing configuration, if it is available.
|
||||
Also never fear when this wizard saves its results! It will create
|
||||
a backup of any existing configuration automatically.
|
||||
|
||||
This wizard has two main phases: foreign shell setup and environment
|
||||
variable setup. Each phase may be skipped in its entirety.
|
||||
|
||||
For the configuration to take effect, you will need to restart xonsh.
|
||||
|
||||
'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'``-.,_,.-*'
|
||||
|
||||
To exit the wizard at any time, press Ctrl-C.
|
||||
|
||||
|
||||
'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'
|
||||
|
||||
Foreign Shell Setup
|
||||
-------------------
|
||||
The xonsh shell has the ability to interface with foreign shells such
|
||||
as Bash, or zsh (fish not yet implemented).
|
||||
|
||||
For configuration, this means that xonsh can load the environment,
|
||||
aliases, and functions specified in the config files of these shells.
|
||||
Naturally, these shells must be available on the system to work.
|
||||
Being able to share configuration (and source) from foreign shells
|
||||
makes it easier to transition to and from xonsh.
|
||||
|
||||
Add a new foreign shell, yes or no [default: no]? yes
|
||||
shell name (e.g. bash): bash
|
||||
interactive shell [bool, default=True]:
|
||||
login shell [bool, default=False]:
|
||||
env command [str, default='env']:
|
||||
alias command [str, default='alias']:
|
||||
extra command line arguments [list of str, default=[]]:
|
||||
safely handle exceptions [bool, default=True]:
|
||||
pre-command [str, default='']:
|
||||
post-command [str, default='']:
|
||||
foreign function command [str, default=None]:
|
||||
source command [str, default=None]: source
|
||||
Foreign shell added.
|
||||
|
||||
Add a new foreign shell, yes or no [default: no]? no
|
||||
|
||||
'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'`-.,_,.-*'``-.,_,.-*'
|
||||
|
||||
Environment Variable Setup
|
||||
--------------------------
|
||||
The xonsh shell also allows you to setup environment variables from
|
||||
the static configuration file. Any variables set in this way are
|
||||
superseded by the definitions in the xonshrc or on the command line.
|
||||
Still, setting environment variables in this way can help define
|
||||
options that are global to the system or user.
|
||||
|
||||
The following lists the environment variable name, its documentation,
|
||||
the default value, and the current value. The default and current
|
||||
values are presented as pretty repr strings of their Python types.
|
||||
|
||||
Note: Simply hitting enter for any environment variable
|
||||
will accept the default value for that entry.
|
||||
|
||||
Would you like to set env vars now, yes or no [default: no]? yes
|
||||
|
||||
$ALLUSERSPROFILE
|
||||
|
||||
default value:
|
||||
current value: 'C:\\ProgramData'
|
||||
>>>
|
||||
|
||||
$APPDATA
|
||||
|
||||
default value:
|
||||
current value: 'C:\\Users\\bobhy\\AppData\\Roaming'
|
||||
>>>
|
||||
|
||||
$AUTO_CD
|
||||
Flag to enable changing to a directory by entering the dirname or
|
||||
full path only (without the cd command).
|
||||
default value: False
|
||||
current value: False
|
||||
>>>
|
||||
|
||||
. . .
|
||||
|
||||
|
||||
Real world sample xonshrc
|
||||
-------------------------
|
||||
|
||||
The following is a real-world example of such a file.
|
||||
|
||||
:download:`Download xonshrc <xonshrc.xsh>`
|
||||
|
||||
.. include:: xonshrc.xsh
|
||||
:code: xonsh
|
||||
|
||||
|
||||
Snippets for xonshrc
|
||||
--------------------
|
||||
|
||||
|
|
@ -57,7 +169,7 @@ The following are useful snippets and code that tweaks and adjust xonsh in vario
|
|||
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.
|
||||
|
|
@ -77,7 +189,7 @@ The following snippet reimplements the formatter also to include untracked files
|
|||
|
||||
|
||||
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.
|
||||
|
||||
.. code-block:: xonshcon
|
||||
|
|
@ -85,7 +197,7 @@ The colors of the ``ls`` command may be hard to read in a dark terminal. If so,
|
|||
>>> $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, though practical, this is rather hacky and might break other functionality. Use at your own risk.
|
||||
|
||||
|
|
@ -97,7 +209,7 @@ Note that, though practical, this is rather hacky and might break other function
|
|||
>>> 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...
|
||||
|
||||
.. code-block:: xonshcon
|
||||
|
|
@ -114,7 +226,7 @@ For a compact shell prompts, some people prefer a very condensed time format. Bu
|
|||
>>> $PROMPT_FIELDS['shelldate'] = get_shelldate
|
||||
|
||||
Use the Nix Package manager with Xonsh
|
||||
--------------------------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
To users of the `Nix Package Manager <https://www.nixos.org/>`_ these few lines might be life-savers:
|
||||
|
||||
.. code-block:: xonshcon
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue