KittyPatch/kitty
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Docs: Document the env vars set by kitty for auto shell integration

Browse Source
This commit is contained in:
pagedown 2022-04-30 16:54:53 +08:00
parent 6c1f20bb27
commit b9fd039668
No known key found for this signature in database
GPG Key ID: E921CF18AC8FF6EB
2 changed files with 48 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/glossary.rst
View File

@ -189,3 +189,21 @@ Variables that kitty sets when running child programs
Set when enabling :ref:`shell_integration`. It is automatically removed by Set when enabling :ref:`shell_integration`. It is automatically removed by
the shell integration scripts. the shell integration scripts.
.. envvar:: ZDOTDIR
Set when enabling :ref:`shell_integration` with :program:`zsh`, allowing
:program:`zsh` to automatically load the integration script.
.. envvar:: XDG_DATA_DIRS
Set when enabling :ref:`shell_integration` with :program:`fish`, allowing
:program:`fish` to automatically load the integration script.
.. envvar:: ENV
Set when enabling :ref:`shell_integration` with :program:`bash`, allowing
:program:`bash` to automatically load the integration script.

58
docs/shell-integration.rst
View File

@ -55,14 +55,15 @@ disabled
:ref:`manual integration <manual_shell_integration>`. :ref:`manual integration <manual_shell_integration>`.
no-rc no-rc
Do not modify the shell's launch environment to enable integration. Useful if you prefer Do not modify the shell's launch environment to enable integration. Useful
to load the kitty shell integration code yourself, either as part of if you prefer to load the kitty shell integration code yourself, either as
:ref:`manually integration <manual_shell_integration>` or because you have part of :ref:`manually integration <manual_shell_integration>` or because
some other software that sets up shell integration. you have some other software that sets up shell integration.
This will still set the :envvar:`KITTY_SHELL_INTEGRATION` environment variable when kitty runs the shell. This will still set the :envvar:`KITTY_SHELL_INTEGRATION` environment
variable when kitty runs the shell.
no-cursor no-cursor
Turn off changing of the text cursor to a bar when editing text Turn off changing of the text cursor to a bar when editing text.
no-title no-title
Turn off setting the kitty window/tab title based on shell state. Turn off setting the kitty window/tab title based on shell state.
@ -71,9 +72,9 @@ no-title
no-cwd no-cwd
Turn off reporting the current working directory. This is used to allow Turn off reporting the current working directory. This is used to allow
:ac:`new_window_with_cwd` and similar to open windows logged :ac:`new_window_with_cwd` and similar to open windows logged into remote
into remote machines using the :doc:`ssh kitten <kittens/ssh>` machines using the :doc:`ssh kitten <kittens/ssh>` automatically with the same
automatically with the same working directory as the current window. working directory as the current window.
Note that for the ``fish`` shell this will not disable its built-in current Note that for the ``fish`` shell this will not disable its built-in current
working directory reporting. working directory reporting.
@ -91,8 +92,8 @@ More ways to browse command output
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can add further key and mouse bindings to browse the output of commands You can add further key and mouse bindings to browse the output of commands
easily. For example to select the output of a command by right clicking the mouse easily. For example to select the output of a command by right clicking the
on the output, define the following in :file:`kitty.conf`: mouse on the output, define the following in :file:`kitty.conf`:
.. code:: conf .. code:: conf
@ -103,8 +104,8 @@ to be copied.
The feature to jump to previous prompts ( The feature to jump to previous prompts (
:sc:`scroll_to_previous_prompt` and :sc:`scroll_to_next_prompt`) and mouse :sc:`scroll_to_previous_prompt` and :sc:`scroll_to_next_prompt`) and mouse
actions (:ac:`mouse_select_command_output` and :ac:`mouse_show_command_output`) can actions (:ac:`mouse_select_command_output` and :ac:`mouse_show_command_output`)
be integrated with browsing command output as well. For example, define the can be integrated with browsing command output as well. For example, define the
following mapping in :file:`kitty.conf`: following mapping in :file:`kitty.conf`:
.. code:: conf .. code:: conf
@ -143,27 +144,27 @@ different shells.
.. tab:: zsh .. tab:: zsh
For zsh, kitty sets the ``ZDOTDIR`` environment variable to make zsh load For zsh, kitty sets the :envvar:`ZDOTDIR` environment variable to make zsh
kitty's :file:`.zshenv` which restores the original value of ``ZDOTDIR`` load kitty's :file:`.zshenv` which restores the original value of
and sources the original :file:`.zshenv`. It then loads the shell integration code. :envvar:`ZDOTDIR` and sources the original :file:`.zshenv`. It then loads
The remainder of zsh's startup process proceeds as normal. the shell integration code. The remainder of zsh's startup process proceeds
as normal.
.. tab:: fish .. tab:: fish
For fish, to make it automatically load the integration code provided by For fish, to make it automatically load the integration code provided by
kitty, the integration script directory path is prepended to the kitty, the integration script directory path is prepended to the
``XDG_DATA_DIRS`` environment variable. This is only applied to the fish :envvar:`XDG_DATA_DIRS` environment variable. This is only applied to the
process and will be cleaned up by the integration script after startup. No files fish process and will be cleaned up by the integration script after startup.
are added or modified. No files are added or modified.
.. tab:: bash .. tab:: bash
For bash, kitty starts bash in POSIX mode, using the environment variable For bash, kitty starts bash in POSIX mode, using the environment variable
``ENV`` to load the shell integration script. This prevents bash from :envvar:`ENV` to load the shell integration script. This prevents bash from
loading any startup files itself. The loading of the startup files is done loading any startup files itself. The loading of the startup files is done
by the integration script, after disabling POSIX mode. From the by the integration script, after disabling POSIX mode. From the perspective
perspective of those scripts there should be no difference to running of those scripts there should be no difference to running vanilla bash.
vanilla bash.
Then, when launching the shell, kitty sets the environment variable Then, when launching the shell, kitty sets the environment variable
@ -232,8 +233,8 @@ You can clone the current shell into a new kitty window by simply running the
clone-in-kitty --title "I am a clone" clone-in-kitty --title "I am a clone"
This will open a new window running a new shell instance but with all This will open a new window running a new shell instance but with all
environment variables and the current working directory copied. This even environment variables and the current working directory copied. This even works
works over SSH when using :doc:`kittens/ssh`. over SSH when using :doc:`kittens/ssh`.
The :command:`clone-in-kitty` command takes almost all the same arguments as the The :command:`clone-in-kitty` command takes almost all the same arguments as the
:doc:`launch <launch>` command, so you can open a new tab instead or a new OS :doc:`launch <launch>` command, so you can open a new tab instead or a new OS
@ -321,9 +322,10 @@ to point to the location of the scripts.
Integration with other shells Integration with other shells
------------------------------- -------------------------------
There exist third-party integrations to use these features for various other shells: There exist third-party integrations to use these features for various other
shells:
* Jupyter console via a patch (:iss:`4475`) * Jupyter console and IPython via a patch (:iss:`4475`)
* `xonsh <https://github.com/xonsh/xonsh/issues/4623>`__ * `xonsh <https://github.com/xonsh/xonsh/issues/4623>`__