kitty/docs/conf.rst

kitty.conf
================

.. highlight:: conf


.. only:: man

    Overview
    --------------


|kitty| is highly customizable, everything from keyboard shortcuts, to rendering
frames-per-second. See below for an overview of all customization possibilities.

You can open the config file within kitty by pressing :sc:`edit_config_file`
(:kbd:`⌘+,` on macOS). A :file:`kitty.conf` with commented default
configurations and descriptions will be created if the file does not exist.
You can reload the config file within kitty by pressing :sc:`reload_config_file`
(:kbd:`⌃+⌘+,` on macOS) or sending kitty the ``SIGUSR1`` signal.
You can also display the current configuration by pressing :sc:`debug_config`
(:kbd:`⌥+⌘+,` on macOS).

.. _confloc:

|kitty| looks for a config file in the OS config directories (usually
:file:`~/.config/kitty/kitty.conf`) but you can pass a specific path via the
:option:`kitty --config` option or use the :envvar:`KITTY_CONFIG_DIRECTORY`
environment variable. See :option:`kitty --config` for full details.

Comments can be added to the config file as lines starting with the ``#``
character. This works only if the ``#`` character is the first character in the
line.

Lines can be split by starting the next line with the ``\`` character.
All leading whitespace and the ``\`` character are removed.

.. _include:

You can include secondary config files via the :code:`include` directive. If
you use a relative path for :code:`include`, it is resolved with respect to the
location of the current config file. Note that environment variables are
expanded, so :code:`${USER}.conf` becomes :file:`name.conf` if
:code:`USER=name`. A special environment variable :envvar:`KITTY_OS` is available,
to detect the operating system. It is ``linux``, ``macos`` or ``bsd``.
Also, you can use :code:`globinclude` to include files
matching a shell glob pattern and :code:`envinclude` to include configuration
from environment variables. For example::

     include other.conf
     # Include *.conf files from all subdirs of kitty.d inside the kitty config dir
     globinclude kitty.d/**/*.conf
     # Include the *contents* of all env vars starting with KITTY_CONF_
     envinclude KITTY_CONF_*


.. note:: Syntax highlighting for :file:`kitty.conf` in vim is available via
   `vim-kitty <https://github.com/fladson/vim-kitty>`__.


.. include:: /generated/conf-kitty.rst


Sample kitty.conf
--------------------

.. only:: html

    You can download a sample :file:`kitty.conf` file with all default settings
    and comments describing each setting by clicking: :download:`sample
    kitty.conf </generated/conf/kitty.conf>`.

.. only:: man

   You can edit a fully commented sample kitty.conf by pressing the
   :sc:`edit_config_file` shortcut in kitty. This will generate a config file
   with full documentation and all settings commented out. If you have a
   pre-existing :file:`kitty.conf`, then that will be used instead, delete it to
   see the sample file.

A default configuration file can also be generated by running::

    kitty +runpy 'from kitty.config import *; print(commented_out_default_config())'

This will print the commented out default config file to :file:`STDOUT`.

All mappable actions
------------------------

See the :doc:`list of all the things you can make kitty can do </actions>`.

.. toctree::
   :hidden:

   actions