mirror of
https://github.com/powerline/powerline.git
synced 2025-07-24 22:36:01 +02:00
commit
da6667bd14
@ -10,10 +10,20 @@ extensions = ['powerline_autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sp
|
||||
source_suffix = '.rst'
|
||||
master_doc = 'index'
|
||||
project = u'Powerline'
|
||||
copyright = u'Kim Silkebækken'
|
||||
version = 'beta'
|
||||
release = 'beta'
|
||||
exclude_patterns = ['_build']
|
||||
pygments_style = 'sphinx'
|
||||
html_theme = 'default'
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
html_static_path = ['_static']
|
||||
html_show_copyright = False
|
||||
|
||||
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
|
||||
|
||||
if not on_rtd: # only import and set the theme if we're building docs locally
|
||||
try:
|
||||
import sphinx_rtd_theme
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
||||
except ImportError:
|
||||
pass
|
||||
|
@ -1,6 +1,6 @@
|
||||
*************
|
||||
Configuration
|
||||
*************
|
||||
*******************************
|
||||
Configuration and customization
|
||||
*******************************
|
||||
|
||||
.. note:: **You DO NOT have to fork the main GitHub repo to personalize your
|
||||
Powerline configuration!** Please read through the :ref:`quick-guide` for
|
||||
@ -13,13 +13,13 @@ written in Python.
|
||||
|
||||
Powerline provides default configurations in the following locations:
|
||||
|
||||
`Main configuration`_
|
||||
:ref:`Main configuration <config-main>`
|
||||
:file:`powerline/config.json`
|
||||
`Colorschemes`_
|
||||
:ref:`Colorschemes <config-colors>`
|
||||
:file:`powerline/colorschemes/{name}.json`,
|
||||
:file:`powerline/colorscheme/__main__.json`,
|
||||
:file:`powerline/colorschemes/{extension}/{name}.json`
|
||||
`Themes`_
|
||||
:ref:`Themes <config-themes>`
|
||||
:file:`powerline/themes/{extension}/default.json`
|
||||
|
||||
The default configuration files are stored in the main package. User
|
||||
@ -27,6 +27,9 @@ configuration files are stored in :file:`$XDG_CONFIG_HOME/powerline` for
|
||||
Linux users, and in :file:`~/.config/powerline` for OS X users. This usually
|
||||
corresponds to :file:`~/.config/powerline` on both platforms.
|
||||
|
||||
If you need per-instance configuration please refer to :ref:`Local configuration
|
||||
overrides <local-configuration-overrides>`.
|
||||
|
||||
.. _quick-guide:
|
||||
|
||||
Quick setup guide
|
||||
@ -98,539 +101,12 @@ segments that you may want to customize right away:
|
||||
}
|
||||
},
|
||||
|
||||
.. _config-main:
|
||||
References
|
||||
==========
|
||||
|
||||
Main configuration
|
||||
==================
|
||||
.. toctree::
|
||||
:glob:
|
||||
|
||||
:Location: :file:`powerline/config.json`
|
||||
|
||||
The main configuration file defines some common options that applies to all
|
||||
extensions, as well as some extension-specific options like themes and
|
||||
colorschemes.
|
||||
|
||||
Common configuration
|
||||
--------------------
|
||||
|
||||
Common configuration is a subdictionary that is a value of ``common`` key in
|
||||
:file:`powerline/config.json` file.
|
||||
|
||||
.. _config-common-term_truecolor:
|
||||
|
||||
``term_truecolor``
|
||||
Defines whether to output cterm indices (8-bit) or RGB colors (24-bit)
|
||||
to the terminal emulator. See the :ref:`term-feature-support-matrix` for
|
||||
information on whether your terminal emulator supports 24-bit colors.
|
||||
|
||||
.. _config-common-ambiwidth:
|
||||
|
||||
``ambiwidth``
|
||||
Tells powerline what to do with characters with East Asian Width Class
|
||||
Ambigious (such as Euro, Registered Sign, Copyright Sign, Greek
|
||||
letters, Cyrillic letters). Valid values: any positive integer; it is
|
||||
suggested that you only set it to 1 (default) or 2.
|
||||
|
||||
``watcher``
|
||||
Select filesystem watcher. Variants are
|
||||
|
||||
======= ===================================
|
||||
Variant Description
|
||||
======= ===================================
|
||||
auto Selects most performant watcher.
|
||||
inotify Select inotify watcher. Linux only.
|
||||
stat Select stat-based polling watcher.
|
||||
======= ===================================
|
||||
|
||||
Default is ``auto``.
|
||||
|
||||
.. _config-common-additional_escapes:
|
||||
|
||||
``additional_escapes``
|
||||
Valid for shell extensions, makes sense only if :ref:`term_truecolor
|
||||
<config-common-term_truecolor>` is enabled. Is to be set from command-line
|
||||
(unless you are sure you always need it). Controls additional escaping that
|
||||
is needed for tmux/screen to work with terminal true color escape codes:
|
||||
normally tmux/screen prevent terminal emulator from receiving these control
|
||||
codes thus rendering powerline prompt colorless. Valid values: ``"tmux"``,
|
||||
``"screen"``, ``null`` (default).
|
||||
|
||||
``dividers``
|
||||
Defines the dividers used in all Powerline extensions. This option
|
||||
should usually only be changed if you don't have a patched font, or if
|
||||
you use a font patched with the legacy font patcher.
|
||||
|
||||
The ``hard`` dividers are used to divide segments with different
|
||||
background colors, while the ``soft`` dividers are used to divide
|
||||
segments with the same background color.
|
||||
|
||||
.. _config-common-paths:
|
||||
|
||||
``paths``
|
||||
Defines additional paths which will be searched for modules when using
|
||||
:ref:`module segment option <config-themes-seg-module>`. Paths defined here
|
||||
have priority when searching for modules.
|
||||
|
||||
``log_file``
|
||||
Defines path which will hold powerline logs. If not present, logging will be
|
||||
done to stderr.
|
||||
|
||||
``log_level``
|
||||
String, determines logging level. Defaults to ``WARNING``.
|
||||
|
||||
``log_format``
|
||||
String, determines format of the log messages. Defaults to
|
||||
``'%(asctime)s:%(level)s:%(message)s'``.
|
||||
|
||||
``interval``
|
||||
Number, determines time (in seconds) between checks for changed
|
||||
configuration. Checks are done in a seprate thread. Use ``null`` to check
|
||||
for configuration changes on ``.render()`` call in main thread.
|
||||
Defaults to ``None``.
|
||||
|
||||
``reload_config``
|
||||
Boolean, determines whether configuration should be reloaded at all.
|
||||
Defaults to ``True``.
|
||||
|
||||
Extension-specific configuration
|
||||
--------------------------------
|
||||
|
||||
Common configuration is a subdictionary that is a value of ``ext`` key in
|
||||
:file:`powerline/config.json` file.
|
||||
|
||||
``colorscheme``
|
||||
Defines the colorscheme used for this extension.
|
||||
|
||||
``theme``
|
||||
.. _config-ext-theme:
|
||||
|
||||
Defines the theme used for this extension.
|
||||
|
||||
``local_themes``
|
||||
.. _config-ext-local_themes:
|
||||
|
||||
Defines themes used when certain conditions are met, e.g. for
|
||||
buffer-specific statuslines in vim. Value depends on extension used. For vim
|
||||
it is a dictionary ``{matcher_name : theme_name}``, where ``matcher_name``
|
||||
is either ``matcher_module.module_attribute`` or ``module_attribute``
|
||||
(``matcher_module`` defaults to ``powerline.matchers.vim``) and
|
||||
``module_attribute`` should point to a function that returns boolean value
|
||||
indicating that current buffer has (not) matched conditions.
|
||||
|
||||
.. _config-colors:
|
||||
|
||||
Color definitions
|
||||
=================
|
||||
|
||||
:Location: :file:`powerline/colors.json`
|
||||
|
||||
.. _config-colors-colors:
|
||||
|
||||
``colors``
|
||||
Color definitions, consisting of a dict where the key is the name of the
|
||||
color, and the value is one of the following:
|
||||
|
||||
* A cterm color index.
|
||||
* A list with a cterm color index and a hex color string (e.g. ``[123,
|
||||
"aabbcc"]``). This is useful for colorschemes that use colors that
|
||||
aren't available in color terminals.
|
||||
|
||||
``gradients``
|
||||
Gradient definitions, consisting of a dict where the key is the name of the
|
||||
gradient, and the value is a list containing one or two items, second item
|
||||
is optional:
|
||||
|
||||
* A list of cterm color indicies.
|
||||
* A list of hex color strings.
|
||||
|
||||
It is expected that you define gradients from least alert color to most
|
||||
alert or use non-alert colors.
|
||||
|
||||
.. _config-colorschemes:
|
||||
|
||||
Colorschemes
|
||||
============
|
||||
|
||||
:Location: :file:`powerline/colorschemes/{name}.json`,
|
||||
:file:`powerline/colorscheme/__main__.json`,
|
||||
:file:`powerline/colorschemes/{extension}/{name}.json`
|
||||
|
||||
Colorscheme files are processed in order given: definitions from each next file
|
||||
override those from each previous file. It is required that either
|
||||
:file:`powerline/colorschemes/{name}.json`, or
|
||||
:file:`powerline/colorschemes/{extension}/{name}.json` exists.
|
||||
|
||||
``name``
|
||||
Name of the colorscheme.
|
||||
|
||||
.. _config-colorschemes-groups:
|
||||
|
||||
``groups``
|
||||
Segment highlighting groups, consisting of a dict where the key is the
|
||||
name of the highlighting group (usually the function name for function
|
||||
segments), and the value is either
|
||||
|
||||
#) a dict that defines the foreground color, background color and
|
||||
attributes:
|
||||
|
||||
``fg``
|
||||
Foreground color. Must be defined in :ref:`colors
|
||||
<config-colors-colors>`.
|
||||
|
||||
``bg``
|
||||
Background color. Must be defined in :ref:`colors
|
||||
<config-colors-colors>`.
|
||||
|
||||
``attr``
|
||||
List of attributes. Valid values are one or more of ``bold``,
|
||||
``italic`` and ``underline``. Note that some attributes may be
|
||||
unavailable in some applications or terminal emulators. If you do not
|
||||
need any attributes leave this empty.
|
||||
|
||||
#) a string (an alias): a name of existing group. This group’s definition
|
||||
will be used when this color is requested.
|
||||
|
||||
``mode_translations``
|
||||
Mode-specific highlighting for extensions that support it (e.g. the vim
|
||||
extension). It's an easy way of changing a color in a specific mode.
|
||||
Consists of a dict where the key is the mode and the value is a dict
|
||||
with the following options:
|
||||
|
||||
``colors``
|
||||
A dict where the key is the color to be translated in this mode, and
|
||||
the value is the new color. Both the key and the value must be defined
|
||||
in :ref:`colors <config-colors-colors>`.
|
||||
|
||||
``groups``
|
||||
Segment highlighting groups for this mode. Same syntax as the main
|
||||
:ref:`groups <config-colorschemes-groups>` option.
|
||||
|
||||
.. _config-themes:
|
||||
|
||||
Themes
|
||||
======
|
||||
|
||||
:Location: :file:`powerline/themes/{extension}/{name}.json`
|
||||
|
||||
``name``
|
||||
Name of the theme.
|
||||
|
||||
.. _config-themes-default_module:
|
||||
|
||||
``default_module``
|
||||
Python module where segments will be looked by default.
|
||||
|
||||
.. _config-themes-segment_data:
|
||||
|
||||
``segment_data``
|
||||
A dict where keys are segment names or strings ``{module}.{name}``. Used to
|
||||
specify default values for various keys:
|
||||
:ref:`after <config-theme-seg-after>`,
|
||||
:ref:`args <config-themes-seg-args>` (only for function segments),
|
||||
:ref:`before <config-theme-seg-before>`,
|
||||
:ref:`contents <config-theme-seg-contents>` (only for string segments
|
||||
if :ref:`name <config-themes-seg-name>` is defined),
|
||||
:ref:`display <config-theme-seg-display`.
|
||||
When using :ref:`local themes <config-ext-local_themes>` values of these
|
||||
keys are first searched in the segment description, then in ``segment_data``
|
||||
key of a local theme, then in ``segment_data`` key of a :ref:`default theme
|
||||
<config-ext-theme>`. For the :ref:`default theme <config-ext-theme>` itself
|
||||
step 2 is obviously avoided.
|
||||
|
||||
``segments``
|
||||
A dict with a ``left`` and a ``right`` lists, consisting of segment
|
||||
dictionaries. Shell themes may also contain ``above`` list of dictionaries.
|
||||
Each item in ``above`` list may have ``left`` and ``right`` keys like this
|
||||
dictionary, but no ``above`` key.
|
||||
|
||||
.. _config-themes-above:
|
||||
|
||||
``above`` list is used for multiline shell configurations.
|
||||
|
||||
``left`` and ``right`` lists are used for segments that should be put on the
|
||||
left or right side in the output. Actual mechanizm of putting segments on
|
||||
the left or the right depends on used renderer, but most renderers require
|
||||
one to specify segment with :ref:`width <config-themes-seg-width>` ``auto``
|
||||
on either side to make generated line fill all of the available width.
|
||||
|
||||
Each segment dictionary has the following options:
|
||||
|
||||
``type``
|
||||
The segment type. Can be one of ``function`` (default), ``string``
|
||||
or ``filler``:
|
||||
|
||||
``function``
|
||||
The segment contents is the return value of the function defined
|
||||
in the :ref:`name option <config-themes-seg-name>`.
|
||||
|
||||
``string``
|
||||
A static string segment where the contents is defined in the
|
||||
:ref:`contents option <config-themes-seg-contents>`, and the
|
||||
highlighting group is defined in the :ref:`highlight_group
|
||||
option <config-themes-seg-highlight_group>`.
|
||||
|
||||
``module``
|
||||
.. _config-themes-seg-module:
|
||||
|
||||
Function module, only required for function segments. Defaults to
|
||||
``powerline.segments.{extension}``. Default is overriden by
|
||||
:ref:`default_module theme option <config-themes-default_module>`.
|
||||
|
||||
``name``
|
||||
.. _config-themes-seg-name:
|
||||
|
||||
Function name, only required for function segments.
|
||||
|
||||
``highlight_group``
|
||||
.. _config-themes-seg-highlight_group:
|
||||
|
||||
Highlighting group for this segment. Consists of a prioritized list
|
||||
of highlighting groups, where the first highlighting group that is
|
||||
available in the colorscheme is used.
|
||||
|
||||
Ignored for segments that have ``function`` type.
|
||||
|
||||
``before``
|
||||
.. _config-themes-seg-before:
|
||||
|
||||
A string which will be prepended to the segment contents.
|
||||
|
||||
``after``
|
||||
.. _config-themes-seg-after:
|
||||
|
||||
A string which will be appended to the segment contents.
|
||||
|
||||
``contents``
|
||||
.. _config-themes-seg-contents:
|
||||
|
||||
Segment contents, only required for ``string`` segments.
|
||||
|
||||
``args``
|
||||
.. _config-themes-seg-args:
|
||||
|
||||
A dict of arguments to be passed to a ``function`` segment.
|
||||
|
||||
``align``
|
||||
Aligns the segments contents to the left (``l``), center (``c``) or
|
||||
right (``r``).
|
||||
|
||||
``width``
|
||||
.. _config-themes-seg-width:
|
||||
|
||||
Enforces a specific width for this segment.
|
||||
|
||||
This segment will work as a spacer if the width is set to ``auto``.
|
||||
Several spacers may be used, and the space will be distributed
|
||||
equally among all the spacer segments. Spacers may have contents,
|
||||
either returned by a function or a static string, and the contents
|
||||
can be aligned with the ``align`` property.
|
||||
|
||||
``priority``
|
||||
Optional segment priority. Segments with priority ``None`` (the default
|
||||
priority, represented by ``null`` in json) will always be included,
|
||||
regardless of the width of the prompt/statusline.
|
||||
|
||||
If the priority is any number, the segment may be removed if the
|
||||
prompt/statusline width is too small for all the segments to be
|
||||
rendered. A lower number means that the segment has a higher priority.
|
||||
|
||||
Segments are removed according to their priority, with low priority
|
||||
segments being removed first.
|
||||
|
||||
``draw_hard_divider``, ``draw_soft_divider``
|
||||
Whether to draw a divider between this and the adjacent segment. The
|
||||
adjacent segment is to the *right* for segments on the *left* side, and
|
||||
vice versa. Hard dividers are used between segments with different
|
||||
background colors, soft ones are used between segments with same
|
||||
background. Both options default to ``True``.
|
||||
|
||||
``draw_inner_divider``
|
||||
Determines whether inner soft dividers are to be drawn for function
|
||||
segments. Only applicable for functions returning multiple segments.
|
||||
Defaults to ``False``.
|
||||
|
||||
``exclude_modes``
|
||||
A list of modes where this segment will be excluded: The segment is
|
||||
included in all modes, *except* for the modes in this list.
|
||||
|
||||
``include_modes``
|
||||
A list of modes where this segment will be included: The segment is
|
||||
*not* included in any modes, *except* for the modes in this list.
|
||||
|
||||
``display``
|
||||
.. _config-themes-seg-display:
|
||||
|
||||
Boolean. If false disables displaying of the segment.
|
||||
Defaults to ``True``.
|
||||
|
||||
Segments
|
||||
========
|
||||
|
||||
Segments are written in Python, and the default segments provided with
|
||||
Powerline are located in :file:`powerline/segments/{extension}.py`.
|
||||
User-defined segments can be defined in any module in ``sys.path`` or
|
||||
:ref:`paths common configuration option <config-common-paths>`, import is
|
||||
always absolute.
|
||||
|
||||
Segments are regular Python functions, and they may accept arguments. All
|
||||
arguments should have a default value which will be used for themes that
|
||||
don't provide an ``args`` dict.
|
||||
|
||||
A segment function must return one of the following values:
|
||||
|
||||
* ``None``, which will remove the segment from the prompt/statusline.
|
||||
* A string, which will be the segment contents.
|
||||
* A list of dicts consisting of a ``contents`` string, and
|
||||
a ``highlight_group`` list. This is useful for providing a particular
|
||||
highlighting group depending on the segment contents.
|
||||
|
||||
Local configuration
|
||||
===================
|
||||
|
||||
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:
|
||||
|
||||
``g:powerline_config_overrides``
|
||||
Dictionary, recursively merged with contents of
|
||||
:file:`powerline/config.json`.
|
||||
|
||||
``g:powerline_theme_overrides__{theme_name}``
|
||||
Dictionary, recursively merged with contents of
|
||||
:file:`powerline/themes/vim/{theme_name}.json`. Note that this way you can’t
|
||||
redefine some value (e.g. segment) in list, only the whole list itself: only
|
||||
dictionaries are merged recursively.
|
||||
|
||||
``g:powerline_config_path``
|
||||
Path (must be expanded, ``~`` shortcut is not supported). Points to the
|
||||
directory 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.
|
||||
|
||||
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=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_option=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``.
|
||||
|
||||
Zsh/zpython overrides
|
||||
---------------------
|
||||
|
||||
Here overrides are controlled by similarly to the powerline script, but values
|
||||
are taken from zsh variables.
|
||||
|
||||
``POWERLINE_CONFIG``
|
||||
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_CONFIG``
|
||||
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``,
|
||||
but only subdictionaries for ``THEME_NAME`` key are merged with theme
|
||||
configuration when theme with given name is requested.
|
||||
|
||||
``POWERLINE_CONFIG_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 zsh usually performs them on its
|
||||
own if you set variable without quotes: ``POWERLINE_CONFIG_PATH=~/example``.
|
||||
Expansion depends on zsh configuration.
|
||||
|
||||
Ipython overrides
|
||||
-----------------
|
||||
|
||||
Ipython overrides depend on ipython version. Before ipython-0.11 you should pass
|
||||
additional keyword arguments to setup() function. After ipython-0.11 you should
|
||||
use ``c.Powerline.KEY``. 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.
|
||||
|
||||
``path``
|
||||
Sets directory where configuration should be read from. If present, no
|
||||
default locations are searched for configuration. No expansions are
|
||||
performed thus you cannot use paths starting with ``~/``.
|
||||
|
||||
Prompt command
|
||||
--------------
|
||||
|
||||
In addition to the above configuration options you can use
|
||||
``$POWERLINE_COMMAND`` environment variable to tell shell or tmux to use
|
||||
specific powerline implementation. This is mostly useful for putting powerline
|
||||
into different directory or replacing ``powerline`` script with
|
||||
``powerline-client`` for performance reasons.
|
||||
|
||||
.. note::
|
||||
|
||||
``$POWERLINE_COMMAND`` appears in shell scripts without quotes thus you can
|
||||
specify additional parameters in bash. In zsh you will have to make
|
||||
``$POWERLINE_COMMAND`` an array parameter to achieve the same result. In
|
||||
tmux it is passed to ``eval`` and depends on the shell used.
|
||||
POSIX-compatible shells, zsh, bash and fish will split this variable in this
|
||||
case.
|
||||
|
||||
If you want to disable prompt in shell, but still have tmux support or if you
|
||||
want to disable tmux support you can use variables
|
||||
``$POWERLINE_NO_{SHELL}_PROMPT``/``$POWERLINE_NO_SHELL_PROMPT`` and
|
||||
``$POWERLINE_NO_{SHELL}_TMUX_SUPPORT``/``$POWERLINE_NO_SHELL_TMUX_SUPPORT``
|
||||
(substitute ``{SHELL}`` with the name of the shell (all-caps) you want to
|
||||
disable support for (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.
|
||||
|
||||
If you do not want to disable prompt in shell, but yet do not want to launch
|
||||
python twice to get :ref:`above <config-themes-above>` lines you do not use in
|
||||
tcsh you should set ``$POWERLINE_NO_TCSH_ABOVE`` or
|
||||
``$POWERLINE_NO_SHELL_ABOVE`` variable.
|
||||
|
||||
If you do not want to see additional space which is added to the right prompt in
|
||||
fish in order to support multiline prompt you should set
|
||||
``$POWERLINE_NO_FISH_ABOVE`` or ``$POWERLINE_NO_SHELL_ABOVE`` variables.
|
||||
|
||||
.. note::
|
||||
|
||||
Most supported shells’ configuration scripts check for additional
|
||||
configuration variables being empty. But tcsh configuration script checks
|
||||
for variables being *defined*, not empty.
|
||||
configuration/reference
|
||||
configuration/segments
|
||||
configuration/local
|
||||
|
154
docs/source/configuration/local.rst
Normal file
154
docs/source/configuration/local.rst
Normal file
@ -0,0 +1,154 @@
|
||||
.. _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:
|
||||
|
||||
``g:powerline_config_overrides``
|
||||
Dictionary, recursively merged with contents of
|
||||
:file:`powerline/config.json`.
|
||||
|
||||
``g:powerline_theme_overrides__{theme_name}``
|
||||
Dictionary, recursively merged with contents of
|
||||
:file:`powerline/themes/vim/{theme_name}.json`. Note that this way you can’t
|
||||
redefine some value (e.g. segment) in list, only the whole list itself: only
|
||||
dictionaries are merged recursively.
|
||||
|
||||
``g:powerline_config_path``
|
||||
Path (must be expanded, ``~`` shortcut is not supported). Points to the
|
||||
directory 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.
|
||||
|
||||
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=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_option=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``.
|
||||
|
||||
Zsh/zpython overrides
|
||||
=====================
|
||||
|
||||
Here overrides are controlled by similarly to the powerline script, but values
|
||||
are taken from zsh variables.
|
||||
|
||||
``POWERLINE_CONFIG``
|
||||
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_CONFIG``
|
||||
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``,
|
||||
but only subdictionaries for ``THEME_NAME`` key are merged with theme
|
||||
configuration when theme with given name is requested.
|
||||
|
||||
``POWERLINE_CONFIG_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 zsh usually performs them on its
|
||||
own if you set variable without quotes: ``POWERLINE_CONFIG_PATH=~/example``.
|
||||
Expansion depends on zsh configuration.
|
||||
|
||||
Ipython overrides
|
||||
=================
|
||||
|
||||
Ipython overrides depend on ipython version. Before ipython-0.11 you should pass
|
||||
additional keyword arguments to setup() function. After ipython-0.11 you should
|
||||
use ``c.Powerline.KEY``. 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.
|
||||
|
||||
``path``
|
||||
Sets directory where configuration should be read from. If present, no
|
||||
default locations are searched for configuration. No expansions are
|
||||
performed thus you cannot use paths starting with ``~/``.
|
||||
|
||||
Prompt command
|
||||
==============
|
||||
|
||||
In addition to the above configuration options you can use
|
||||
``$POWERLINE_COMMAND`` environment variable to tell shell or tmux to use
|
||||
specific powerline implementation. This is mostly useful for putting powerline
|
||||
into different directory or replacing ``powerline`` script with
|
||||
``powerline-client`` for performance reasons.
|
||||
|
||||
.. note::
|
||||
|
||||
``$POWERLINE_COMMAND`` appears in shell scripts without quotes thus you can
|
||||
specify additional parameters in bash. In zsh you will have to make
|
||||
``$POWERLINE_COMMAND`` an array parameter to achieve the same result. In
|
||||
tmux it is passed to ``eval`` and depends on the shell used.
|
||||
POSIX-compatible shells, zsh, bash and fish will split this variable in this
|
||||
case.
|
||||
|
||||
If you want to disable prompt in shell, but still have tmux support or if you
|
||||
want to disable tmux support you can use variables
|
||||
``$POWERLINE_NO_{SHELL}_PROMPT``/``$POWERLINE_NO_SHELL_PROMPT`` and
|
||||
``$POWERLINE_NO_{SHELL}_TMUX_SUPPORT``/``$POWERLINE_NO_SHELL_TMUX_SUPPORT``
|
||||
(substitute ``{SHELL}`` with the name of the shell (all-caps) you want to
|
||||
disable support for (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.
|
||||
|
||||
If you do not want to disable prompt in shell, but yet do not want to launch
|
||||
python twice to get :ref:`above <config-themes-above>` lines you do not use in
|
||||
tcsh you should set ``$POWERLINE_NO_TCSH_ABOVE`` or
|
||||
``$POWERLINE_NO_SHELL_ABOVE`` variable.
|
||||
|
||||
If you do not want to see additional space which is added to the right prompt in
|
||||
fish in order to support multiline prompt you should set
|
||||
``$POWERLINE_NO_FISH_ABOVE`` or ``$POWERLINE_NO_SHELL_ABOVE`` variables.
|
||||
|
||||
.. note::
|
||||
|
||||
Most supported shells’ configuration scripts check for additional
|
||||
configuration variables being empty. But tcsh configuration script checks
|
||||
for variables being *defined*, not empty.
|
368
docs/source/configuration/reference.rst
Normal file
368
docs/source/configuration/reference.rst
Normal file
@ -0,0 +1,368 @@
|
||||
***********************
|
||||
Configuration reference
|
||||
***********************
|
||||
|
||||
.. _config-main:
|
||||
|
||||
Main configuration
|
||||
==================
|
||||
|
||||
:Location: :file:`powerline/config.json`
|
||||
|
||||
The main configuration file defines some common options that applies to all
|
||||
extensions, as well as some extension-specific options like themes and
|
||||
colorschemes.
|
||||
|
||||
Common configuration
|
||||
--------------------
|
||||
|
||||
Common configuration is a subdictionary that is a value of ``common`` key in
|
||||
:file:`powerline/config.json` file.
|
||||
|
||||
.. _config-common-term_truecolor:
|
||||
|
||||
``term_truecolor``
|
||||
Defines whether to output cterm indices (8-bit) or RGB colors (24-bit)
|
||||
to the terminal emulator. See the :ref:`term-feature-support-matrix` for
|
||||
information on whether your terminal emulator supports 24-bit colors.
|
||||
|
||||
.. _config-common-ambiwidth:
|
||||
|
||||
``ambiwidth``
|
||||
Tells powerline what to do with characters with East Asian Width Class
|
||||
Ambigious (such as Euro, Registered Sign, Copyright Sign, Greek
|
||||
letters, Cyrillic letters). Valid values: any positive integer; it is
|
||||
suggested that you only set it to 1 (default) or 2.
|
||||
|
||||
``watcher``
|
||||
Select filesystem watcher. Variants are
|
||||
|
||||
======= ===================================
|
||||
Variant Description
|
||||
======= ===================================
|
||||
auto Selects most performant watcher.
|
||||
inotify Select inotify watcher. Linux only.
|
||||
stat Select stat-based polling watcher.
|
||||
======= ===================================
|
||||
|
||||
Default is ``auto``.
|
||||
|
||||
.. _config-common-additional_escapes:
|
||||
|
||||
``additional_escapes``
|
||||
Valid for shell extensions, makes sense only if :ref:`term_truecolor
|
||||
<config-common-term_truecolor>` is enabled. Is to be set from command-line
|
||||
(unless you are sure you always need it). Controls additional escaping that
|
||||
is needed for tmux/screen to work with terminal true color escape codes:
|
||||
normally tmux/screen prevent terminal emulator from receiving these control
|
||||
codes thus rendering powerline prompt colorless. Valid values: ``"tmux"``,
|
||||
``"screen"``, ``null`` (default).
|
||||
|
||||
``dividers``
|
||||
Defines the dividers used in all Powerline extensions. This option
|
||||
should usually only be changed if you don't have a patched font, or if
|
||||
you use a font patched with the legacy font patcher.
|
||||
|
||||
The ``hard`` dividers are used to divide segments with different
|
||||
background colors, while the ``soft`` dividers are used to divide
|
||||
segments with the same background color.
|
||||
|
||||
.. _config-common-paths:
|
||||
|
||||
``paths``
|
||||
Defines additional paths which will be searched for modules when using
|
||||
:ref:`module segment option <config-themes-seg-module>`. Paths defined here
|
||||
have priority when searching for modules.
|
||||
|
||||
``log_file``
|
||||
Defines path which will hold powerline logs. If not present, logging will be
|
||||
done to stderr.
|
||||
|
||||
``log_level``
|
||||
String, determines logging level. Defaults to ``WARNING``.
|
||||
|
||||
``log_format``
|
||||
String, determines format of the log messages. Defaults to
|
||||
``'%(asctime)s:%(level)s:%(message)s'``.
|
||||
|
||||
``interval``
|
||||
Number, determines time (in seconds) between checks for changed
|
||||
configuration. Checks are done in a seprate thread. Use ``null`` to check
|
||||
for configuration changes on ``.render()`` call in main thread.
|
||||
Defaults to ``None``.
|
||||
|
||||
``reload_config``
|
||||
Boolean, determines whether configuration should be reloaded at all.
|
||||
Defaults to ``True``.
|
||||
|
||||
Extension-specific configuration
|
||||
--------------------------------
|
||||
|
||||
Common configuration is a subdictionary that is a value of ``ext`` key in
|
||||
:file:`powerline/config.json` file.
|
||||
|
||||
``colorscheme``
|
||||
Defines the colorscheme used for this extension.
|
||||
|
||||
``theme``
|
||||
.. _config-ext-theme:
|
||||
|
||||
Defines the theme used for this extension.
|
||||
|
||||
``local_themes``
|
||||
.. _config-ext-local_themes:
|
||||
|
||||
Defines themes used when certain conditions are met, e.g. for
|
||||
buffer-specific statuslines in vim. Value depends on extension used. For vim
|
||||
it is a dictionary ``{matcher_name : theme_name}``, where ``matcher_name``
|
||||
is either ``matcher_module.module_attribute`` or ``module_attribute``
|
||||
(``matcher_module`` defaults to ``powerline.matchers.vim``) and
|
||||
``module_attribute`` should point to a function that returns boolean value
|
||||
indicating that current buffer has (not) matched conditions.
|
||||
|
||||
.. _config-colors:
|
||||
|
||||
Color definitions
|
||||
=================
|
||||
|
||||
:Location: :file:`powerline/colors.json`
|
||||
|
||||
.. _config-colors-colors:
|
||||
|
||||
``colors``
|
||||
Color definitions, consisting of a dict where the key is the name of the
|
||||
color, and the value is one of the following:
|
||||
|
||||
* A cterm color index.
|
||||
* A list with a cterm color index and a hex color string (e.g. ``[123,
|
||||
"aabbcc"]``). This is useful for colorschemes that use colors that
|
||||
aren't available in color terminals.
|
||||
|
||||
``gradients``
|
||||
Gradient definitions, consisting of a dict where the key is the name of the
|
||||
gradient, and the value is a list containing one or two items, second item
|
||||
is optional:
|
||||
|
||||
* A list of cterm color indicies.
|
||||
* A list of hex color strings.
|
||||
|
||||
It is expected that you define gradients from least alert color to most
|
||||
alert or use non-alert colors.
|
||||
|
||||
.. _config-colorschemes:
|
||||
|
||||
Colorschemes
|
||||
============
|
||||
|
||||
:Location: :file:`powerline/colorschemes/{name}.json`,
|
||||
:file:`powerline/colorscheme/__main__.json`,
|
||||
:file:`powerline/colorschemes/{extension}/{name}.json`
|
||||
|
||||
Colorscheme files are processed in order given: definitions from each next file
|
||||
override those from each previous file. It is required that either
|
||||
:file:`powerline/colorschemes/{name}.json`, or
|
||||
:file:`powerline/colorschemes/{extension}/{name}.json` exists.
|
||||
|
||||
``name``
|
||||
Name of the colorscheme.
|
||||
|
||||
.. _config-colorschemes-groups:
|
||||
|
||||
``groups``
|
||||
Segment highlighting groups, consisting of a dict where the key is the
|
||||
name of the highlighting group (usually the function name for function
|
||||
segments), and the value is either
|
||||
|
||||
#) a dict that defines the foreground color, background color and
|
||||
attributes:
|
||||
|
||||
``fg``
|
||||
Foreground color. Must be defined in :ref:`colors
|
||||
<config-colors-colors>`.
|
||||
|
||||
``bg``
|
||||
Background color. Must be defined in :ref:`colors
|
||||
<config-colors-colors>`.
|
||||
|
||||
``attr``
|
||||
List of attributes. Valid values are one or more of ``bold``,
|
||||
``italic`` and ``underline``. Note that some attributes may be
|
||||
unavailable in some applications or terminal emulators. If you do not
|
||||
need any attributes leave this empty.
|
||||
|
||||
#) a string (an alias): a name of existing group. This group’s definition
|
||||
will be used when this color is requested.
|
||||
|
||||
``mode_translations``
|
||||
Mode-specific highlighting for extensions that support it (e.g. the vim
|
||||
extension). It's an easy way of changing a color in a specific mode.
|
||||
Consists of a dict where the key is the mode and the value is a dict
|
||||
with the following options:
|
||||
|
||||
``colors``
|
||||
A dict where the key is the color to be translated in this mode, and
|
||||
the value is the new color. Both the key and the value must be defined
|
||||
in :ref:`colors <config-colors-colors>`.
|
||||
|
||||
``groups``
|
||||
Segment highlighting groups for this mode. Same syntax as the main
|
||||
:ref:`groups <config-colorschemes-groups>` option.
|
||||
|
||||
.. _config-themes:
|
||||
|
||||
Themes
|
||||
======
|
||||
|
||||
:Location: :file:`powerline/themes/{extension}/{name}.json`
|
||||
|
||||
``name``
|
||||
Name of the theme.
|
||||
|
||||
.. _config-themes-default_module:
|
||||
|
||||
``default_module``
|
||||
Python module where segments will be looked by default.
|
||||
|
||||
.. _config-themes-segment_data:
|
||||
|
||||
``segment_data``
|
||||
A dict where keys are segment names or strings ``{module}.{name}``. Used to
|
||||
specify default values for various keys:
|
||||
:ref:`after <config-themes-seg-after>`,
|
||||
:ref:`args <config-themes-seg-args>` (only for function segments),
|
||||
:ref:`before <config-themes-seg-before>`,
|
||||
:ref:`contents <config-themes-seg-contents>` (only for string segments
|
||||
if :ref:`name <config-themes-seg-name>` is defined),
|
||||
:ref:`display <config-themes-seg-display>`.
|
||||
When using :ref:`local themes <config-ext-local_themes>` values of these
|
||||
keys are first searched in the segment description, then in ``segment_data``
|
||||
key of a local theme, then in ``segment_data`` key of a :ref:`default theme
|
||||
<config-ext-theme>`. For the :ref:`default theme <config-ext-theme>` itself
|
||||
step 2 is obviously avoided.
|
||||
|
||||
``segments``
|
||||
A dict with a ``left`` and a ``right`` lists, consisting of segment
|
||||
dictionaries. Shell themes may also contain ``above`` list of dictionaries.
|
||||
Each item in ``above`` list may have ``left`` and ``right`` keys like this
|
||||
dictionary, but no ``above`` key.
|
||||
|
||||
.. _config-themes-above:
|
||||
|
||||
``above`` list is used for multiline shell configurations.
|
||||
|
||||
``left`` and ``right`` lists are used for segments that should be put on the
|
||||
left or right side in the output. Actual mechanizm of putting segments on
|
||||
the left or the right depends on used renderer, but most renderers require
|
||||
one to specify segment with :ref:`width <config-themes-seg-width>` ``auto``
|
||||
on either side to make generated line fill all of the available width.
|
||||
|
||||
Each segment dictionary has the following options:
|
||||
|
||||
``type``
|
||||
The segment type. Can be one of ``function`` (default), ``string``
|
||||
or ``filler``:
|
||||
|
||||
``function``
|
||||
The segment contents is the return value of the function defined
|
||||
in the :ref:`name option <config-themes-seg-name>`.
|
||||
|
||||
``string``
|
||||
A static string segment where the contents is defined in the
|
||||
:ref:`contents option <config-themes-seg-contents>`, and the
|
||||
highlighting group is defined in the :ref:`highlight_group
|
||||
option <config-themes-seg-highlight_group>`.
|
||||
|
||||
``module``
|
||||
.. _config-themes-seg-module:
|
||||
|
||||
Function module, only required for function segments. Defaults to
|
||||
``powerline.segments.{extension}``. Default is overriden by
|
||||
:ref:`default_module theme option <config-themes-default_module>`.
|
||||
|
||||
``name``
|
||||
.. _config-themes-seg-name:
|
||||
|
||||
Function name, only required for function segments.
|
||||
|
||||
``highlight_group``
|
||||
.. _config-themes-seg-highlight_group:
|
||||
|
||||
Highlighting group for this segment. Consists of a prioritized list
|
||||
of highlighting groups, where the first highlighting group that is
|
||||
available in the colorscheme is used.
|
||||
|
||||
Ignored for segments that have ``function`` type.
|
||||
|
||||
``before``
|
||||
.. _config-themes-seg-before:
|
||||
|
||||
A string which will be prepended to the segment contents.
|
||||
|
||||
``after``
|
||||
.. _config-themes-seg-after:
|
||||
|
||||
A string which will be appended to the segment contents.
|
||||
|
||||
``contents``
|
||||
.. _config-themes-seg-contents:
|
||||
|
||||
Segment contents, only required for ``string`` segments.
|
||||
|
||||
``args``
|
||||
.. _config-themes-seg-args:
|
||||
|
||||
A dict of arguments to be passed to a ``function`` segment.
|
||||
|
||||
``align``
|
||||
Aligns the segments contents to the left (``l``), center (``c``) or
|
||||
right (``r``).
|
||||
|
||||
``width``
|
||||
.. _config-themes-seg-width:
|
||||
|
||||
Enforces a specific width for this segment.
|
||||
|
||||
This segment will work as a spacer if the width is set to ``auto``.
|
||||
Several spacers may be used, and the space will be distributed
|
||||
equally among all the spacer segments. Spacers may have contents,
|
||||
either returned by a function or a static string, and the contents
|
||||
can be aligned with the ``align`` property.
|
||||
|
||||
``priority``
|
||||
Optional segment priority. Segments with priority ``None`` (the default
|
||||
priority, represented by ``null`` in json) will always be included,
|
||||
regardless of the width of the prompt/statusline.
|
||||
|
||||
If the priority is any number, the segment may be removed if the
|
||||
prompt/statusline width is too small for all the segments to be
|
||||
rendered. A lower number means that the segment has a higher priority.
|
||||
|
||||
Segments are removed according to their priority, with low priority
|
||||
segments being removed first.
|
||||
|
||||
``draw_hard_divider``, ``draw_soft_divider``
|
||||
Whether to draw a divider between this and the adjacent segment. The
|
||||
adjacent segment is to the *right* for segments on the *left* side, and
|
||||
vice versa. Hard dividers are used between segments with different
|
||||
background colors, soft ones are used between segments with same
|
||||
background. Both options default to ``True``.
|
||||
|
||||
``draw_inner_divider``
|
||||
Determines whether inner soft dividers are to be drawn for function
|
||||
segments. Only applicable for functions returning multiple segments.
|
||||
Defaults to ``False``.
|
||||
|
||||
``exclude_modes``
|
||||
A list of modes where this segment will be excluded: The segment is
|
||||
included in all modes, *except* for the modes in this list.
|
||||
|
||||
``include_modes``
|
||||
A list of modes where this segment will be included: The segment is
|
||||
*not* included in any modes, *except* for the modes in this list.
|
||||
|
||||
``display``
|
||||
|
||||
.. _config-themes-seg-display:
|
||||
|
||||
Boolean. If false disables displaying of the segment.
|
||||
Defaults to ``True``.
|
32
docs/source/configuration/segments.rst
Normal file
32
docs/source/configuration/segments.rst
Normal file
@ -0,0 +1,32 @@
|
||||
*****************
|
||||
Segment reference
|
||||
*****************
|
||||
|
||||
Segments
|
||||
========
|
||||
|
||||
Segments are written in Python, and the default segments provided with
|
||||
Powerline are located in :file:`powerline/segments/{extension}.py`.
|
||||
User-defined segments can be defined in any module in ``sys.path`` or
|
||||
:ref:`paths common configuration option <config-common-paths>`, import is
|
||||
always absolute.
|
||||
|
||||
Segments are regular Python functions, and they may accept arguments. All
|
||||
arguments should have a default value which will be used for themes that
|
||||
don't provide an ``args`` dict.
|
||||
|
||||
A segment function must return one of the following values:
|
||||
|
||||
* ``None``, which will remove the segment from the prompt/statusline.
|
||||
* A string, which will be the segment contents.
|
||||
* A list of dicts consisting of a ``contents`` string, and
|
||||
a ``highlight_group`` list. This is useful for providing a particular
|
||||
highlighting group depending on the segment contents.
|
||||
|
||||
Available segments
|
||||
==================
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
|
||||
segments/*
|
@ -1,136 +0,0 @@
|
||||
.. _font-patching:
|
||||
|
||||
*************
|
||||
Font patching
|
||||
*************
|
||||
|
||||
Powerline provides a font patcher for custom glyphs like the segment
|
||||
dividers (arrows), branch symbol, padlock symbol, etc. The font patcher
|
||||
requires FontForge with Python bindings to work.
|
||||
|
||||
Check out the `powerline-fonts
|
||||
<https://github.com/Lokaltog/powerline-fonts>`_ repository on GitHub for
|
||||
patched versions of some popular programming fonts.
|
||||
|
||||
.. warning:: The code points have changed in this version of Powerline! This
|
||||
means that you either have to patch your font again, or change the glyphs
|
||||
Powerline uses in your user configuration.
|
||||
|
||||
.. note:: Powerline no longer works with rxvt-unicode unless you either use
|
||||
rxvt-unicode compiled with ``--enable-unicode3``, or you use fonts patched
|
||||
with the legacy font patcher and change the glyphs in your user
|
||||
configuration.
|
||||
|
||||
Glyph table
|
||||
===========
|
||||
|
||||
Powerline stores all special glyphs in the Unicode *Private Use Area*
|
||||
(``U+E000``-``U+F8FF``).
|
||||
|
||||
========== ===== ===========
|
||||
Code point Glyph Description
|
||||
========== ===== ===========
|
||||
``U+E0A0`` Version control branch
|
||||
``U+E0A1`` LN (line) symbol
|
||||
``U+E0A2`` Closed padlock
|
||||
``U+E0B0`` Rightwards black arrowhead
|
||||
``U+E0B1`` Rightwards arrowhead
|
||||
``U+E0B2`` Leftwards black arrowhead
|
||||
``U+E0B3`` Leftwards arrowhead
|
||||
========== ===== ===========
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
The font patcher, :file:`fontpatcher.py` is located in the `powerline-fontpatcher
|
||||
<https://github.com/Lokaltog/powerline-fontpatcher>`_ repository on GitHub.
|
||||
It requires Python 2.7 and FontForge compiled with Python bindings to work.
|
||||
|
||||
Patched fonts are renamed by default (" for Powerline" is added to the font
|
||||
name) so they don't conflict with existing fonts. Use the ``--no-rename``
|
||||
option to disable font renaming.
|
||||
|
||||
.. note:: Bitmap fonts are not supported, and will probably never be
|
||||
supported officially due to difficulty creating a font patcher that works
|
||||
for bitmap fonts. The recommended method of patching bitmap fonts is to draw
|
||||
the glyphs manually using a tool like ``gbdfed``.
|
||||
|
||||
Linux
|
||||
-----
|
||||
|
||||
1. Install fontforge with Python bindings. For Ubuntu users the required
|
||||
package is ``python-fontforge``, for Arch Linux users the required
|
||||
package is ``fontforge``. It should be something similar for other
|
||||
distros.
|
||||
|
||||
2. Run the font patcher::
|
||||
|
||||
$ /path/to/fontpatcher.py MyFontFile.ttf
|
||||
|
||||
3. Copy the font file into :file:`~/.fonts` (or another X font directory)::
|
||||
|
||||
$ cp "MyFontFile for Powerline.otf" ~/.fonts
|
||||
|
||||
4. Update your font cache::
|
||||
|
||||
$ fc-cache -vf ~/.fonts
|
||||
|
||||
If you're using vim in a terminal you may need to close all open terminal
|
||||
windows after updating the font cache.
|
||||
|
||||
5. **Gvim users:** Update the GUI font in your :file:`vimrc` file::
|
||||
|
||||
set guifont=MyFont\ for\ Powerline
|
||||
|
||||
**Terminal users:** Update your terminal configuration to use the patched
|
||||
font.
|
||||
|
||||
6. Open vim and enjoy your new statusline!
|
||||
|
||||
OS X
|
||||
----
|
||||
|
||||
1. Check if you have a FontForge version with Python support by running
|
||||
``fontforge -version``. You should see something like this::
|
||||
|
||||
$ fontforge -version
|
||||
Copyright (c) 2000-2011 by George Williams.
|
||||
Executable based on sources from 13:48 GMT 22-Feb-2011-D.
|
||||
Library based on sources from 13:48 GMT 22-Feb-2011.
|
||||
fontforge 20110222
|
||||
libfontforge 20110222
|
||||
|
||||
Make sure that the executable version number doesn't have ``NoPython`` in
|
||||
it. If everything looks OK, skip ahead to step 4.
|
||||
|
||||
2. If you have FontForge but with ``NoPython`` in the version number, please
|
||||
try to update to a later version::
|
||||
|
||||
$ brew uninstall fontforge
|
||||
$ brew update
|
||||
$ brew install fontforge
|
||||
|
||||
**Note:** You may have to use ``--use-clang`` instead of ``--use-gcc``
|
||||
when compiling FontForge.
|
||||
|
||||
3. If you don't have FontForge, install it with Homebrew::
|
||||
|
||||
$ brew update
|
||||
$ brew install fontforge
|
||||
|
||||
4. Patch your fonts by passing the ``fontpatcher`` script as a parameter to
|
||||
FontForge::
|
||||
|
||||
$ fontforge -script /path/to/fontpatcher.py MyFontFile.ttf
|
||||
|
||||
5. Install the font by double-clicking the font file in Finder and click
|
||||
"Install this font" from the preview window.
|
||||
|
||||
6. **Gvim users:** Update the GUI font in your :file:`vimrc` file::
|
||||
|
||||
set guifont=MyFont\ for\ Powerline
|
||||
|
||||
**Terminal users:** Update your terminal configuration to use the patched
|
||||
font.
|
||||
|
||||
7. Open vim and enjoy your new statusline!
|
@ -3,23 +3,16 @@ Powerline
|
||||
*********
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 3
|
||||
:glob:
|
||||
|
||||
introduction
|
||||
overview
|
||||
installation
|
||||
usage
|
||||
configuration
|
||||
tipstricks
|
||||
fontpatching
|
||||
license-credits
|
||||
|
||||
Segments
|
||||
========
|
||||
|
||||
.. toctree::
|
||||
segments/common
|
||||
segments/shell
|
||||
segments/vim
|
||||
troubleshooting
|
||||
tips-and-tricks
|
||||
license-and-credits
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
93
docs/source/installation.rst
Normal file
93
docs/source/installation.rst
Normal file
@ -0,0 +1,93 @@
|
||||
************
|
||||
Installation
|
||||
************
|
||||
|
||||
Generic requirements
|
||||
====================
|
||||
|
||||
* Python 2.6 or later, 3.2 or later, PyPy 2.0 or later. It is the only
|
||||
non-optional requirement.
|
||||
* C compiler. Required to build powerline client on linux. If it is not present
|
||||
then powerline will fall back to shell script or python client.
|
||||
* ``socat`` program. Required for shell variant of client which runs a bit
|
||||
faster than python version of the client, but still slower than C version.
|
||||
* ``psutil`` python package. Required for some segments like cpu_percent. Some
|
||||
segments have linux-only fallbacks for ``psutil`` functionality.
|
||||
* ``mercurial`` python package (note: *not* standalone executable). Required to
|
||||
work with mercurial repositories.
|
||||
* ``pygit2`` python package or ``git`` executable. Required to work with ``git``
|
||||
repositories.
|
||||
* ``bzr`` python package (note: *not* standalone executable). Required to work
|
||||
with bazaar repositories.
|
||||
* ``i3-py``, `available on github <https://github.com/ziberna/i3-py>`_. Required
|
||||
for i3wm bindings and segments.
|
||||
|
||||
.. note::
|
||||
Until mercurial and bazaar support Python-3 or PyPy powerline will not
|
||||
support repository information when running in these interpreters.
|
||||
|
||||
Pip installation
|
||||
================
|
||||
|
||||
This project is currently unavailable from PyPI due to a naming conflict with an
|
||||
unrelated project, thus you will have to use the following command to install
|
||||
powerline with ``pip``::
|
||||
|
||||
pip install --user git+git://github.com/Lokaltog/powerline
|
||||
|
||||
. You may also choose to clone powerline repository somewhere and use::
|
||||
|
||||
pip install -e --user {path_to_powerline}
|
||||
|
||||
, but note that in this case ``pip`` will not install ``powerline`` executable
|
||||
and you will have to do something like::
|
||||
|
||||
ln -s {path_to_powerline}/scripts/powerline ~/.local/bin
|
||||
|
||||
(:file:`~/.local/bin` should be replaced with some path present in ``$PATH``).
|
||||
|
||||
.. note::
|
||||
If your ISP blocks git protocol for some reason github also provides ``ssh``
|
||||
(``git+ssh://git@github.com/Lokaltog/powerline``) and ``https``
|
||||
(``git+https://github.com/Lokaltog/powerline``) protocols. ``git`` protocol
|
||||
should be the fastest, but least secure one though.
|
||||
|
||||
Fonts installation
|
||||
==================
|
||||
|
||||
Powerline uses several special glyphs to get the arrow effect and some custom
|
||||
symbols for developers. This requires that you either have a symbol font or
|
||||
a patched font on your system. Your terminal emulator must also support either
|
||||
patched fonts or fontconfig for Powerline to work properly.
|
||||
|
||||
You can also enable :ref:`24-bit color support <config-common-term_truecolor>`
|
||||
if your terminal emulator supports it (see :ref:`the terminal emulator support
|
||||
matrix <usage-terminal-emulators>`).
|
||||
|
||||
There are basically two ways to get powerline glyphs displayed: use
|
||||
:file:`PowerlineSymbols.otf` font as a fallback for one of the existing fonts or
|
||||
install a patched font.
|
||||
|
||||
.. _installation-patched-fonts:
|
||||
|
||||
Patched fonts
|
||||
-------------
|
||||
|
||||
This method is the fallback method and works for every terminal, with the
|
||||
exception of :ref:`rxvt-unicode <tips-and-tricks-urxvt>`.
|
||||
|
||||
Download the font of your choice from `powerline-fonts`_. If you can't find
|
||||
your preferred font in the `powerline-fonts`_ repo, you'll have to patch your
|
||||
own font instead.
|
||||
|
||||
.. _powerline-fonts: https://github.com/Lokaltog/powerline-fonts
|
||||
|
||||
After downloading this font refer to platform-specific instructions.
|
||||
|
||||
Installation on various platforms
|
||||
=================================
|
||||
|
||||
.. toctree::
|
||||
|
||||
Linux <installation/linux>
|
||||
OS X <installation/osx>
|
@ -1,15 +1,10 @@
|
||||
:tocdepth: 2
|
||||
|
||||
.. _installation-linux:
|
||||
|
||||
*********************
|
||||
Installation on Linux
|
||||
*********************
|
||||
|
||||
The following distribution-specific packages are officially supported, and
|
||||
they provide an easy way of installing and upgrading Powerline. The packages
|
||||
will automatically do most of the configuration for you, but you should
|
||||
still skim through this guide so you know how the plugin works.
|
||||
The following distribution-specific packages are officially supported, and they
|
||||
provide an easy way of installing and upgrading Powerline. The packages will
|
||||
automatically do most of the configuration for you.
|
||||
|
||||
* `Arch Linux (AUR), Python 2 version <https://aur.archlinux.org/packages/python2-powerline-git/>`_
|
||||
* `Arch Linux (AUR), Python 3 version <https://aur.archlinux.org/packages/python-powerline-git/>`_
|
||||
@ -18,10 +13,8 @@ still skim through this guide so you know how the plugin works.
|
||||
If you're running a distribution without an official package you'll have to
|
||||
follow the installation guide below:
|
||||
|
||||
Plugin installation
|
||||
===================
|
||||
|
||||
1. Install Python 3.2+ or Python 2.6+.
|
||||
1. Install Python 3.2+ or Python 2.6+ with ``pip``. This step is
|
||||
distribution-specific, so no commands provided.
|
||||
2. Install Powerline using the following command::
|
||||
|
||||
pip install --user git+git://github.com/Lokaltog/powerline
|
||||
@ -35,72 +28,68 @@ Plugin installation
|
||||
install powerline this way you will be missing ``powerline`` executable and
|
||||
need to symlink it. It will be located in ``scripts/powerline``.
|
||||
|
||||
Font installation
|
||||
=================
|
||||
|
||||
Powerline provides two ways of installing the required fonts on Linux. The
|
||||
recommended method is using ``fontconfig`` if your terminal emulator
|
||||
supports it. See the :ref:`term-feature-support-matrix` for details about
|
||||
what features your terminal emulator supports.
|
||||
Fonts installation
|
||||
==================
|
||||
|
||||
Fontconfig
|
||||
----------
|
||||
|
||||
1. Download the `latest version of PowerlineSymbols
|
||||
<https://github.com/Lokaltog/powerline/raw/develop/font/PowerlineSymbols.otf>`_
|
||||
and the `latest version of the fontconfig file
|
||||
<https://github.com/Lokaltog/powerline/raw/develop/font/10-powerline-symbols.conf>`_.
|
||||
2. Move :file:`PowerlineSymbols.otf` to :file:`~/.fonts/` (or another X font
|
||||
directory).
|
||||
3. Run ``fc-cache -vf ~/.fonts`` to update your font cache.
|
||||
4. Move :file:`10-powerline-symbols.conf` to either :file:`~/.fonts.conf.d/`
|
||||
or :file:`~/.config/fontconfig/conf.d/`, depending on your fontconfig
|
||||
version.
|
||||
5. If you don't see the arrow symbols, please close all instances of your
|
||||
terminal emulator or gvim. You may also have to restart X for the changes
|
||||
to take effect. If you *still* don't see the arrow symbols, please submit
|
||||
an issue on GitHub.
|
||||
This method only works on Linux. It's the recommended method if your
|
||||
terminal emulator supports it as you don't have to patch any fonts, and it
|
||||
generally works well with any coding font.
|
||||
|
||||
Patched font
|
||||
------------
|
||||
#. Download the latest version of the symbol font and fontconfig file::
|
||||
|
||||
1. Download the font of your choice from `powerline-fonts`_. If you can't
|
||||
find your preferred font in the `powerline-fonts`_ repo, you'll have to
|
||||
patch your own font instead. See :ref:`font-patching` for instructions.
|
||||
2. Move your patched font to :file:`~/.fonts/` (or another X font
|
||||
directory).
|
||||
3. Run ``fc-cache -vf ~/.fonts`` to update your font cache.
|
||||
4. Update Gvim or your terminal emulator to use the patched font. (the
|
||||
correct font usually ends with *for Powerline*).
|
||||
5. If you don't see the arrow symbols, please close all instances of your
|
||||
terminal emulator or gvim. You may also have to restart X for the changes
|
||||
to take effect. If you *still* don't see the arrow symbols, please submit
|
||||
an issue on GitHub.
|
||||
wget https://github.com/Lokaltog/powerline/raw/develop/font/PowerlineSymbols.otf
|
||||
wget https://github.com/Lokaltog/powerline/raw/develop/font/10-powerline-symbols.conf
|
||||
|
||||
.. _powerline-fonts: https://github.com/Lokaltog/powerline-fonts
|
||||
#. Move the symbol font to a valid X font path. Valid font paths can be
|
||||
listed with ``xset q``::
|
||||
|
||||
Troubleshooting
|
||||
===============
|
||||
mv PowerlineSymbols.otf ~/.fonts/
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
#. Update font cache for the path you moved the font to (you may need to be
|
||||
root to update the cache for system-wide paths)::
|
||||
|
||||
I can't see any fancy symbols, what's wrong?
|
||||
--------------------------------------------
|
||||
fc-cache -vf ~/.fonts/
|
||||
|
||||
* Make sure that you've configured gvim or your terminal emulator to use
|
||||
a patched font (see :ref:`font-patching`).
|
||||
* You need to set your ``LANG`` and ``LC_*`` environment variables to
|
||||
a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro's
|
||||
documentation for information about setting these variables correctly.
|
||||
* Make sure that vim is compiled with the ``--with-features=big`` flag.
|
||||
* If you're using rxvt-unicode, make sure that it's compiled with the
|
||||
``--enable-unicode3`` flag.
|
||||
#. Install the fontconfig file. For newer versions of fontconfig the config
|
||||
path is ``~/.config/fontconfig/conf.d/``, for older versions it's
|
||||
``~/.fonts.conf.d/``::
|
||||
|
||||
The fancy symbols look a bit blurry or "off"!
|
||||
---------------------------------------------
|
||||
mv 10-powerline-symbols.conf ~/.config/fontconfig/conf.d/
|
||||
|
||||
* Make sure that you have patched all variants of your font (i.e. both the
|
||||
regular and the bold font files).
|
||||
If you can't see the custom symbols, please close all instances of your
|
||||
terminal emulator. You may need to restart X for the changes to take
|
||||
effect.
|
||||
|
||||
.. include:: troubleshooting-common.rst
|
||||
If you *still* can't see the custom symbols, double-check that you have
|
||||
installed the font to a valid X font path, and that you have installed the
|
||||
fontconfig file to a valid fontconfig path. Alternatively try to install
|
||||
a :ref:`patched font <installation-patched-fonts>`.
|
||||
|
||||
Patched font installation
|
||||
-------------------------
|
||||
|
||||
After downloading font you should do the following:
|
||||
|
||||
#. Move the patched font to a valid X font path. Valid font paths can be
|
||||
listed with ``xset q``::
|
||||
|
||||
mv 'MyFont for Powerline.otf' ~/.fonts/
|
||||
|
||||
#. Update font cache for the path you moved the font to (you may need to be
|
||||
root to update the cache for system-wide paths)::
|
||||
|
||||
fc-cache -vf ~/.fonts/
|
||||
|
||||
After installing the patched font you need to update Gvim or your terminal
|
||||
emulator to use the patched font. The correct font usually ends with *for
|
||||
Powerline*.
|
||||
|
||||
If you can't see the custom symbols, please close all instances of your
|
||||
terminal emulator. You may need to restart X for the changes to take
|
||||
effect.
|
||||
|
||||
If you *still* can't see the custom symbols, double-check that you have
|
||||
installed the font to a valid X font path.
|
||||
|
@ -1,16 +1,9 @@
|
||||
:tocdepth: 2
|
||||
|
||||
.. _installation-osx:
|
||||
|
||||
********************
|
||||
Installation on OS X
|
||||
********************
|
||||
|
||||
Plugin installation
|
||||
===================
|
||||
|
||||
Python package
|
||||
--------------
|
||||
==============
|
||||
|
||||
1. Install a proper Python version (see `issue #39
|
||||
<https://github.com/Lokaltog/powerline/issues/39>`_ for a discussion
|
||||
@ -18,108 +11,42 @@ Python package
|
||||
|
||||
sudo port select python python27-apple
|
||||
|
||||
. You may use homebrew for this::
|
||||
|
||||
brew install python
|
||||
|
||||
.
|
||||
|
||||
2. Install Powerline using the following command::
|
||||
|
||||
pip install --user git+git://github.com/Lokaltog/powerline
|
||||
|
||||
.. warning:: When using ``brew install`` to install Python one must not supply
|
||||
``--user`` flag to ``pip``.
|
||||
|
||||
.. note:: You need to use the GitHub URI when installing Powerline! This
|
||||
project is currently unavailable on the PyPI due to a naming conflict
|
||||
with an unrelated project.
|
||||
|
||||
.. note:: If you are powerline developer you should be aware that ``pip install
|
||||
--editable`` does not currently fully work. If you
|
||||
install powerline this way you will be missing ``powerline`` executable and
|
||||
need to symlink it. It will be located in ``scripts/powerline``.
|
||||
--editable`` does not currently fully work. If you install powerline this way
|
||||
you will be missing ``powerline`` executable and need to symlink it. It will
|
||||
be located in ``scripts/powerline``.
|
||||
|
||||
Vim installation
|
||||
----------------
|
||||
================
|
||||
|
||||
Any terminal vim version with Python 3.2+ or Python 2.6+ support should work,
|
||||
but if you're using MacVim you need to install it using the following command::
|
||||
|
||||
brew install macvim --env-std --override-system-vim
|
||||
|
||||
Font installation
|
||||
=================
|
||||
Fonts installation
|
||||
==================
|
||||
|
||||
You need a patched font for Powerline to work on OS X. Check out the
|
||||
`powerline-fonts`_ repository on GitHub for patched versions of some popular
|
||||
programming fonts.
|
||||
Install downloaded patched font by double-clicking the font file in Finder, then
|
||||
clicking :guilabel:`Install this font` in the preview window.
|
||||
|
||||
1. Download the font of your choice and install it by double-clicking the
|
||||
font file in Finder and then click :guilabel:`Install this font` in the
|
||||
preview window.
|
||||
|
||||
If you can't find your preferred font in the `powerline-fonts`_ repo,
|
||||
you'll have to patch your own font instead. See :ref:`font-patching` for
|
||||
instructions.
|
||||
2. Configure MacVim or your terminal emulator to use the patched font (the
|
||||
correct font usually ends with *for Powerline*).
|
||||
|
||||
.. _powerline-fonts: https://github.com/Lokaltog/powerline-fonts
|
||||
|
||||
Troubleshooting
|
||||
===============
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
I can't see any fancy symbols, what's wrong?
|
||||
--------------------------------------------
|
||||
|
||||
* If you're using iTerm2, please update to `this revision
|
||||
<https://github.com/gnachman/iTerm2/commit/8e3ad6dabf83c60b8cf4a3e3327c596401744af6>`_
|
||||
or newer.
|
||||
* You need to set your ``LANG`` and ``LC_*`` environment variables to
|
||||
a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro's
|
||||
documentation for information about setting these variables correctly.
|
||||
|
||||
The colors look weird in the default OS X Terminal app!
|
||||
-------------------------------------------------------
|
||||
|
||||
* The arrows may have the wrong colors if you have changed the "minimum
|
||||
contrast" slider in the color tab of your OS X settings.
|
||||
* The default OS X Terminal app is known to have some issues with the
|
||||
Powerline colors. Please use another terminal emulator. iTerm2 should work
|
||||
fine.
|
||||
|
||||
The colors look weird in iTerm2!
|
||||
--------------------------------
|
||||
|
||||
* The arrows may have the wrong colors if you have changed the "minimum
|
||||
contrast" slider in the color tab of your OS X settings.
|
||||
* Please disable background transparency to resolve this issue.
|
||||
|
||||
Statusline is getting wrapped to the next line in iTerm2
|
||||
--------------------------------------------------------
|
||||
|
||||
* Turn off “Treat ambigious-width characters as double width” in `Preferences
|
||||
--> Text`.
|
||||
* Alternative: remove fancy dividers (they suck in this case), set
|
||||
:ref:`ambiwidth <config-common-ambiwidth>` to 2.
|
||||
|
||||
I receive a ``NameError`` when trying to use Powerline with MacVim!
|
||||
-------------------------------------------------------------------
|
||||
|
||||
* Please install MacVim using this command::
|
||||
|
||||
brew install macvim --env-std --override-system-vim
|
||||
|
||||
Then install Powerline locally with ``pip install --user``, or by
|
||||
running these commands in the ``powerline`` directory::
|
||||
|
||||
./setup.py build
|
||||
./setup.py install --user
|
||||
|
||||
I receive an ``ImportError`` when trying to use Powerline on OS X!
|
||||
------------------------------------------------------------------
|
||||
|
||||
* This is caused by an invalid ``sys.path`` when using system vim and system
|
||||
Python. Please try to select another Python distribution::
|
||||
|
||||
sudo port select python python27-apple
|
||||
|
||||
* See `issue #39 <https://github.com/Lokaltog/powerline/issues/39>`_ for
|
||||
a discussion and other possible solutions for this issue.
|
||||
|
||||
.. include:: troubleshooting-common.rst
|
||||
After installing the patched font you need to update MacVim or your terminal
|
||||
emulator to use the patched font. The correct font usually ends with *for
|
||||
Powerline*.
|
||||
|
@ -1,65 +0,0 @@
|
||||
************
|
||||
Introduction
|
||||
************
|
||||
|
||||
This is the next version of Powerline, implemented in Python. It aims to
|
||||
resolve some of the "unresolvable" problems of the vimscript implementation,
|
||||
as well as providing a common code base for all projects that use Powerline
|
||||
in some way (e.g. shell prompts and tmux themes).
|
||||
|
||||
The project is currently in beta, and most of the functionality in the old
|
||||
vimscript project is already implemented.
|
||||
|
||||
Screenshots
|
||||
===========
|
||||
|
||||
**Mode-dependent highlighting**
|
||||
|
||||
* .. image:: _static/img/pl-mode-normal.png
|
||||
:alt: Normal mode
|
||||
* .. image:: _static/img/pl-mode-insert.png
|
||||
:alt: Insert mode
|
||||
* .. image:: _static/img/pl-mode-visual.png
|
||||
:alt: Visual mode
|
||||
* .. image:: _static/img/pl-mode-replace.png
|
||||
:alt: Replace mode
|
||||
|
||||
**Automatic truncation of segments in small windows**
|
||||
|
||||
* .. image:: _static/img/pl-truncate1.png
|
||||
:alt: Truncation illustration
|
||||
* .. image:: _static/img/pl-truncate2.png
|
||||
:alt: Truncation illustration
|
||||
* .. image:: _static/img/pl-truncate3.png
|
||||
:alt: Truncation illustration
|
||||
|
||||
The font in the screenshots is `Pragmata Pro`_ by Fabrizio Schiavi.
|
||||
|
||||
.. _`Pragmata Pro`: http://www.fsd.it/fonts/pragmatapro.htm
|
||||
|
||||
Feature highlights
|
||||
==================
|
||||
|
||||
* **Better performance.** Python performs quite a bit better than vimscript,
|
||||
and by having most of the code in Python instead of vimscript it's also
|
||||
much easier to profile the code and eliminate bottlenecks.
|
||||
* **A much leaner code base.** With most of the functionality of the old
|
||||
project implemented the new version consists of less than half the amount
|
||||
of code.
|
||||
* **Automatic removal of less important segments in small windows.** Not all
|
||||
information is equally important to have in the statusline, and segments
|
||||
with e.g. encoding and file format information are automatically removed
|
||||
in smaller windows.
|
||||
* **Dynamic statusline evaluation in Python.** Statuslines are dynamically
|
||||
rendered in Python instead of relying on vim's statusline flags, which
|
||||
allows much more flexibility when creating statuslines.
|
||||
* **The possibility of adding more segments.** Because of vim's hardcoded
|
||||
limitation of 80 statusline options, the vimscript implementation
|
||||
triggered an error when adding more segments to the default theme. Since
|
||||
segment contents are now rendered as plain text in Python it's possible to
|
||||
add many more segments in the statusline before reaching this limit.
|
||||
* **New and improved theme and colorscheme syntax.** Themes and colorschemes
|
||||
are now written in JSON, with a much cleaner syntax that's easier to learn
|
||||
and work with. Themes and colorschemes are also much more configurable,
|
||||
and it's easy to write your own and store them in your home config
|
||||
directory.
|
@ -2,28 +2,22 @@
|
||||
License and credits
|
||||
*******************
|
||||
|
||||
License
|
||||
=======
|
||||
|
||||
Powerline is licensed under the `MIT license
|
||||
Powerline is licensed under the `MIT license
|
||||
<https://raw.github.com/Lokaltog/powerline/develop/LICENSE>`_.
|
||||
|
||||
Credits
|
||||
=======
|
||||
|
||||
Authors
|
||||
-------
|
||||
|
||||
* `Kim Silkebækken <https://github.com/Lokaltog>`_
|
||||
* `ZyX-I <https://github.com/ZyX-I>`_
|
||||
* `Nikolay Pavlov <https://github.com/ZyX-I>`_
|
||||
* `Kovid Goyal <https://github.com/kovidgoyal>`_
|
||||
|
||||
Contributors
|
||||
------------
|
||||
|
||||
* `List of contributors
|
||||
* `List of contributors
|
||||
<https://github.com/Lokaltog/powerline/contributors>`_
|
||||
* The glyphs in the font patcher are created by Fabrizio Schiavi, creator of
|
||||
* The glyphs in the font patcher are created by Fabrizio Schiavi, creator of
|
||||
the excellent coding font `Pragmata Pro`_.
|
||||
|
||||
.. _`Pragmata Pro`: http://www.fsd.it/fonts/pragmatapro.htm
|
@ -2,332 +2,66 @@
|
||||
Overview
|
||||
********
|
||||
|
||||
Requirements
|
||||
============
|
||||
**Powerline is a statusline plugin for vim, and provides statuslines and
|
||||
prompts for several other applications, including zsh, bash, tmux, IPython,
|
||||
Awesome and Qtile.**
|
||||
|
||||
Powerline requires Python 3.3 or Python 2.7 to work.
|
||||
Features
|
||||
--------
|
||||
|
||||
Vim plugin requirements
|
||||
-----------------------
|
||||
* **Extensible and feature rich, written in Python.** Powerline was
|
||||
completely rewritten in Python to get rid of as much vimscript as
|
||||
possible. This has allowed much better extensibility, leaner and better
|
||||
config files, and a structured, object-oriented codebase with no mandatory
|
||||
third-party dependencies other than a Python interpreter.
|
||||
* **Stable and testable code base.** Using Python has allowed unit testing
|
||||
of all the project code. The code is tested to work in Python 2.6+ and
|
||||
Python 3.
|
||||
* **Support for prompts and statuslines in many applications.** Originally
|
||||
created exclusively for vim statuslines, the project has evolved to
|
||||
provide statuslines in tmux and several WMs, and prompts for shells like
|
||||
bash/zsh and other applications. It's simple to write renderers for any
|
||||
other applications that Powerline doesn't yet support.
|
||||
* **Configuration and colorschemes written in JSON.** JSON is
|
||||
a standardized, simple and easy to use file format that allows for easy
|
||||
user configuration across all of Powerline's supported applications.
|
||||
* **Fast and lightweight, with daemon support for even better performance.**
|
||||
Although the code base spans a couple of thousand lines of code with no
|
||||
goal of "less than X lines of code", the main focus is on good performance
|
||||
and as little code as possible while still providing a rich set of
|
||||
features. The new daemon also ensures that only one Python instance is
|
||||
launched for prompts and statuslines, which provides excellent
|
||||
performance.
|
||||
|
||||
The vim plugin requires a vim version with Python support compiled in. You
|
||||
can check if your vim supports Python by running ``vim --version | grep
|
||||
+python``.
|
||||
*But I hate Python / I don't need shell prompts / this is just too much
|
||||
hassle for me / what happened to the original vim-powerline project / …*
|
||||
|
||||
If your vim version doesn't have support for Python, you'll have to compile
|
||||
it with the ``--enable-pythoninterp`` flag (``--enable-python3interp`` if
|
||||
you want Python 3 support instead). Note that this also requires the related
|
||||
Python headers to be installed on your system. Please consult your
|
||||
distribution's documentation for details on how to compile and install
|
||||
packages.
|
||||
You should check out some of the Powerline derivatives. The most lightweight
|
||||
and feature-rich alternative is currently Bailey Ling's `vim-airline
|
||||
<https://github.com/bling/vim-airline>`_ project.
|
||||
|
||||
Vim version 7.3.661 or newer is recommended for performance reasons.
|
||||
|
||||
Terminal emulator requirements
|
||||
------------------------------
|
||||
|
||||
Powerline uses several special glyphs to get the arrow effect and some
|
||||
custom symbols for developers. This requires that you either have a symbol
|
||||
font or a patched font on your system. Your terminal emulator must also
|
||||
support either patched fonts or fontconfig for Powerline to work properly.
|
||||
|
||||
You can also enable :ref:`24-bit color support <config-common-term_truecolor>`
|
||||
if your terminal emulator supports it.
|
||||
|
||||
.. table:: Application/terminal emulator feature support matrix
|
||||
:name: term-feature-support-matrix
|
||||
|
||||
===================== ======= ===================== ===================== =====================
|
||||
Name OS Patched font support Fontconfig support 24-bit color support
|
||||
===================== ======= ===================== ===================== =====================
|
||||
Gnome Terminal Linux |i_yes| |i_yes| |i_no|
|
||||
Gvim Linux |i_yes| |i_no| |i_yes|
|
||||
iTerm2 OS X |i_yes| |i_no| |i_no|
|
||||
Konsole Linux |i_yes| |i_yes| |i_yes|
|
||||
lxterminal Linux |i_yes| |i_yes| |i_no|
|
||||
MacVim OS X |i_yes| |i_no| |i_yes|
|
||||
rxvt-unicode Linux |i_partial| [#]_ |i_no| |i_no|
|
||||
st Linux |i_yes| |i_yes| |i_no|
|
||||
Terminal.app OS X |i_yes| |i_no| |i_no|
|
||||
Xfce Terminal Linux |i_yes| |i_yes| |i_no|
|
||||
xterm Linux |i_yes| |i_no| |i_partial| [#]_
|
||||
===================== ======= ===================== ===================== =====================
|
||||
|
||||
.. |i_yes| image:: _static/img/icons/tick.png
|
||||
.. |i_no| image:: _static/img/icons/cross.png
|
||||
.. |i_partial| image:: _static/img/icons/error.png
|
||||
|
||||
.. [#] Must be compiled with ``--enable-unicode3`` for the
|
||||
patched font to work.
|
||||
.. [#] Uses nearest color from 8-bit palette.
|
||||
|
||||
Optional dependencies
|
||||
---------------------
|
||||
|
||||
The following software is not required by all segments, but recommended for
|
||||
optimal performance and extra features:
|
||||
|
||||
Python packages
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
* ``pygit2``
|
||||
* ``mercurial``
|
||||
* ``psutil``
|
||||
* ``i3-py``, `available on github <https://github.com/ziberna/i3-py>`_. Only used with i3wm bindings and segments.
|
||||
|
||||
Other applications
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* ``git`` version 1.7.2 and later. Not needed if you have ``pygit2``.
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
.. note:: This project is currently unavailable from PyPI due to a naming conflict
|
||||
with an unrelated project. Please read the detailed instructions for your platform
|
||||
below.
|
||||
|
||||
* :ref:`installation-linux`
|
||||
* :ref:`installation-osx`
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
.. _vim-vimrc:
|
||||
Screenshots
|
||||
-----------
|
||||
|
||||
Vim statusline
|
||||
--------------
|
||||
|
||||
If installed using pip just add
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
python from powerline.vim import setup as powerline_setup
|
||||
python powerline_setup()
|
||||
python del powerline_setup
|
||||
|
||||
(replace ``python`` with ``python3`` if appropriate) to your :file:`vimrc`.
|
||||
|
||||
If you just cloned the repository add the following line to your :file:`vimrc`,
|
||||
where ``{repository_root}`` is the absolute path to your Powerline installation
|
||||
directory:
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
set rtp+={repository_root}/powerline/bindings/vim
|
||||
|
||||
If you're using Vundle or Pathogen and don't want Powerline functionality in
|
||||
any other applications, simply add Powerline as a bundle and point the path
|
||||
above to the Powerline bundle directory, e.g.
|
||||
``~/.vim/bundle/powerline/powerline/bindings/vim``. For vim-addon-manager it is
|
||||
even easier since you don’t need to write this big path or install anything by
|
||||
hand: ``powerline`` is installed and run just like any other plugin using
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
call vam#ActivateAddons(['powerline'])
|
||||
|
||||
.. note::
|
||||
If you use supplied :file:`powerline.vim` file to load powerline there are
|
||||
additional configuration variables available: ``g:powerline_pycmd`` and
|
||||
``g:powerline_pyeval``. First sets command used to load powerline: expected
|
||||
values are ``"py"`` and ``"py3"``. Second sets function used in statusline,
|
||||
expected values are ``"pyeval"`` and ``"py3eval"``.
|
||||
|
||||
If ``g:powerline_pycmd`` is set to the one of the expected values then
|
||||
``g:powerline_pyeval`` will be set accordingly. If it is set to some other
|
||||
value then you must also set ``g:powerline_pyeval``. Powerline will not
|
||||
check that Vim is compiled with Python support if you set
|
||||
``g:powerline_pycmd`` to an unexpected value.
|
||||
|
||||
These values are to be used to specify the only Python that is to be loaded
|
||||
if you have both versions: Vim may disable loading one python version if
|
||||
other was already loaded. They should also be used if you have two python
|
||||
versions able to load simultaneously, but with powerline installed only for
|
||||
python-3 version.
|
||||
|
||||
Shell prompts
|
||||
-------------
|
||||
|
||||
.. note::
|
||||
It is advised that you run ``powerline-daemon`` before using any of the
|
||||
below solutions. To do this add
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
powerline-daemon -q
|
||||
|
||||
just before sourcing powerline bindings script or running
|
||||
``powerline-setup``. Use ``|| true`` or equivalent if you run your
|
||||
configuration with ``set -e`` because ``powerline-daemon`` will exit with
|
||||
``1`` if daemon is already running.
|
||||
|
||||
Bash prompt
|
||||
^^^^^^^^^^^
|
||||
|
||||
Add the following line to your :file:`bashrc`, where ``{repository_root}`` is
|
||||
the absolute path to your Powerline installation directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
. {repository_root}/powerline/bindings/bash/powerline.sh
|
||||
|
||||
Zsh prompt
|
||||
^^^^^^^^^^
|
||||
|
||||
Add the following line to your :file:`zshrc`, where ``{repository_root}`` is the
|
||||
absolute path to your Powerline installation directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
. {repository_root}/powerline/bindings/zsh/powerline.zsh
|
||||
|
||||
Fish prompt
|
||||
^^^^^^^^^^^
|
||||
|
||||
Add the following line to your :file:`config.fish`, where ``{repository_root}``
|
||||
is the absolute path to your Powerline installation directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
set fish_function_path $fish_function_path "{repository_root}/powerline/bindings/fish"
|
||||
powerline-setup
|
||||
|
||||
.. _tmux-statusline:
|
||||
|
||||
Busybox (ash), mksh and dash prompt
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
After launching busybox run the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
. {repository_root}/powerline/bindings/shell/powerline.sh
|
||||
|
||||
Mksh users may put this line into ``~/.mkshrc`` file. Dash users may use the
|
||||
following in ``~/.profile``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
if test "x$0" != "x${0#dash}" ; then
|
||||
export ENV={repository_root}/powerline/bindings/shell/powerline.sh
|
||||
fi
|
||||
|
||||
.. note::
|
||||
Dash users that already have ``$ENV`` defined should either put the ``.
|
||||
…/shell/powerline.sh`` line in the ``$ENV`` file or create a new file which
|
||||
will source (using ``.`` command) both former ``$ENV`` file and
|
||||
:file:`powerline.sh` files and set ``$ENV`` to the path of this new file.
|
||||
|
||||
.. warning::
|
||||
Job count is using some weird hack that uses signals and temporary files for
|
||||
interprocess communication. It may be wrong sometimes. Not the case in mksh.
|
||||
|
||||
.. warning::
|
||||
Busybox has two shells: ``ash`` and ``hush``. Second is known to segfault in
|
||||
busybox 1.22.1 when using :file:`powerline.sh` script.
|
||||
|
||||
Tmux statusline
|
||||
---------------
|
||||
|
||||
Add the following lines to your :file:`.tmux.conf`, where ``{repository_root}``
|
||||
is the absolute path to your Powerline installation directory::
|
||||
|
||||
source "{repository_root}/powerline/bindings/tmux/powerline.conf"
|
||||
|
||||
.. note::
|
||||
The availability of the ``powerline-config`` command is required for
|
||||
powerline support. You may specify location of this script via
|
||||
``$POWERLINE_CONFIG_COMMAND`` environment variable.
|
||||
|
||||
.. note::
|
||||
It is advised that you run ``powerline-daemon`` before adding the above line
|
||||
to tmux.conf. To do so add::
|
||||
|
||||
run-shell "powerline-daemon -q"
|
||||
|
||||
to :file:`.tmux.conf`.
|
||||
|
||||
IPython prompt
|
||||
--------------
|
||||
|
||||
For IPython<0.11 add the following lines to your
|
||||
:file:`.ipython/ipy_user_conf.py`::
|
||||
|
||||
# top
|
||||
from powerline.bindings.ipython.pre_0_11 import setup as powerline_setup
|
||||
|
||||
# main() function (assuming you launched ipython without configuration to
|
||||
# create skeleton ipy_user_conf.py file):
|
||||
powerline_setup()
|
||||
|
||||
For IPython>=0.11 add the following line to your :file:`ipython_config.py`
|
||||
file in the profile you are using::
|
||||
|
||||
c.InteractiveShellApp.extensions = [
|
||||
'powerline.bindings.ipython.post_0_11'
|
||||
]
|
||||
|
||||
IPython=0.11* is not supported and does not work. IPython<0.10 was not
|
||||
tested (not installable by pip).
|
||||
|
||||
Awesome widget
|
||||
--------------
|
||||
|
||||
.. note:: Powerline currently only supports awesome 3.5.
|
||||
|
||||
.. note:: The Powerline widget will spawn a shell script that runs in the
|
||||
background and updates the statusline with ``awesome-client``.
|
||||
|
||||
Add the following to your :file:`rc.lua`, where ``{repository_root}`` is the
|
||||
absolute path to your Powerline installation directory:
|
||||
|
||||
.. code-block:: lua
|
||||
|
||||
package.path = package.path .. ';{repository_root}/powerline/bindings/awesome/?.lua'
|
||||
require('powerline')
|
||||
|
||||
Then add the ``powerline_widget`` to your ``wibox``:
|
||||
|
||||
.. code-block:: lua
|
||||
|
||||
right_layout:add(powerline_widget)
|
||||
|
||||
Qtile widget
|
||||
------------
|
||||
|
||||
Add the following to your :file:`~/.config/qtile/config.py`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from powerline.bindings.qtile.widget import Powerline
|
||||
|
||||
screens = [
|
||||
Screen(
|
||||
top=bar.Bar([
|
||||
# ...
|
||||
Powerline(timeout=2),
|
||||
# ...
|
||||
],
|
||||
),
|
||||
),
|
||||
]
|
||||
|
||||
I3 bar
|
||||
------
|
||||
|
||||
.. note:: Until the patch is done in i3, you will need a custom ``i3bar`` build
|
||||
called ``i3bgbar``. The source is available `here
|
||||
<https://github.com/S0lll0s/i3bgbar>`_.
|
||||
|
||||
Add the following to your :file:`~/.i3/config`::
|
||||
|
||||
bar {
|
||||
i3bar_command i3bgbar
|
||||
|
||||
status_command python /path/to/powerline/bindings/i3/powerline-i3.py
|
||||
font pango:PowerlineFont 12
|
||||
}
|
||||
|
||||
where ``i3bgbar`` may be replaced with the path to the custom i3bar binary and
|
||||
``PowerlineFont`` is any system font with powerline support.
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
**Mode-dependent highlighting**
|
||||
|
||||
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-normal.png
|
||||
:alt: Normal mode
|
||||
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-insert.png
|
||||
:alt: Insert mode
|
||||
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-visual.png
|
||||
:alt: Visual mode
|
||||
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-replace.png
|
||||
:alt: Replace mode
|
||||
|
||||
**Automatic truncation of segments in small windows**
|
||||
|
||||
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate1.png
|
||||
:alt: Truncation illustration
|
||||
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate2.png
|
||||
:alt: Truncation illustration
|
||||
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate3.png
|
||||
:alt: Truncation illustration
|
||||
|
50
docs/source/tips-and-tricks.rst
Normal file
50
docs/source/tips-and-tricks.rst
Normal file
@ -0,0 +1,50 @@
|
||||
***************
|
||||
Tips and tricks
|
||||
***************
|
||||
|
||||
Vim
|
||||
===
|
||||
|
||||
Useful settings
|
||||
---------------
|
||||
|
||||
You may find the following vim settings useful when using the Powerline
|
||||
statusline:
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
set laststatus=2 " Always display the statusline in all windows
|
||||
set noshowmode " Hide the default mode text (e.g. -- INSERT -- below the statusline)
|
||||
|
||||
.. _tips-and-tricks-urxvt:
|
||||
|
||||
Rxvt-unicode
|
||||
============
|
||||
|
||||
Terminus font and urxvt
|
||||
-----------------------
|
||||
|
||||
The Terminus fonts does not have the powerline glyphs and unless someone submits
|
||||
a patch to the font author, it is unlikely to happen. However, Andre Klärner
|
||||
came up with this work around: In your ``~/.Xdefault`` file add the following::
|
||||
|
||||
urxvt*font: xft:Terminus:pixelsize=12,xft:Inconsolata\ for\ Powerline:pixelsize=12
|
||||
|
||||
This will allow urxvt to fallback onto the Inconsolata fonts in case it does not
|
||||
find the right glyphs within the terminus font.
|
||||
|
||||
Source Code Pro font and urxvt
|
||||
------------------------------
|
||||
|
||||
Much like the terminus font that was mentioned above, a similar fix can be
|
||||
applied to the Source Code Pro fonts.
|
||||
|
||||
In the ``~/.Xdefaults`` add the following::
|
||||
|
||||
URxvt*font: xft:Source\ Code\ Pro\ Medium:pixelsize=13:antialias=true:hinting=true,xft:Source\ Code\ Pro\ Medium:pixelsize=13:antialias=true:hinting=true
|
||||
|
||||
I noticed that Source Code Pro has the glyphs there already, but the pixel size
|
||||
of the fonts play a role in whether or not the > or the < separators showing up
|
||||
or not. Using font size 12, glyphs on the right hand side of the powerline are
|
||||
present, but the ones on the left don't. Pixel size 14, brings the reverse
|
||||
problem. Font size 13 seems to work just fine.
|
@ -1,49 +0,0 @@
|
||||
*************
|
||||
Tips & Tricks
|
||||
*************
|
||||
|
||||
Vim
|
||||
===
|
||||
|
||||
Fix terminal timeout when pressing escape
|
||||
-----------------------------------------
|
||||
|
||||
When you're pressing :kbd:`Escape` to leave insert mode in the terminal, it
|
||||
will by default take a second or another keystroke to leave insert mode
|
||||
completely and update the statusline. If you find this annoying, you can add
|
||||
the following snippet to your :file:`vimrc` to escape insert mode
|
||||
immediately:
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
if ! has('gui_running')
|
||||
set ttimeoutlen=10
|
||||
augroup FastEscape
|
||||
autocmd!
|
||||
au InsertEnter * set timeoutlen=0
|
||||
au InsertLeave * set timeoutlen=1000
|
||||
augroup END
|
||||
endif
|
||||
|
||||
Useful settings
|
||||
---------------
|
||||
|
||||
You may find the following vim settings useful when using the Powerline
|
||||
statusline:
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
set laststatus=2 " Always display the statusline in all windows
|
||||
set noshowmode " Hide the default mode text (e.g. -- INSERT -- below the statusline)
|
||||
|
||||
Terminus font and urxvt
|
||||
=======================
|
||||
|
||||
The Terminus fonts does not have the powerline glyths and unless someone submits a patch to
|
||||
the font author, it is unlikely to happen. However, Andre Klärner came up with this work around:
|
||||
In your ``~/.Xdefault`` file add the following:
|
||||
|
||||
``urxvt*font: xft:Terminus:pixelsize=12,xft:Inconsolata\ for\ Powerline:pixelsize=12``
|
||||
|
||||
This will allow urxvt to fallback onto the Inconsolata fonts in case it does not find the right
|
||||
glyths within the terminus font.
|
@ -1,3 +1,18 @@
|
||||
***************
|
||||
Troubleshooting
|
||||
***************
|
||||
|
||||
System-specific issues
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
|
||||
Linux <troubleshooting/linux>
|
||||
OS X <troubleshooting/osx>
|
||||
|
||||
Common issues
|
||||
=============
|
||||
|
||||
I'm using tmux and Powerline looks like crap, what's wrong?
|
||||
-----------------------------------------------------------
|
||||
|
||||
@ -5,10 +20,11 @@ I'm using tmux and Powerline looks like crap, what's wrong?
|
||||
:file:`.tmux.conf` to solve this issue::
|
||||
|
||||
set -g default-terminal "screen-256color"
|
||||
|
||||
* If you're using iTerm2, make sure that you have enabled the setting
|
||||
:guilabel:`Set locale variables automatically` in :menuselection:`Profiles
|
||||
--> Terminal --> Environment`.
|
||||
:guilabel:`Set locale variables automatically` in :menuselection:`Profiles -->
|
||||
Terminal --> Environment`.
|
||||
* Make sure tmux knows that terminal it is running in support 256 colors. You
|
||||
may tell it tmux by using ``-2`` option when launching it.
|
||||
|
||||
I’m using tmux/screen and Powerline is colorless
|
||||
------------------------------------------------
|
||||
@ -38,7 +54,7 @@ diagnose this problem you may do the following:
|
||||
|
||||
#) If this problem is observed within the shell make sure that
|
||||
|
||||
.. code-block:: shell
|
||||
.. code-block:: sh
|
||||
|
||||
python -c 'import powerline; print (powerline.__file__)'
|
||||
|
||||
@ -75,7 +91,7 @@ diagnose this problem you may do the following:
|
||||
There is a hint if you want to place powerline repository somewhere, but still
|
||||
make powerline package importable anywhere: use
|
||||
|
||||
.. code-block:: shell
|
||||
.. code-block:: sh
|
||||
|
||||
pip install --user --editable path/to/powerline
|
||||
|
||||
@ -133,4 +149,57 @@ Prompt is spoiled after completing files in ksh
|
||||
|
||||
This is exactly why powerline has official mksh support, but not official ksh
|
||||
support. If you know the solution feel free to share it in `powerline bug
|
||||
tracker <https://github.com/Lokaltog/powerline/issues/new>`_.
|
||||
tracker`_.
|
||||
|
||||
Powerline loses color after editing vimrc
|
||||
-----------------------------------------
|
||||
|
||||
If your vimrc has something like
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
autocmd! BufWritePost vimrc :source ~/.vimrc
|
||||
|
||||
to automatically source vimrc after saving it you must then add ``nested`` after
|
||||
pattern (``vimrc`` in this case):
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
autocmd! BufWritePost vimrc nested :source ~/.vimrc
|
||||
|
||||
. Alternatively move ``:colorscheme`` command out of the vimrc to the file which
|
||||
will not be automatically resourced. Observed problem is that when you use
|
||||
``:colorscheme`` command existing highlighting groups are usually cleared,
|
||||
including those defined by powerline. To workaround this issue powerline hooks
|
||||
``Colorscheme`` event, but when you source vimrc with ``BufWritePost`` event,
|
||||
but without ``nested`` this event is not launched. See also `autocmd-nested
|
||||
<http://vimpluginloader.sourceforge.net/doc/autocmd.txt.html#autocmd-nested>`_
|
||||
Vim documentation.
|
||||
|
||||
Powerline loses color after saving any file
|
||||
-------------------------------------------
|
||||
|
||||
It may be one of the incarnations of the above issue: specifically minibufexpl
|
||||
is known to trigger it. If you are using minibufexplorer you should set
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
let g:miniBufExplForceSyntaxEnable = 1
|
||||
|
||||
variable so that this issue is not triggered. Complete explanation:
|
||||
|
||||
#. When MBE autocommand is executed it launches ``:syntax enable`` Vim command…
|
||||
#. … which makes Vim source :file:`syntax/syntax.vim` file …
|
||||
#. … which in turn sources :file:`syntax/synload.vim` …
|
||||
#. … which executes ``:colorscheme`` command. Normally this command triggers
|
||||
``Colorscheme`` event, but in the first point minibufexplorer did set up
|
||||
autocommands that miss ``nested`` attribute meaning that no events will be
|
||||
triggered when processing MBE events.
|
||||
|
||||
.. note::
|
||||
This setting was introduced in version 6.3.1 of `minibufexpl
|
||||
<http://www.vim.org/scripts/script.php?script_id=159>`_ and removed in
|
||||
version 6.5.0 of its successor `minibufexplorer
|
||||
<http://www.vim.org/scripts/script.php?script_id=3239>`_. It is highly
|
||||
advised to use the latter because `minibufexpl`_ was last updated late in
|
||||
2004.
|
21
docs/source/troubleshooting/linux.rst
Normal file
21
docs/source/troubleshooting/linux.rst
Normal file
@ -0,0 +1,21 @@
|
||||
************************
|
||||
Troubleshooting on Linux
|
||||
************************
|
||||
|
||||
I can't see any fancy symbols, what's wrong?
|
||||
--------------------------------------------
|
||||
|
||||
* Make sure that you've configured gvim or your terminal emulator to use
|
||||
a patched font.
|
||||
* You need to set your ``LANG`` and ``LC_*`` environment variables to
|
||||
a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro's
|
||||
documentation for information about setting these variables correctly.
|
||||
* Make sure that vim is compiled with the ``--with-features=big`` flag.
|
||||
* If you're using rxvt-unicode, make sure that it's compiled with the
|
||||
``--enable-unicode3`` flag.
|
||||
|
||||
The fancy symbols look a bit blurry or "off"!
|
||||
---------------------------------------------
|
||||
|
||||
* Make sure that you have patched all variants of your font (i.e. both the
|
||||
regular and the bold font files).
|
61
docs/source/troubleshooting/osx.rst
Normal file
61
docs/source/troubleshooting/osx.rst
Normal file
@ -0,0 +1,61 @@
|
||||
***********************
|
||||
Troubleshooting on OS X
|
||||
***********************
|
||||
|
||||
I can't see any fancy symbols, what's wrong?
|
||||
--------------------------------------------
|
||||
|
||||
* If you're using iTerm2, please update to `this revision
|
||||
<https://github.com/gnachman/iTerm2/commit/8e3ad6dabf83c60b8cf4a3e3327c596401744af6>`_
|
||||
or newer.
|
||||
* You need to set your ``LANG`` and ``LC_*`` environment variables to
|
||||
a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro's
|
||||
documentation for information about setting these variables correctly.
|
||||
|
||||
The colors look weird in the default OS X Terminal app!
|
||||
-------------------------------------------------------
|
||||
|
||||
* The arrows may have the wrong colors if you have changed the "minimum
|
||||
contrast" slider in the color tab of your OS X settings.
|
||||
* The default OS X Terminal app is known to have some issues with the
|
||||
Powerline colors. Please use another terminal emulator. iTerm2 should work
|
||||
fine.
|
||||
|
||||
The colors look weird in iTerm2!
|
||||
--------------------------------
|
||||
|
||||
* The arrows may have the wrong colors if you have changed the "minimum
|
||||
contrast" slider in the color tab of your OS X settings.
|
||||
* Please disable background transparency to resolve this issue.
|
||||
|
||||
Statusline is getting wrapped to the next line in iTerm2
|
||||
--------------------------------------------------------
|
||||
|
||||
* Turn off “Treat ambigious-width characters as double width” in `Preferences
|
||||
--> Text`.
|
||||
* Alternative: remove fancy dividers (they suck in this case), set
|
||||
:ref:`ambiwidth <config-common-ambiwidth>` to 2.
|
||||
|
||||
I receive a ``NameError`` when trying to use Powerline with MacVim!
|
||||
-------------------------------------------------------------------
|
||||
|
||||
* Please install MacVim using this command::
|
||||
|
||||
brew install macvim --env-std --override-system-vim
|
||||
|
||||
Then install Powerline locally with ``pip install --user``, or by
|
||||
running these commands in the ``powerline`` directory::
|
||||
|
||||
./setup.py build
|
||||
./setup.py install --user
|
||||
|
||||
I receive an ``ImportError`` when trying to use Powerline on OS X!
|
||||
------------------------------------------------------------------
|
||||
|
||||
* This is caused by an invalid ``sys.path`` when using system vim and system
|
||||
Python. Please try to select another Python distribution::
|
||||
|
||||
sudo port select python python27-apple
|
||||
|
||||
* See `issue #39 <https://github.com/Lokaltog/powerline/issues/39>`_ for
|
||||
a discussion and other possible solutions for this issue.
|
72
docs/source/usage.rst
Normal file
72
docs/source/usage.rst
Normal file
@ -0,0 +1,72 @@
|
||||
*****
|
||||
Usage
|
||||
*****
|
||||
|
||||
Application-specific requirements
|
||||
---------------------------------
|
||||
|
||||
Vim plugin requirements
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The vim plugin requires a vim version with Python support compiled in. You
|
||||
can check if your vim supports Python by running ``vim --version | grep
|
||||
+python``.
|
||||
|
||||
If your vim version doesn't have support for Python, you'll have to compile
|
||||
it with the ``--enable-pythoninterp`` flag (``--enable-python3interp`` if
|
||||
you want Python 3 support instead). Note that this also requires the related
|
||||
Python headers to be installed on your system. Please consult your
|
||||
distribution's documentation for details on how to compile and install
|
||||
packages.
|
||||
|
||||
Vim version 7.3.661 or newer is recommended for performance reasons.
|
||||
|
||||
.. _usage-terminal-emulators:
|
||||
|
||||
Terminal emulator requirements
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Powerline uses several special glyphs to get the arrow effect and some
|
||||
custom symbols for developers. This requires that you either have a symbol
|
||||
font or a patched font on your system. Your terminal emulator must also
|
||||
support either patched fonts or fontconfig for Powerline to work properly.
|
||||
|
||||
You can also enable :ref:`24-bit color support <config-common-term_truecolor>`
|
||||
if your terminal emulator supports it.
|
||||
|
||||
.. table:: Application/terminal emulator feature support matrix
|
||||
:name: term-feature-support-matrix
|
||||
|
||||
===================== ======= ===================== ===================== =====================
|
||||
Name OS Patched font support Fontconfig support 24-bit color support
|
||||
===================== ======= ===================== ===================== =====================
|
||||
Gvim Linux |i_yes| |i_no| |i_yes|
|
||||
iTerm2 OS X |i_yes| |i_no| |i_no|
|
||||
Konsole Linux |i_yes| |i_yes| |i_yes|
|
||||
lxterminal Linux |i_yes| |i_yes| |i_no|
|
||||
MacVim OS X |i_yes| |i_no| |i_yes|
|
||||
rxvt-unicode Linux |i_partial| [#]_ |i_no| |i_no|
|
||||
st Linux |i_yes| |i_yes| |i_yes| [#]_
|
||||
Terminal.app OS X |i_yes| |i_no| |i_no|
|
||||
libvte-based [#]_ Linux |i_yes| |i_yes| |i_yes| [#]_
|
||||
xterm Linux |i_yes| |i_no| |i_partial| [#]_
|
||||
===================== ======= ===================== ===================== =====================
|
||||
|
||||
.. |i_yes| image:: _static/img/icons/tick.png
|
||||
.. |i_no| image:: _static/img/icons/cross.png
|
||||
.. |i_partial| image:: _static/img/icons/error.png
|
||||
|
||||
.. [#] Must be compiled with ``--enable-unicode3`` for the patched font to work.
|
||||
.. [#] Since version 0.5.
|
||||
.. [#] Including XFCE terminal and GNOME terminal.
|
||||
.. [#] Since version 0.36.
|
||||
.. [#] Uses nearest color from 8-bit palette.
|
||||
|
||||
Plugins
|
||||
-------
|
||||
|
||||
.. toctree::
|
||||
|
||||
usage/shell-prompts
|
||||
usage/wm-widgets
|
||||
usage/other
|
121
docs/source/usage/other.rst
Normal file
121
docs/source/usage/other.rst
Normal file
@ -0,0 +1,121 @@
|
||||
*************
|
||||
Other plugins
|
||||
*************
|
||||
|
||||
.. _vim-vimrc:
|
||||
|
||||
Vim statusline
|
||||
==============
|
||||
|
||||
If installed using pip just add
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
python from powerline.vim import setup as powerline_setup
|
||||
python powerline_setup()
|
||||
python del powerline_setup
|
||||
|
||||
(replace ``python`` with ``python3`` if appropriate) to your :file:`vimrc`.
|
||||
|
||||
If you just cloned the repository add the following line to your :file:`vimrc`,
|
||||
where ``{repository_root}`` is the absolute path to your Powerline installation
|
||||
directory:
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
set rtp+={repository_root}/powerline/bindings/vim
|
||||
|
||||
If you're using pathogen and don't want Powerline functionality in any other
|
||||
applications, simply add Powerline as a bundle and point the path above to the
|
||||
Powerline bundle directory, e.g.
|
||||
``~/.vim/bundle/powerline/powerline/bindings/vim``.
|
||||
|
||||
With Vundle you may instead use
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
Bundle 'Lokaltog/powerline', {'rtp': 'powerline/bindings/vim/'}
|
||||
|
||||
(replace ``Bundle`` with ``NeoBundle`` for NeoBundle).
|
||||
|
||||
For vim-addon-manager it is even easier since you don’t need to write this big
|
||||
path or install anything by hand: ``powerline`` is installed and run just like
|
||||
any other plugin using
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
call vam#ActivateAddons(['powerline'])
|
||||
|
||||
.. warning::
|
||||
*Never* install powerline with pathogen/VAM/Vundle/NeoBundle *and* with pip.
|
||||
If you want powerline functionality in vim and other applications use
|
||||
system-wide installation if your system has powerline package, pip-only or
|
||||
``pip install --editable`` kind of installation performed on the repository
|
||||
installed by Vim plugin manager.
|
||||
|
||||
If you have installed powerline with pip and with some of Vim package
|
||||
managers do never report any errors to powerline bug tracker, especially
|
||||
errors occurring after updates.
|
||||
|
||||
.. note::
|
||||
If you use supplied :file:`powerline.vim` file to load powerline there are
|
||||
additional configuration variables available: ``g:powerline_pycmd`` and
|
||||
``g:powerline_pyeval``. First sets command used to load powerline: expected
|
||||
values are ``"py"`` and ``"py3"``. Second sets function used in statusline,
|
||||
expected values are ``"pyeval"`` and ``"py3eval"``.
|
||||
|
||||
If ``g:powerline_pycmd`` is set to the one of the expected values then
|
||||
``g:powerline_pyeval`` will be set accordingly. If it is set to some other
|
||||
value then you must also set ``g:powerline_pyeval``. Powerline will not
|
||||
check that Vim is compiled with Python support if you set
|
||||
``g:powerline_pycmd`` to an unexpected value.
|
||||
|
||||
These values are to be used to specify the only Python that is to be loaded
|
||||
if you have both versions: Vim may disable loading one python version if
|
||||
other was already loaded. They should also be used if you have two python
|
||||
versions able to load simultaneously, but with powerline installed only for
|
||||
python-3 version.
|
||||
|
||||
Tmux statusline
|
||||
===============
|
||||
|
||||
Add the following lines to your :file:`.tmux.conf`, where ``{repository_root}``
|
||||
is the absolute path to your Powerline installation directory::
|
||||
|
||||
source "{repository_root}/powerline/bindings/tmux/powerline.conf"
|
||||
|
||||
.. note::
|
||||
The availability of the ``powerline-config`` command is required for
|
||||
powerline support. You may specify location of this script via
|
||||
``$POWERLINE_CONFIG_COMMAND`` environment variable.
|
||||
|
||||
.. note::
|
||||
It is advised that you run ``powerline-daemon`` before adding the above line
|
||||
to tmux.conf. To do so add::
|
||||
|
||||
run-shell "powerline-daemon -q"
|
||||
|
||||
to :file:`.tmux.conf`.
|
||||
|
||||
IPython prompt
|
||||
==============
|
||||
|
||||
For IPython<0.11 add the following lines to your
|
||||
:file:`.ipython/ipy_user_conf.py`::
|
||||
|
||||
# top
|
||||
from powerline.bindings.ipython.pre_0_11 import setup as powerline_setup
|
||||
|
||||
# main() function (assuming you launched ipython without configuration to
|
||||
# create skeleton ipy_user_conf.py file):
|
||||
powerline_setup()
|
||||
|
||||
For IPython>=0.11 add the following line to your :file:`ipython_config.py`
|
||||
file in the profile you are using::
|
||||
|
||||
c.InteractiveShellApp.extensions = [
|
||||
'powerline.bindings.ipython.post_0_11'
|
||||
]
|
||||
|
||||
IPython=0.11* is not supported and does not work. IPython<0.10 was not
|
||||
tested (not installable by pip).
|
68
docs/source/usage/shell-prompts.rst
Normal file
68
docs/source/usage/shell-prompts.rst
Normal file
@ -0,0 +1,68 @@
|
||||
*************
|
||||
Shell prompts
|
||||
*************
|
||||
|
||||
Bash prompt
|
||||
===========
|
||||
|
||||
Add the following line to your :file:`bashrc`, where ``{repository_root}`` is
|
||||
the absolute path to your Powerline installation directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
. {repository_root}/powerline/bindings/bash/powerline.sh
|
||||
|
||||
Zsh prompt
|
||||
==========
|
||||
|
||||
Add the following line to your :file:`zshrc`, where ``{repository_root}`` is the
|
||||
absolute path to your Powerline installation directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
. {repository_root}/powerline/bindings/zsh/powerline.zsh
|
||||
|
||||
Fish prompt
|
||||
===========
|
||||
|
||||
Add the following line to your :file:`config.fish`, where ``{repository_root}``
|
||||
is the absolute path to your Powerline installation directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
set fish_function_path $fish_function_path "{repository_root}/powerline/bindings/fish"
|
||||
powerline-setup
|
||||
|
||||
.. _tmux-statusline:
|
||||
|
||||
Busybox (ash), mksh and dash prompt
|
||||
=====================================
|
||||
|
||||
After launching busybox run the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
. {repository_root}/powerline/bindings/shell/powerline.sh
|
||||
|
||||
Mksh users may put this line into ``~/.mkshrc`` file. Dash users may use the
|
||||
following in ``~/.profile``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
if test "x$0" != "x${0#dash}" ; then
|
||||
export ENV={repository_root}/powerline/bindings/shell/powerline.sh
|
||||
fi
|
||||
|
||||
.. note::
|
||||
Dash users that already have ``$ENV`` defined should either put the ``.
|
||||
…/shell/powerline.sh`` line in the ``$ENV`` file or create a new file which
|
||||
will source (using ``.`` command) both former ``$ENV`` file and
|
||||
:file:`powerline.sh` files and set ``$ENV`` to the path of this new file.
|
||||
|
||||
.. warning::
|
||||
Job count is using some weird hack that uses signals and temporary files for
|
||||
interprocess communication. It may be wrong sometimes. Not the case in mksh.
|
||||
|
||||
.. warning::
|
||||
Busybox has two shells: ``ash`` and ``hush``. Second is known to segfault in
|
||||
busybox 1.22.1 when using :file:`powerline.sh` script.
|
64
docs/source/usage/wm-widgets.rst
Normal file
64
docs/source/usage/wm-widgets.rst
Normal file
@ -0,0 +1,64 @@
|
||||
**********************
|
||||
Window manager widgets
|
||||
**********************
|
||||
|
||||
Awesome widget
|
||||
==============
|
||||
|
||||
.. note:: Powerline currently only supports awesome 3.5.
|
||||
|
||||
.. note:: The Powerline widget will spawn a shell script that runs in the
|
||||
background and updates the statusline with ``awesome-client``.
|
||||
|
||||
Add the following to your :file:`rc.lua`, where ``{repository_root}`` is the
|
||||
absolute path to your Powerline installation directory:
|
||||
|
||||
.. code-block:: lua
|
||||
|
||||
package.path = package.path .. ';{repository_root}/powerline/bindings/awesome/?.lua'
|
||||
require('powerline')
|
||||
|
||||
Then add the ``powerline_widget`` to your ``wibox``:
|
||||
|
||||
.. code-block:: lua
|
||||
|
||||
right_layout:add(powerline_widget)
|
||||
|
||||
Qtile widget
|
||||
============
|
||||
|
||||
Add the following to your :file:`~/.config/qtile/config.py`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from powerline.bindings.qtile.widget import Powerline
|
||||
|
||||
screens = [
|
||||
Screen(
|
||||
top=bar.Bar([
|
||||
# ...
|
||||
Powerline(timeout=2),
|
||||
# ...
|
||||
],
|
||||
),
|
||||
),
|
||||
]
|
||||
|
||||
I3 bar
|
||||
======
|
||||
|
||||
.. note:: Until the patch is done in i3, you will need a custom ``i3bar`` build
|
||||
called ``i3bgbar``. The source is available `here
|
||||
<https://github.com/S0lll0s/i3bgbar>`_.
|
||||
|
||||
Add the following to your :file:`~/.i3/config`::
|
||||
|
||||
bar {
|
||||
i3bar_command i3bgbar
|
||||
|
||||
status_command python /path/to/powerline/bindings/i3/powerline-i3.py
|
||||
font pango:PowerlineFont 12
|
||||
}
|
||||
|
||||
where ``i3bgbar`` may be replaced with the path to the custom i3bar binary and
|
||||
``PowerlineFont`` is any system font with powerline support.
|
Loading…
x
Reference in New Issue
Block a user