261 lines
11 KiB
ReStructuredText
261 lines
11 KiB
ReStructuredText
.. _local-configuration-overrides:
|
||
|
||
*****************************
|
||
Local configuration overrides
|
||
*****************************
|
||
|
||
Depending on the application used it is possible to override configuration. Here
|
||
is the list:
|
||
|
||
Vim overrides
|
||
=============
|
||
|
||
Vim configuration can be overridden using the following options:
|
||
|
||
.. _local-configuration-overrides-vim-config:
|
||
|
||
``g:powerline_config_overrides``
|
||
Dictionary, recursively merged with contents of
|
||
:file:`powerline/config.json`.
|
||
|
||
``g:powerline_theme_overrides``
|
||
Dictionary mapping theme names to theme overrides, recursively merged with
|
||
contents of :file:`powerline/themes/vim/{key}.json`. Note that this way some
|
||
value (e.g. segment) in a list cannot be redefined, only the whole list
|
||
itself: only dictionaries are merged recursively.
|
||
|
||
``g:powerline_config_paths``
|
||
Paths list (each path must be expanded, ``~`` shortcut is not supported).
|
||
Points to the list of directories which will be searched for configuration.
|
||
When this option is present, none of the other locations are searched.
|
||
|
||
``g:powerline_no_python_error``
|
||
If this variable is set to a true value it will prevent Powerline from reporting
|
||
an error when loaded in a copy of vim without the necessary Python support.
|
||
|
||
``g:powerline_use_var_handler``
|
||
This variable may be set to either 0 or 1. If it is set to 1 then Vim will
|
||
save log in ``g:powerline_log_messages`` variable in addition to whatever
|
||
was configured in :ref:`log_* options <config-common-log>`. Level is always
|
||
:ref:`log_level <config-common-log_level>`, same for format.
|
||
|
||
.. warning::
|
||
This variable is deprecated. Use :ref:`log_file option
|
||
<config-common-log>` in conjunction with
|
||
:py:class:`powerline.vim.VimVarHandler` class and :ref:`Vim config
|
||
overrides variable <local-configuration-overrides-vim-config>`. Using
|
||
this is also the only variant to make saving into the environment
|
||
variable the *only* place where log is saved or save into different
|
||
variable.
|
||
|
||
.. autoclass:: powerline.vim.VimVarHandler
|
||
|
||
.. _local-configuration-overrides-script:
|
||
|
||
Powerline script overrides
|
||
==========================
|
||
|
||
Powerline script has a number of options controlling powerline behavior. Here
|
||
``VALUE`` always means “some JSON object”.
|
||
|
||
``-c KEY.NESTED_KEY=VALUE`` or ``--config-override=KEY.NESTED_KEY=VALUE``
|
||
Overrides options from :file:`powerline/config.json`.
|
||
``KEY.KEY2.KEY3=VALUE`` is a shortcut for ``KEY={"KEY2": {"KEY3": VALUE}}``.
|
||
Multiple options (i.e. ``-c K1=V1 -c K2=V2``) are allowed, result (in the
|
||
example: ``{"K1": V1, "K2": V2}``) is recursively merged with the contents
|
||
of the file.
|
||
|
||
If ``VALUE`` is omitted then corresponding key will be removed from the
|
||
configuration (if it was present).
|
||
|
||
``-t THEME_NAME.KEY.NESTED_KEY=VALUE`` or ``--theme-override=THEME_NAME.KEY.NESTED_KEY=VALUE``
|
||
Overrides options from :file:`powerline/themes/{ext}/{THEME_NAME}.json`.
|
||
``KEY.NESTED_KEY=VALUE`` is processed like described above, ``{ext}`` is the
|
||
first argument to powerline script. May be passed multiple times.
|
||
|
||
If ``VALUE`` is omitted then corresponding key will be removed from the
|
||
configuration (if it was present).
|
||
|
||
``-p PATH`` or ``--config-path=PATH``
|
||
Sets directory where configuration should be read from. If present, no
|
||
default locations are searched for configuration. No expansions are
|
||
performed by powerline script itself, but ``-p ~/.powerline`` will likely be
|
||
expanded by the shell to something like ``-p /home/user/.powerline``.
|
||
|
||
.. warning::
|
||
Such overrides are suggested for testing purposes only. Use
|
||
:ref:`Environment variables overrides <local-configuration-overrides-env>`
|
||
for other purposes.
|
||
|
||
.. _local-configuration-overrides-env:
|
||
|
||
Environment variables overrides
|
||
===============================
|
||
|
||
All bindings that use ``POWERLINE_COMMAND`` environment variable support taking
|
||
overrides from environment variables. In this case overrides should look like
|
||
the following::
|
||
|
||
OVERRIDE='key1.key2.key3=value;key4.key5={"value":1};key6=true;key1.key7=10'
|
||
|
||
. This will be parsed into
|
||
|
||
.. code-block:: Python
|
||
|
||
{
|
||
"key1": {
|
||
"key2": {
|
||
"key3": "value"
|
||
},
|
||
"key7": 10,
|
||
},
|
||
"key4": {
|
||
"key5": {
|
||
"value": 1,
|
||
},
|
||
},
|
||
"key6": True,
|
||
}
|
||
|
||
. Rules:
|
||
|
||
#. Environment variable must form a semicolon-separated list of key-value pairs:
|
||
``key=value;key2=value2``.
|
||
#. Keys are always dot-separated strings that must not contain equals sign (as
|
||
well as semicolon) or start with an underscore. They are interpreted
|
||
literally and create a nested set of dictionaries: ``k1.k2.k3`` creates
|
||
``{"k1":{"k2":{}}}`` and inside the innermost dictionary last key (``k3`` in
|
||
the example) is contained with its value.
|
||
#. Value may be empty in which case they are interpreted as an order to remove
|
||
some value: ``k1.k2=`` will form ``{"k1":{"k2":REMOVE_THIS_KEY}}`` nested
|
||
dictionary where ``k2`` value is a special value that tells
|
||
dictionary-merging function to remove ``k2`` rather then replace it with
|
||
something.
|
||
#. Value may be a JSON strings like ``{"a":1}`` (JSON dictionary), ``["a",1]``
|
||
(JSON list), ``1`` or ``-1`` (JSON number), ``"abc"`` (JSON string) or
|
||
``true``, ``false`` and ``null`` (JSON boolean objects and ``Null`` object
|
||
from JSON). General rule is that anything starting with a digit (U+0030 till
|
||
U+0039, inclusive), a hyphenminus (U+002D), a quotation mark (U+0022), a left
|
||
curly bracket (U+007B) or a left square bracket (U+005B) is considered to be
|
||
some JSON object, same for *exact* values ``true``, ``false`` and ``null``.
|
||
#. Any other value is considered to be literal string: ``k1=foo:bar`` parses to
|
||
``{"k1": "foo:bar"}``.
|
||
|
||
The following environment variables may be used for overrides according to the
|
||
above rules:
|
||
|
||
``POWERLINE_CONFIG_OVERRIDES``
|
||
Overrides values from :file:`powerline/config.json`.
|
||
|
||
``POWERLINE_THEME_OVERRIDES``
|
||
Overrides values from :file:`powerline/themes/{ext}/{key}.json`. Top-level
|
||
key is treated as a name of the theme for which overrides are used: e.g. to
|
||
disable cwd segment defined in :file:`powerline/themes/shell/default.json`
|
||
one needs to use::
|
||
|
||
POWERLINE_THEME_OVERRIDES=default.segment_data.cwd.display=false
|
||
|
||
Additionally one environment variable is a usual *colon*-separated list of
|
||
directories: ``POWERLINE_CONFIG_PATHS``. This one defines paths which will be
|
||
searched for configuration. Empty paths in ``POWERLINE_CONFIG_PATHS`` are
|
||
ignored.
|
||
|
||
.. note::
|
||
Overrides from environment variables have lower priority then
|
||
:ref:`Powerline script overrides <local-configuration-overrides-script>`.
|
||
Latter are suggested for tests only.
|
||
|
||
Zsh/zpython overrides
|
||
=====================
|
||
|
||
Here overrides are controlled by similarly to the powerline script, but values
|
||
are taken from zsh variables. :ref:`Environment variable overrides
|
||
<local-configuration-overrides-env>` are also supported: if variable is a string
|
||
this variant is used.
|
||
|
||
``POWERLINE_CONFIG_OVERRIDES``
|
||
Overrides options from :file:`powerline/config.json`. Should be a zsh
|
||
associative array with keys equal to ``KEY.NESTED_KEY`` and values being
|
||
JSON strings. Pair ``KEY.KEY1 VALUE`` is equivalent to ``{"KEY": {"KEY1":
|
||
VALUE}}``. All pairs are then recursively merged into one dictionary and
|
||
this dictionary is recursively merged with the contents of the file.
|
||
|
||
``POWERLINE_THEME_OVERRIDES``
|
||
Overrides options from :file:`powerline/themes/shell/*.json`. Should be
|
||
a zsh associative array with keys equal to ``THEME_NAME.KEY.NESTED_KEY`` and
|
||
values being JSON strings. Is processed like the above
|
||
``POWERLINE_CONFIG_OVERRIDES``, but only subdictionaries for ``THEME_NAME``
|
||
key are merged with theme configuration when theme with given name is
|
||
requested.
|
||
|
||
``POWERLINE_CONFIG_PATHS``
|
||
Sets directories where configuration should be read from. If present, no
|
||
default locations are searched for configuration. No expansions are
|
||
performed by powerline script itself, but zsh usually performs them on its
|
||
own if variable without is set without quotes: ``POWERLINE_CONFIG_PATHS=(
|
||
~/example )``. In addition to arrays usual colon-separated “array” string
|
||
can be used: ``POWERLINE_CONFIG_PATHS=$HOME/path1:$HOME/path2``.
|
||
|
||
Ipython overrides
|
||
=================
|
||
|
||
Ipython overrides depend on ipython version. Before ipython-0.11 additional
|
||
keyword arguments should be passed to setup() function. After ipython-0.11
|
||
``c.Powerline.KEY`` should be used. Supported ``KEY`` strings or keyword
|
||
argument names:
|
||
|
||
``config_overrides``
|
||
Overrides options from :file:`powerline/config.json`. Should be a dictionary
|
||
that will be recursively merged with the contents of the file.
|
||
|
||
``theme_overrides``
|
||
Overrides options from :file:`powerline/themes/ipython/*.json`. Should be
|
||
a dictionary where keys are theme names and values are dictionaries which
|
||
will be recursively merged with the contents of the given theme.
|
||
|
||
``config_paths``
|
||
Sets directories where configuration should be read from. If present, no
|
||
default locations are searched for configuration. No expansions are
|
||
performed thus paths starting with ``~/`` cannot be used: use
|
||
:py:func:`os.path.expanduser`.
|
||
|
||
Prompt command
|
||
==============
|
||
|
||
In addition to the above configuration options ``$POWERLINE_COMMAND``
|
||
environment variable can be used to tell shell or tmux to use specific powerline
|
||
implementation and ``$POWERLINE_CONFIG_COMMAND`` to tell zsh or tmux where
|
||
``powerline-config`` script is located. This is mostly useful for putting
|
||
powerline into different directory.
|
||
|
||
.. note::
|
||
|
||
``$POWERLINE_COMMAND`` is always treated as one path in shell bindings, so
|
||
path with spaces in it may be used. To specify additional arguments one may
|
||
use ``$POWERLINE_COMMAND_ARGS``, but note that this variable exists for
|
||
testing purposes only and may be removed. One should use :ref:`Environment
|
||
variable overrides <local-configuration-overrides-env>` instead.
|
||
|
||
To disable prompt in shell, but still have tmux support or to disable tmux
|
||
support environment variables ``$POWERLINE_NO_{SHELL}_PROMPT`` and
|
||
``$POWERLINE_NO_{SHELL}_TMUX_SUPPORT`` can be used (substitute ``{SHELL}`` with
|
||
the name of the shell (all-caps) that should be affected (e.g. ``BASH``) or use
|
||
all-inclusive ``SHELL`` that will disable support for all shells). These
|
||
variables have no effect after configuration script was sourced (in fish case:
|
||
after ``powerline-setup`` function was run). To disable specific feature support
|
||
set one of these variables to some non-empty value.
|
||
|
||
In order to keep shell prompt, but avoid launching Python twice to get unused
|
||
:ref:`above <config-themes-above>` lines in tcsh ``$POWERLINE_NO_TCSH_ABOVE`` or
|
||
``$POWERLINE_NO_SHELL_ABOVE`` variable should be set.
|
||
|
||
In order to remove additional space from the end of the right prompt in fish
|
||
that was added in order to support multiline prompt ``$POWERLINE_NO_FISH_ABOVE``
|
||
or ``$POWERLINE_NO_SHELL_ABOVE`` variable should be set.
|
||
|
||
PDB overrides
|
||
=============
|
||
|
||
Like shell bindings :ref:`PDB bindings <pdb-prompt>` take overrides from
|
||
:ref:`environment variables <local-configuration-overrides-env>`.
|