tyler.durden/powerline
1
0
Fork 0
mirror of https://github.com/powerline/powerline.git synced 2025-07-25 23:05:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #945 from ZyX-I/update-docs

Browse Source 
Update documentation
This commit is contained in:
Nikolai Aleksandrovich Pavlov 2014-08-03 03:40:26 +04:00
commit da6667bd14
26 changed files with 1351 additions and 1304 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/source/conf.py
View File

@ -10,10 +10,20 @@ extensions = ['powerline_autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sp
source_suffix = '.rst' source_suffix = '.rst'
master_doc = 'index' master_doc = 'index'
project = u'Powerline' project = u'Powerline'
copyright = u'Kim Silkebækken'
version = 'beta' version = 'beta'
release = 'beta' release = 'beta'
exclude_patterns = ['_build'] exclude_patterns = ['_build']
pygments_style = 'sphinx' pygments_style = 'sphinx'
html_theme = 'default' html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static'] 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

556
docs/source/configuration.rst
View File

@ -1,6 +1,6 @@
************* *******************************
Configuration Configuration and customization
************* *******************************
.. note:: **You DO NOT have to fork the main GitHub repo to personalize your .. note:: **You DO NOT have to fork the main GitHub repo to personalize your
Powerline configuration!** Please read through the :ref:`quick-guide` for 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: Powerline provides default configurations in the following locations:
`Main configuration`_ :ref:`Main configuration <config-main>`
:file:`powerline/config.json` :file:`powerline/config.json`
`Colorschemes`_ :ref:`Colorschemes <config-colors>`
:file:`powerline/colorschemes/{name}.json`, :file:`powerline/colorschemes/{name}.json`,
:file:`powerline/colorscheme/__main__.json`, :file:`powerline/colorscheme/__main__.json`,
:file:`powerline/colorschemes/{extension}/{name}.json` :file:`powerline/colorschemes/{extension}/{name}.json`
`Themes`_ :ref:`Themes <config-themes>`
:file:`powerline/themes/{extension}/default.json` :file:`powerline/themes/{extension}/default.json`
The default configuration files are stored in the main package. User 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 Linux users, and in :file:`~/.config/powerline` for OS X users. This usually
corresponds to :file:`~/.config/powerline` on both platforms. 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-guide:
Quick setup 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` configuration/reference
configuration/segments
The main configuration file defines some common options that applies to all configuration/local
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.

154
docs/source/configuration/local.rst Normal file
View 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
View 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
View 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/*

0
docs/source/segments/common.rst → docs/source/configuration/segments/common.rst
View File

0
docs/source/segments/shell.rst → docs/source/configuration/segments/shell.rst
View File

0
docs/source/segments/vim.rst → docs/source/configuration/segments/vim.rst
View File

136
docs/source/fontpatching.rst
View File

@ -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!

19
docs/source/index.rst
View File

@ -3,23 +3,16 @@ Powerline
********* *********
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 3
:glob: :glob:
introduction
overview overview
installation
usage
configuration configuration
tipstricks troubleshooting
fontpatching tips-and-tricks
license-credits license-and-credits
Segments
========
.. toctree::
segments/common
segments/shell
segments/vim
Indices and tables Indices and tables
================== ==================

93
docs/source/installation.rst Normal file
View 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>

123
docs/source/installation/linux.rst
View File

@ -1,15 +1,10 @@
:tocdepth: 2
.. _installation-linux:
********************* *********************
Installation on Linux Installation on Linux
********************* *********************
The following distribution-specific packages are officially supported, and The following distribution-specific packages are officially supported, and they
they provide an easy way of installing and upgrading Powerline. The packages provide an easy way of installing and upgrading Powerline. The packages will
will automatically do most of the configuration for you, but you should automatically do most of the configuration for you.
still skim through this guide so you know how the plugin works.
* `Arch Linux (AUR), Python 2 version <https://aur.archlinux.org/packages/python2-powerline-git/>`_ * `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/>`_ * `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 If you're running a distribution without an official package you'll have to
follow the installation guide below: follow the installation guide below:
Plugin installation 1. Install Python 3.2+ or Python 2.6+ with ``pip``. This step is
=================== distribution-specific, so no commands provided.
1. Install Python 3.2+ or Python 2.6+.
2. Install Powerline using the following command:: 2. Install Powerline using the following command::
pip install --user git+git://github.com/Lokaltog/powerline 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 install powerline this way you will be missing ``powerline`` executable and
need to symlink it. It will be located in ``scripts/powerline``. need to symlink it. It will be located in ``scripts/powerline``.
Font installation Fonts 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.
Fontconfig Fontconfig
---------- ----------
1. Download the `latest version of PowerlineSymbols This method only works on Linux. It's the recommended method if your
<https://github.com/Lokaltog/powerline/raw/develop/font/PowerlineSymbols.otf>`_ terminal emulator supports it as you don't have to patch any fonts, and it
and the `latest version of the fontconfig file generally works well with any coding font.
<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.
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 wget https://github.com/Lokaltog/powerline/raw/develop/font/PowerlineSymbols.otf
find your preferred font in the `powerline-fonts`_ repo, you'll have to wget https://github.com/Lokaltog/powerline/raw/develop/font/10-powerline-symbols.conf
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.
.. _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:: #. Update font cache for the path you moved the font to (you may need to be
:local: 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 #. Install the fontconfig file. For newer versions of fontconfig the config
a patched font (see :ref:`font-patching`). path is ``~/.config/fontconfig/conf.d/``, for older versions it's
* You need to set your ``LANG`` and ``LC_*`` environment variables to ``~/.fonts.conf.d/``::
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"! mv 10-powerline-symbols.conf ~/.config/fontconfig/conf.d/
---------------------------------------------
* Make sure that you have patched all variants of your font (i.e. both the If you can't see the custom symbols, please close all instances of your
regular and the bold font files). 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.

115
docs/source/installation/osx.rst
View File

@ -1,16 +1,9 @@
:tocdepth: 2
.. _installation-osx:
******************** ********************
Installation on OS X Installation on OS X
******************** ********************
Plugin installation
===================
Python package Python package
-------------- ==============
1. Install a proper Python version (see `issue #39 1. Install a proper Python version (see `issue #39
<https://github.com/Lokaltog/powerline/issues/39>`_ for a discussion <https://github.com/Lokaltog/powerline/issues/39>`_ for a discussion
@ -18,108 +11,42 @@ Python package
sudo port select python python27-apple sudo port select python python27-apple
. You may use homebrew for this::
brew install python
.
2. Install Powerline using the following command:: 2. Install Powerline using the following command::
pip install --user git+git://github.com/Lokaltog/powerline 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 .. note:: You need to use the GitHub URI when installing Powerline! This
project is currently unavailable on the PyPI due to a naming conflict project is currently unavailable on the PyPI due to a naming conflict
with an unrelated project. with an unrelated project.
.. note:: If you are powerline developer you should be aware that ``pip install .. note:: If you are powerline developer you should be aware that ``pip install
--editable`` does not currently fully work. If you --editable`` does not currently fully work. If you install powerline this way
install powerline this way you will be missing ``powerline`` executable and you will be missing ``powerline`` executable and need to symlink it. It will
need to symlink it. It will be located in ``scripts/powerline``. be located in ``scripts/powerline``.
Vim installation Vim installation
---------------- ================
Any terminal vim version with Python 3.2+ or Python 2.6+ support should work, 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:: but if you're using MacVim you need to install it using the following command::
brew install macvim --env-std --override-system-vim 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 Install downloaded patched font by double-clicking the font file in Finder, then
`powerline-fonts`_ repository on GitHub for patched versions of some popular clicking :guilabel:`Install this font` in the preview window.
programming fonts.
1. Download the font of your choice and install it by double-clicking the After installing the patched font you need to update MacVim or your terminal
font file in Finder and then click :guilabel:`Install this font` in the emulator to use the patched font. The correct font usually ends with *for
preview window. Powerline*.
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

65
docs/source/introduction.rst
View File

@ -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.

14
docs/source/license-credits.rst → docs/source/license-and-credits.rst
View File

@ -2,28 +2,22 @@
License and credits 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>`_. <https://raw.github.com/Lokaltog/powerline/develop/LICENSE>`_.
Credits
=======
Authors Authors
------- -------
* `Kim Silkebækken <https://github.com/Lokaltog>`_ * `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>`_ * `Kovid Goyal <https://github.com/kovidgoyal>`_
Contributors Contributors
------------ ------------
* `List of contributors * `List of contributors
<https://github.com/Lokaltog/powerline/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`_. the excellent coding font `Pragmata Pro`_.
.. _`Pragmata Pro`: http://www.fsd.it/fonts/pragmatapro.htm .. _`Pragmata Pro`: http://www.fsd.it/fonts/pragmatapro.htm

378
docs/source/overview.rst
View File

@ -2,332 +2,66 @@
Overview 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 *But I hate Python / I don't need shell prompts / this is just too much
can check if your vim supports Python by running ``vim --version | grep hassle for me / what happened to the original vim-powerline project / …*
+python``.
If your vim version doesn't have support for Python, you'll have to compile You should check out some of the Powerline derivatives. The most lightweight
it with the ``--enable-pythoninterp`` flag (``--enable-python3interp`` if and feature-rich alternative is currently Bailey Ling's `vim-airline
you want Python 3 support instead). Note that this also requires the related <https://github.com/bling/vim-airline>`_ project.
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. Screenshots
-----------
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:
Vim statusline Vim statusline
-------------- ^^^^^^^^^^^^^^
If installed using pip just add **Mode-dependent highlighting**
.. code-block:: vim * .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-normal.png
:alt: Normal mode
python from powerline.vim import setup as powerline_setup * .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-insert.png
python powerline_setup() :alt: Insert mode
python del powerline_setup * .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-visual.png
:alt: Visual mode
(replace ``python`` with ``python3`` if appropriate) to your :file:`vimrc`. * .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-replace.png
:alt: Replace mode
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 **Automatic truncation of segments in small windows**
directory:
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate1.png
.. code-block:: vim :alt: Truncation illustration
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate2.png
set rtp+={repository_root}/powerline/bindings/vim :alt: Truncation illustration
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate3.png
If you're using Vundle or Pathogen and don't want Powerline functionality in :alt: Truncation illustration
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.

50
docs/source/tips-and-tricks.rst Normal file
View 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.

49
docs/source/tipstricks.rst
View File

@ -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.

81
docs/source/installation/troubleshooting-common.rst → docs/source/troubleshooting.rst
View File

@ -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? 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:: :file:`.tmux.conf` to solve this issue::
set -g default-terminal "screen-256color" set -g default-terminal "screen-256color"
* If you're using iTerm2, make sure that you have enabled the setting * If you're using iTerm2, make sure that you have enabled the setting
:guilabel:`Set locale variables automatically` in :menuselection:`Profiles :guilabel:`Set locale variables automatically` in :menuselection:`Profiles -->
--> Terminal --> Environment`. 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 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 #) If this problem is observed within the shell make sure that
.. code-block:: shell .. code-block:: sh
python -c 'import powerline; print (powerline.__file__)' 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 There is a hint if you want to place powerline repository somewhere, but still
make powerline package importable anywhere: use make powerline package importable anywhere: use
.. code-block:: shell .. code-block:: sh
pip install --user --editable path/to/powerline 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 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 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
View 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
View 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
View 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
View 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
View 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
View 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.

1
setup.py
View File

@ -92,6 +92,7 @@ setup(
extras_require={ extras_require={
'docs': [ 'docs': [
'Sphinx', 'Sphinx',
'sphinx_rtd_theme',
], ],
}, },
test_suite='tests' if not OLD_PYTHON else None, test_suite='tests' if not OLD_PYTHON else None,