Remove old docs and update documentation structure
Most of the files are empty and need to be copied or rewritten from the old docs. Font patching docs have been removed entirely and will be moved to the powerline-fontpatcher repo. Ref #769
This commit is contained in:
Kim Silkebækken
ZyX
parent
ecb3b690db
commit
c2379df50a
|
|
@ -0,0 +1,15 @@
|
||||||
|
*******************************
|
||||||
|
Configuration and customization
|
||||||
|
*******************************
|
||||||
|
|
||||||
|
Quick setup guide
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
References
|
||||||
|
----------
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:glob:
|
||||||
|
|
||||||
|
configuration-reference
|
||||||
|
segment-reference
|
||||||
|
|
@ -0,0 +1,3 @@
|
||||||
|
***********************
|
||||||
|
Configuration reference
|
||||||
|
***********************
|
||||||
|
|
@ -1,636 +0,0 @@
|
||||||
*************
|
|
||||||
Configuration
|
|
||||||
*************
|
|
||||||
|
|
||||||
.. note:: **You DO NOT have to fork the main GitHub repo to personalize your
|
|
||||||
Powerline configuration!** Please read through the :ref:`quick-guide` for
|
|
||||||
a quick introduction to user configuration.
|
|
||||||
|
|
||||||
Powerline is configured with one main configuration file, and with separate
|
|
||||||
configuration files for themes and colorschemes. All configuration files are
|
|
||||||
written in JSON, with the exception of segment definitions, which are
|
|
||||||
written in Python.
|
|
||||||
|
|
||||||
Powerline provides default configurations in the following locations:
|
|
||||||
|
|
||||||
`Main configuration`_
|
|
||||||
:file:`powerline/config.json`
|
|
||||||
`Colorschemes`_
|
|
||||||
:file:`powerline/colorschemes/{name}.json`,
|
|
||||||
:file:`powerline/colorscheme/__main__.json`,
|
|
||||||
:file:`powerline/colorschemes/{extension}/{name}.json`
|
|
||||||
`Themes`_
|
|
||||||
:file:`powerline/themes/{extension}/default.json`
|
|
||||||
|
|
||||||
The default configuration files are stored in the main package. User
|
|
||||||
configuration files are stored in :file:`$XDG_CONFIG_HOME/powerline` for
|
|
||||||
Linux users, and in :file:`~/.config/powerline` for OS X users. This usually
|
|
||||||
corresponds to :file:`~/.config/powerline` on both platforms.
|
|
||||||
|
|
||||||
.. _quick-guide:
|
|
||||||
|
|
||||||
Quick setup guide
|
|
||||||
=================
|
|
||||||
|
|
||||||
This guide will help you with the initial configuration of Powerline.
|
|
||||||
|
|
||||||
Start by copying the entire set of default configuration files to the
|
|
||||||
corresponding path in your user config directory:
|
|
||||||
|
|
||||||
.. code-block:: sh
|
|
||||||
|
|
||||||
mkdir ~/.config/powerline
|
|
||||||
cp -R /path/to/powerline/config_files/* ~/.config/powerline
|
|
||||||
|
|
||||||
Each extension (vim, tmux, etc.) has its own theme, and they are located in
|
|
||||||
:file:`{config directory}/themes/{extension}/default.json`.
|
|
||||||
|
|
||||||
If you want to move, remove or customize any of the provided segments, you
|
|
||||||
can do that by updating the segment dictionary in the theme you want to
|
|
||||||
customize. A segment dictionary looks like this:
|
|
||||||
|
|
||||||
.. code-block:: javascript
|
|
||||||
|
|
||||||
{
|
|
||||||
"name": "segment_name"
|
|
||||||
...
|
|
||||||
}
|
|
||||||
|
|
||||||
You can move the segment dictionaries around to change the segment
|
|
||||||
positions, or remove the entire dictionary to remove the segment from the
|
|
||||||
prompt or statusline.
|
|
||||||
|
|
||||||
.. note:: It's essential that the contents of all your configuration files
|
|
||||||
is valid JSON! It's strongly recommended that you run your configuration
|
|
||||||
files through ``jsonlint`` after changing them.
|
|
||||||
|
|
||||||
Some segments need a user configuration to work properly. Here's a couple of
|
|
||||||
segments that you may want to customize right away:
|
|
||||||
|
|
||||||
**E-mail alert segment**
|
|
||||||
You have to set your username and password (and possibly server/port)
|
|
||||||
for the e-mail alert segment. If you're using GMail it's recommended
|
|
||||||
that you `generate an application-specific password
|
|
||||||
<https://accounts.google.com/IssuedAuthSubTokens>`_ for this purpose.
|
|
||||||
|
|
||||||
Open a theme file, scroll down to the ``email_imap_alert`` segment and
|
|
||||||
set your ``username`` and ``password``. The server defaults to GMail's
|
|
||||||
IMAP server, but you can set the server/port by adding a ``server`` and
|
|
||||||
a ``port`` argument.
|
|
||||||
**Weather segment**
|
|
||||||
The weather segment will try to find your location using a GeoIP lookup,
|
|
||||||
so unless you're on a VPN you probably won't have to change the location
|
|
||||||
query.
|
|
||||||
|
|
||||||
If you want to change the location query or the temperature unit you'll
|
|
||||||
have to update the segment arguments. Open a theme file, scroll down to
|
|
||||||
the weather segment and update it to include unit/location query
|
|
||||||
arguments:
|
|
||||||
|
|
||||||
.. code-block:: javascript
|
|
||||||
|
|
||||||
{
|
|
||||||
"name": "weather",
|
|
||||||
"priority": 50,
|
|
||||||
"args": {
|
|
||||||
"unit": "F",
|
|
||||||
"location_query": "oslo, norway"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
|
|
||||||
.. _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-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.
|
|
||||||
|
|
@ -1,142 +0,0 @@
|
||||||
***********************************
|
|
||||||
Font installation and configuration
|
|
||||||
***********************************
|
|
||||||
|
|
||||||
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 Recommended installation method Patched font support Fontconfig support 24-bit color support
|
|
||||||
===================== ======= =================================== ===================== ===================== =====================
|
|
||||||
Gnome Terminal Linux `Fontconfig`_ |i_yes| |i_yes| |i_no|
|
|
||||||
Gvim Linux `Patched font`_ |i_yes| |i_no| |i_yes|
|
|
||||||
Konsole Linux `Fontconfig`_ |i_yes| |i_yes| |i_yes|
|
|
||||||
lxterminal Linux `Fontconfig`_ |i_yes| |i_yes| |i_no|
|
|
||||||
rxvt-unicode Linux `rxvt-unicode`_ or `Patched font`_ |i_partial| [#]_ |i_no| |i_no|
|
|
||||||
st Linux `Fontconfig`_ |i_yes| |i_yes| |i_no|
|
|
||||||
Xfce Terminal Linux `Fontconfig`_ |i_yes| |i_yes| |i_no|
|
|
||||||
xterm Linux `Patched font`_ |i_yes| |i_no| |i_partial| [#]_
|
|
||||||
iTerm2 OS X `Patched font`_ |i_yes| |i_no| |i_no|
|
|
||||||
MacVim OS X `Patched font`_ |i_yes| |i_no| |i_yes|
|
|
||||||
Terminal.app OS X `Patched font`_ |i_yes| |i_no| |i_no|
|
|
||||||
===================== ======= =================================== ===================== ===================== =====================
|
|
||||||
|
|
||||||
.. |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.
|
|
||||||
|
|
||||||
Fontconfig
|
|
||||||
==========
|
|
||||||
|
|
||||||
This method only works on Linux. It's the recommended method if your
|
|
||||||
terminal emulator supports it as you don't have to patch any fonts, and it
|
|
||||||
generally works well with any coding font.
|
|
||||||
|
|
||||||
#. Download the latest version of the symbol font and fontconfig file::
|
|
||||||
|
|
||||||
wget https://github.com/Lokaltog/powerline/raw/develop/font/PowerlineSymbols.otf
|
|
||||||
wget https://github.com/Lokaltog/powerline/raw/develop/font/10-powerline-symbols.conf
|
|
||||||
|
|
||||||
#. Move the symbol font to a valid X font path. Valid font paths can be
|
|
||||||
listed with ``xset q``::
|
|
||||||
|
|
||||||
mv PowerlineSymbols.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/
|
|
||||||
|
|
||||||
#. Install the fontconfig file. For newer versions of fontconfig the config
|
|
||||||
path is ``~/.config/fontconfig/conf.d/``, for older versions it's
|
|
||||||
``~/.fonts.conf.d/``::
|
|
||||||
|
|
||||||
mv 10-powerline-symbols.conf ~/.config/fontconfig/conf.d/
|
|
||||||
|
|
||||||
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, and that you have installed the
|
|
||||||
fontconfig file to a valid fontconfig path. Alternatively try to install
|
|
||||||
a `Patched font`_.
|
|
||||||
|
|
||||||
Patched font
|
|
||||||
============
|
|
||||||
|
|
||||||
This method is the fallback method and works for every terminal emulator and
|
|
||||||
OS, with the exception of `rxvt-unicode`_.
|
|
||||||
|
|
||||||
Download the font of your choice from `powerline-fonts`_. If you can't find
|
|
||||||
your preferred font in the `powerline-fonts`_ repo, you'll have to patch
|
|
||||||
your own font instead. See :ref:`font-patching` for instructions.
|
|
||||||
|
|
||||||
.. _powerline-fonts: https://github.com/Lokaltog/powerline-fonts
|
|
||||||
|
|
||||||
Installation on Linux
|
|
||||||
---------------------
|
|
||||||
|
|
||||||
#. 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.
|
|
||||||
|
|
||||||
Installation on OS X
|
|
||||||
--------------------
|
|
||||||
|
|
||||||
Install your patched font by double-clicking the font file in Finder, then
|
|
||||||
clicking :guilabel:`Install this font` in the preview window.
|
|
||||||
|
|
||||||
After installing the patched font you need to update MacVim or your terminal
|
|
||||||
emulator to use the patched font. The correct font usually ends with *for
|
|
||||||
Powerline*.
|
|
||||||
|
|
||||||
Special cases
|
|
||||||
=============
|
|
||||||
|
|
||||||
rxvt-unicode
|
|
||||||
------------
|
|
||||||
|
|
||||||
.. note:: Symbol font support generally doesn't work well in
|
|
||||||
rxvt-unicode. It's recommended that you either disable the symbols or
|
|
||||||
switch to a better terminal emulator if you want to use Powerline.
|
|
||||||
|
|
||||||
rxvt-unicode allows using a `Patched font`_ only if it's compiled with the
|
|
||||||
``--enable-unicode3`` flag.
|
|
||||||
|
|
||||||
For unsupported fonts (e.g. bitmap fonts like Terminus), you can't use
|
|
||||||
``PowerlineSymbols.otf`` as a fallback since rxvt-unicode has trouble
|
|
||||||
determining the font's metrics. A solution to this issue is to get
|
|
||||||
a `Patched font`_ and add this as a fallback font to your
|
|
||||||
``.Xresources``/``.Xdefaults``::
|
|
||||||
|
|
||||||
URxvt*font: xft:Terminus:pixelsize=12,xft:Inconsolata\ for\ Powerline:pixelsize=12
|
|
||||||
|
|
@ -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!
|
|
||||||
|
|
@ -6,20 +6,13 @@ Powerline
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
:glob:
|
:glob:
|
||||||
|
|
||||||
introduction
|
|
||||||
overview
|
overview
|
||||||
configuration
|
installation
|
||||||
tipstricks
|
usage
|
||||||
fontpatching
|
configuration-and-customization
|
||||||
license-credits
|
troubleshooting
|
||||||
|
tips-and-tricks
|
||||||
Segments
|
license-and-credits
|
||||||
========
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
segments/common
|
|
||||||
segments/shell
|
|
||||||
segments/vim
|
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
==================
|
==================
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,8 @@
|
||||||
|
************
|
||||||
|
Installation
|
||||||
|
************
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
|
||||||
|
Linux <installation/linux>
|
||||||
|
OS X <installation/osx>
|
||||||
|
|
@ -1,106 +1,9 @@
|
||||||
:tocdepth: 2
|
|
||||||
|
|
||||||
.. _installation-linux:
|
|
||||||
|
|
||||||
*********************
|
*********************
|
||||||
Installation on Linux
|
Installation on Linux
|
||||||
*********************
|
*********************
|
||||||
|
|
||||||
The following distribution-specific packages are officially supported, and
|
Requirements
|
||||||
they provide an easy way of installing and upgrading Powerline. The packages
|
|
||||||
will automatically do most of the configuration for you, but you should
|
|
||||||
still skim through this guide so you know how the plugin works.
|
|
||||||
|
|
||||||
* `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/>`_
|
|
||||||
* Gentoo Live ebuild in `raiagent <https://github.com/leycec/raiagent>`_ overlay
|
|
||||||
|
|
||||||
If you're running a distribution without an official package you'll have to
|
|
||||||
follow the installation guide below:
|
|
||||||
|
|
||||||
Plugin installation
|
|
||||||
===================
|
|
||||||
|
|
||||||
1. Install Python 3.2+ or Python 2.6+.
|
|
||||||
2. Install Powerline using the following command::
|
|
||||||
|
|
||||||
pip install --user git+git://github.com/Lokaltog/powerline
|
|
||||||
|
|
||||||
.. note:: You need to use the GitHub URI when installing Powerline! This
|
|
||||||
project is currently unavailable on the PyPI due to a naming conflict
|
|
||||||
with an unrelated project.
|
|
||||||
|
|
||||||
.. note:: If you are powerline developer you should be aware that ``pip install
|
|
||||||
--editable`` does not currently fully work. If you
|
|
||||||
install powerline this way you will be missing ``powerline`` executable and
|
|
||||||
need to symlink it. It will be located in ``scripts/powerline``.
|
|
||||||
|
|
||||||
Font installation
|
|
||||||
=================
|
|
||||||
|
|
||||||
Powerline provides two ways of installing the required fonts on Linux. The
|
|
||||||
recommended method is using ``fontconfig`` if your terminal emulator
|
|
||||||
supports it. See the :ref:`term-feature-support-matrix` for details about
|
|
||||||
what features your terminal emulator supports.
|
|
||||||
|
|
||||||
Fontconfig
|
|
||||||
----------
|
|
||||||
|
|
||||||
1. Download the `latest version of PowerlineSymbols
|
|
||||||
<https://github.com/Lokaltog/powerline/raw/develop/font/PowerlineSymbols.otf>`_
|
|
||||||
and the `latest version of the fontconfig file
|
|
||||||
<https://github.com/Lokaltog/powerline/raw/develop/font/10-powerline-symbols.conf>`_.
|
|
||||||
2. Move :file:`PowerlineSymbols.otf` to :file:`~/.fonts/` (or another X font
|
|
||||||
directory).
|
|
||||||
3. Run ``fc-cache -vf ~/.fonts`` to update your font cache.
|
|
||||||
4. Move :file:`10-powerline-symbols.conf` to either :file:`~/.fonts.conf.d/`
|
|
||||||
or :file:`~/.config/fontconfig/conf.d/`, depending on your fontconfig
|
|
||||||
version.
|
|
||||||
5. If you don't see the arrow symbols, please close all instances of your
|
|
||||||
terminal emulator or gvim. You may also have to restart X for the changes
|
|
||||||
to take effect. If you *still* don't see the arrow symbols, please submit
|
|
||||||
an issue on GitHub.
|
|
||||||
|
|
||||||
Patched font
|
|
||||||
------------
|
------------
|
||||||
|
|
||||||
1. Download the font of your choice from `powerline-fonts`_. If you can't
|
Installation
|
||||||
find your preferred font in the `powerline-fonts`_ repo, you'll have to
|
------------
|
||||||
patch your own font instead. See :ref:`font-patching` for instructions.
|
|
||||||
2. Move your patched font to :file:`~/.fonts/` (or another X font
|
|
||||||
directory).
|
|
||||||
3. Run ``fc-cache -vf ~/.fonts`` to update your font cache.
|
|
||||||
4. Update Gvim or your terminal emulator to use the patched font. (the
|
|
||||||
correct font usually ends with *for Powerline*).
|
|
||||||
5. If you don't see the arrow symbols, please close all instances of your
|
|
||||||
terminal emulator or gvim. You may also have to restart X for the changes
|
|
||||||
to take effect. If you *still* don't see the arrow symbols, please submit
|
|
||||||
an issue on GitHub.
|
|
||||||
|
|
||||||
.. _powerline-fonts: https://github.com/Lokaltog/powerline-fonts
|
|
||||||
|
|
||||||
Troubleshooting
|
|
||||||
===============
|
|
||||||
|
|
||||||
.. contents::
|
|
||||||
:local:
|
|
||||||
|
|
||||||
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 (see :ref:`font-patching`).
|
|
||||||
* You need to set your ``LANG`` and ``LC_*`` environment variables to
|
|
||||||
a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro's
|
|
||||||
documentation for information about setting these variables correctly.
|
|
||||||
* Make sure that vim is compiled with the ``--with-features=big`` flag.
|
|
||||||
* If you're using rxvt-unicode, make sure that it's compiled with the
|
|
||||||
``--enable-unicode3`` flag.
|
|
||||||
|
|
||||||
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).
|
|
||||||
|
|
||||||
.. include:: troubleshooting-common.rst
|
|
||||||
|
|
|
||||||
|
|
@ -1,125 +1,9 @@
|
||||||
:tocdepth: 2
|
|
||||||
|
|
||||||
.. _installation-osx:
|
|
||||||
|
|
||||||
********************
|
********************
|
||||||
Installation on OS X
|
Installation on OS X
|
||||||
********************
|
********************
|
||||||
|
|
||||||
Plugin installation
|
Requirements
|
||||||
===================
|
------------
|
||||||
|
|
||||||
Python package
|
Installation
|
||||||
--------------
|
------------
|
||||||
|
|
||||||
1. Install a proper Python version (see `issue #39
|
|
||||||
<https://github.com/Lokaltog/powerline/issues/39>`_ for a discussion
|
|
||||||
regarding the required Python version on OS X)::
|
|
||||||
|
|
||||||
sudo port select python python27-apple
|
|
||||||
|
|
||||||
2. Install Powerline using the following command::
|
|
||||||
|
|
||||||
pip install --user git+git://github.com/Lokaltog/powerline
|
|
||||||
|
|
||||||
.. note:: You need to use the GitHub URI when installing Powerline! This
|
|
||||||
project is currently unavailable on the PyPI due to a naming conflict
|
|
||||||
with an unrelated project.
|
|
||||||
|
|
||||||
.. note:: If you are powerline developer you should be aware that ``pip install
|
|
||||||
--editable`` does not currently fully work. If you
|
|
||||||
install powerline this way you will be missing ``powerline`` executable and
|
|
||||||
need to symlink it. It will be located in ``scripts/powerline``.
|
|
||||||
|
|
||||||
Vim installation
|
|
||||||
----------------
|
|
||||||
|
|
||||||
Any terminal vim version with Python 3.2+ or Python 2.6+ support should work,
|
|
||||||
but if you're using MacVim you need to install it using the following command::
|
|
||||||
|
|
||||||
brew install macvim --env-std --override-system-vim
|
|
||||||
|
|
||||||
Font installation
|
|
||||||
=================
|
|
||||||
|
|
||||||
You need a patched font for Powerline to work on OS X. Check out the
|
|
||||||
`powerline-fonts`_ repository on GitHub for patched versions of some popular
|
|
||||||
programming fonts.
|
|
||||||
|
|
||||||
1. Download the font of your choice and install it by double-clicking the
|
|
||||||
font file in Finder and then click :guilabel:`Install this font` in the
|
|
||||||
preview window.
|
|
||||||
|
|
||||||
If you can't find your preferred font in the `powerline-fonts`_ repo,
|
|
||||||
you'll have to patch your own font instead. See :ref:`font-patching` for
|
|
||||||
instructions.
|
|
||||||
2. Configure MacVim or your terminal emulator to use the patched font (the
|
|
||||||
correct font usually ends with *for Powerline*).
|
|
||||||
|
|
||||||
.. _powerline-fonts: https://github.com/Lokaltog/powerline-fonts
|
|
||||||
|
|
||||||
Troubleshooting
|
|
||||||
===============
|
|
||||||
|
|
||||||
.. contents::
|
|
||||||
:local:
|
|
||||||
|
|
||||||
I can't see any fancy symbols, what's wrong?
|
|
||||||
--------------------------------------------
|
|
||||||
|
|
||||||
* If you're using iTerm2, please update to `this revision
|
|
||||||
<https://github.com/gnachman/iTerm2/commit/8e3ad6dabf83c60b8cf4a3e3327c596401744af6>`_
|
|
||||||
or newer.
|
|
||||||
* You need to set your ``LANG`` and ``LC_*`` environment variables to
|
|
||||||
a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro's
|
|
||||||
documentation for information about setting these variables correctly.
|
|
||||||
|
|
||||||
The colors look weird in the default OS X Terminal app!
|
|
||||||
-------------------------------------------------------
|
|
||||||
|
|
||||||
* The arrows may have the wrong colors if you have changed the "minimum
|
|
||||||
contrast" slider in the color tab of your OS X settings.
|
|
||||||
* The default OS X Terminal app is known to have some issues with the
|
|
||||||
Powerline colors. Please use another terminal emulator. iTerm2 should work
|
|
||||||
fine.
|
|
||||||
|
|
||||||
The colors look weird in iTerm2!
|
|
||||||
--------------------------------
|
|
||||||
|
|
||||||
* The arrows may have the wrong colors if you have changed the "minimum
|
|
||||||
contrast" slider in the color tab of your OS X settings.
|
|
||||||
* Please disable background transparency to resolve this issue.
|
|
||||||
|
|
||||||
Statusline is getting wrapped to the next line in iTerm2
|
|
||||||
--------------------------------------------------------
|
|
||||||
|
|
||||||
* Turn off “Treat ambigious-width characters as double width” in `Preferences
|
|
||||||
--> Text`.
|
|
||||||
* Alternative: remove fancy dividers (they suck in this case), set
|
|
||||||
:ref:`ambiwidth <config-common-ambiwidth>` to 2.
|
|
||||||
|
|
||||||
I receive a ``NameError`` when trying to use Powerline with MacVim!
|
|
||||||
-------------------------------------------------------------------
|
|
||||||
|
|
||||||
* Please install MacVim using this command::
|
|
||||||
|
|
||||||
brew install macvim --env-std --override-system-vim
|
|
||||||
|
|
||||||
Then install Powerline locally with ``pip install --user``, or by
|
|
||||||
running these commands in the ``powerline`` directory::
|
|
||||||
|
|
||||||
./setup.py build
|
|
||||||
./setup.py install --user
|
|
||||||
|
|
||||||
I receive an ``ImportError`` when trying to use Powerline on OS X!
|
|
||||||
------------------------------------------------------------------
|
|
||||||
|
|
||||||
* This is caused by an invalid ``sys.path`` when using system vim and system
|
|
||||||
Python. Please try to select another Python distribution::
|
|
||||||
|
|
||||||
sudo port select python python27-apple
|
|
||||||
|
|
||||||
* See `issue #39 <https://github.com/Lokaltog/powerline/issues/39>`_ for
|
|
||||||
a discussion and other possible solutions for this issue.
|
|
||||||
|
|
||||||
.. include:: troubleshooting-common.rst
|
|
||||||
|
|
|
||||||
|
|
@ -1,136 +0,0 @@
|
||||||
I'm using tmux and Powerline looks like crap, what's wrong?
|
|
||||||
-----------------------------------------------------------
|
|
||||||
|
|
||||||
* You need to tell tmux that it has 256-color capabilities. Add this to your
|
|
||||||
:file:`.tmux.conf` to solve this issue::
|
|
||||||
|
|
||||||
set -g default-terminal "screen-256color"
|
|
||||||
|
|
||||||
* If you're using iTerm2, make sure that you have enabled the setting
|
|
||||||
:guilabel:`Set locale variables automatically` in :menuselection:`Profiles
|
|
||||||
--> Terminal --> Environment`.
|
|
||||||
|
|
||||||
I’m using tmux/screen and Powerline is colorless
|
|
||||||
------------------------------------------------
|
|
||||||
|
|
||||||
* If the above advices do not help, then you need to disable
|
|
||||||
:ref:`term_truecolor <config-common-term_truecolor>`.
|
|
||||||
* Alternative: set :ref:`additional_escapes <config-common-additional_escapes>`
|
|
||||||
to ``"tmux"`` or ``"screen"``. Note that it is known to work perfectly in
|
|
||||||
screen, but in tmux it may produce ugly spaces.
|
|
||||||
|
|
||||||
|
|
||||||
After an update something stopped working
|
|
||||||
-----------------------------------------
|
|
||||||
|
|
||||||
Assuming powerline was working before update and stopped only after there are
|
|
||||||
two possible explanations:
|
|
||||||
|
|
||||||
* You have more then one powerline installation (e.g. ``pip`` and ``Vundle``
|
|
||||||
installations) and you have updated only one.
|
|
||||||
* Update brought some bug to powerline.
|
|
||||||
|
|
||||||
In the second case you, of course, should report the bug to `powerline bug
|
|
||||||
tracker <https://github.com/Lokaltog/powerline>`_. In the first you should make
|
|
||||||
sure you either have only one powerline installation or you update all of them
|
|
||||||
simultaneously (beware that in the second case you are not supported). To
|
|
||||||
diagnose this problem you may do the following:
|
|
||||||
|
|
||||||
#) If this problem is observed within the shell make sure that
|
|
||||||
|
|
||||||
.. code-block:: shell
|
|
||||||
|
|
||||||
python -c 'import powerline; print (powerline.__file__)'
|
|
||||||
|
|
||||||
which should report something like
|
|
||||||
:file:`/usr/lib64/python2.7/site-packages/powerline/__init__.pyc` (if
|
|
||||||
powerline is installed system-wide) or
|
|
||||||
:file:`/home/USER/.../powerline/__init__.pyc` (if powerline was cloned
|
|
||||||
somewhere, e.g. in :file:`/home/USER/.vim/bundle/powerline`) reports the same
|
|
||||||
location you use to source in your shell configuration: in first case it
|
|
||||||
should be some location in :file:`/usr` (e.g.
|
|
||||||
:file:`/usr/share/zsh/site-contrib/powerline.zsh`), in the second it should
|
|
||||||
be something like
|
|
||||||
:file:`/home/USER/.../powerline/bindings/zsh/powerline.zsh`. If this is true
|
|
||||||
it may be a powerline bug, but if locations do not match you should not
|
|
||||||
report the bug until you observe it on configuration where locations do
|
|
||||||
match.
|
|
||||||
#) If this problem is observed within the vim instance you should check out the
|
|
||||||
output of the following Ex mode commands
|
|
||||||
|
|
||||||
.. code-block:: vim
|
|
||||||
|
|
||||||
python import powerline as pl ; print (pl.__file__)
|
|
||||||
python3 import powerline as pl ; print (pl.__file__)
|
|
||||||
|
|
||||||
One (but not both) of them will most likely error out, this is OK. The same
|
|
||||||
rules apply as in the 1), but in place of sourcing you should seek for the
|
|
||||||
place where you modify `runtimepath` vim option. If you install powerline
|
|
||||||
using `VAM <https://github.com/MarcWeber/vim-addon-manager>`_ then no
|
|
||||||
explicit modifications of runtimpath were performed in your vimrc
|
|
||||||
(runtimepath is modified by VAM in this case), but powerline will be placed
|
|
||||||
in :file:`{plugin_root_dir}/powerline` where `{plugin_root_dir}` is stored in
|
|
||||||
VAM settings dictionary: do `echo g:vim_addon_manager.plugin_root_dir`.
|
|
||||||
|
|
||||||
There is a hint if you want to place powerline repository somewhere, but still
|
|
||||||
make powerline package importable anywhere: use
|
|
||||||
|
|
||||||
.. code-block:: shell
|
|
||||||
|
|
||||||
pip install --user --editable path/to/powerline
|
|
||||||
|
|
||||||
My vim statusline has strange characters like ``^B`` in it!
|
|
||||||
-----------------------------------------------------------
|
|
||||||
|
|
||||||
* Please add ``set encoding=utf-8`` to your :file:`vimrc`.
|
|
||||||
|
|
||||||
My vim statusline has a lot of ``^`` or underline characters in it!
|
|
||||||
-------------------------------------------------------------------
|
|
||||||
|
|
||||||
* You need to configure the ``fillchars`` setting to disable statusline
|
|
||||||
fillchars (see ``:h fillchars`` for details). Add this to your
|
|
||||||
:file:`vimrc` to solve this issue:
|
|
||||||
|
|
||||||
.. code-block:: vim
|
|
||||||
|
|
||||||
set fillchars+=stl:\ ,stlnc:\
|
|
||||||
|
|
||||||
My vim statusline is hidden/only appears in split windows!
|
|
||||||
----------------------------------------------------------
|
|
||||||
|
|
||||||
* Make sure that you have ``set laststatus=2`` in your :file:`vimrc`.
|
|
||||||
|
|
||||||
My vim statusline is not displayed completely and has too much spaces
|
|
||||||
---------------------------------------------------------------------
|
|
||||||
|
|
||||||
* Be sure you have ``ambiwidth`` option set to ``single``.
|
|
||||||
* Alternative: set :ref:`ambiwidth <config-common-ambiwidth>` to 2, remove fancy
|
|
||||||
dividers (they suck when ``ambiwidth`` is set to double).
|
|
||||||
|
|
||||||
When using z powerline shows wrong number of jobs
|
|
||||||
-------------------------------------------------
|
|
||||||
|
|
||||||
This happens because `z <https://github.com/rupa/z>`_ is launching some jobs in
|
|
||||||
the background from ``$POWERLINE_COMMAND`` and these jobs fail to finish before
|
|
||||||
powerline prompt is run.
|
|
||||||
|
|
||||||
Solution to this problem is simple: be sure that :file:`z.sh` is sourced
|
|
||||||
strictly after :file:`powerline/bindings/bash/powerline.sh`. This way background
|
|
||||||
jobs are spawned by `z <https://github.com/rupa/z>`_ after powerline has done
|
|
||||||
its job.
|
|
||||||
|
|
||||||
I am suffering bad lags before displaying shell prompt
|
|
||||||
------------------------------------------------------
|
|
||||||
|
|
||||||
To get rid of these lags there currently are two options:
|
|
||||||
|
|
||||||
* Run ``powerline-daemon``. Powerline does not automatically start it for you.
|
|
||||||
* Compile and install ``libzpython`` module that lives in
|
|
||||||
https://bitbucket.org/ZyX_I/zpython. This variant is zsh-specific.
|
|
||||||
|
|
||||||
Prompt is spoiled after completing files in ksh
|
|
||||||
-----------------------------------------------
|
|
||||||
|
|
||||||
This is exactly why powerline has official mksh support, but not official ksh
|
|
||||||
support. If you know the solution feel free to share it in `powerline bug
|
|
||||||
tracker <https://github.com/Lokaltog/powerline/issues/new>`_.
|
|
||||||
|
|
@ -1,65 +0,0 @@
|
||||||
************
|
|
||||||
Introduction
|
|
||||||
************
|
|
||||||
|
|
||||||
This is the next version of Powerline, implemented in Python. It aims to
|
|
||||||
resolve some of the "unresolvable" problems of the vimscript implementation,
|
|
||||||
as well as providing a common code base for all projects that use Powerline
|
|
||||||
in some way (e.g. shell prompts and tmux themes).
|
|
||||||
|
|
||||||
The project is currently in beta, and most of the functionality in the old
|
|
||||||
vimscript project is already implemented.
|
|
||||||
|
|
||||||
Screenshots
|
|
||||||
===========
|
|
||||||
|
|
||||||
**Mode-dependent highlighting**
|
|
||||||
|
|
||||||
* .. image:: _static/img/pl-mode-normal.png
|
|
||||||
:alt: Normal mode
|
|
||||||
* .. image:: _static/img/pl-mode-insert.png
|
|
||||||
:alt: Insert mode
|
|
||||||
* .. image:: _static/img/pl-mode-visual.png
|
|
||||||
:alt: Visual mode
|
|
||||||
* .. image:: _static/img/pl-mode-replace.png
|
|
||||||
:alt: Replace mode
|
|
||||||
|
|
||||||
**Automatic truncation of segments in small windows**
|
|
||||||
|
|
||||||
* .. image:: _static/img/pl-truncate1.png
|
|
||||||
:alt: Truncation illustration
|
|
||||||
* .. image:: _static/img/pl-truncate2.png
|
|
||||||
:alt: Truncation illustration
|
|
||||||
* .. image:: _static/img/pl-truncate3.png
|
|
||||||
:alt: Truncation illustration
|
|
||||||
|
|
||||||
The font in the screenshots is `Pragmata Pro`_ by Fabrizio Schiavi.
|
|
||||||
|
|
||||||
.. _`Pragmata Pro`: http://www.fsd.it/fonts/pragmatapro.htm
|
|
||||||
|
|
||||||
Feature highlights
|
|
||||||
==================
|
|
||||||
|
|
||||||
* **Better performance.** Python performs quite a bit better than vimscript,
|
|
||||||
and by having most of the code in Python instead of vimscript it's also
|
|
||||||
much easier to profile the code and eliminate bottlenecks.
|
|
||||||
* **A much leaner code base.** With most of the functionality of the old
|
|
||||||
project implemented the new version consists of less than half the amount
|
|
||||||
of code.
|
|
||||||
* **Automatic removal of less important segments in small windows.** Not all
|
|
||||||
information is equally important to have in the statusline, and segments
|
|
||||||
with e.g. encoding and file format information are automatically removed
|
|
||||||
in smaller windows.
|
|
||||||
* **Dynamic statusline evaluation in Python.** Statuslines are dynamically
|
|
||||||
rendered in Python instead of relying on vim's statusline flags, which
|
|
||||||
allows much more flexibility when creating statuslines.
|
|
||||||
* **The possibility of adding more segments.** Because of vim's hardcoded
|
|
||||||
limitation of 80 statusline options, the vimscript implementation
|
|
||||||
triggered an error when adding more segments to the default theme. Since
|
|
||||||
segment contents are now rendered as plain text in Python it's possible to
|
|
||||||
add many more segments in the statusline before reaching this limit.
|
|
||||||
* **New and improved theme and colorscheme syntax.** Themes and colorschemes
|
|
||||||
are now written in JSON, with a much cleaner syntax that's easier to learn
|
|
||||||
and work with. Themes and colorschemes are also much more configurable,
|
|
||||||
and it's easy to write your own and store them in your home config
|
|
||||||
directory.
|
|
||||||
|
|
@ -2,20 +2,14 @@
|
||||||
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
|
||||||
|
|
@ -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.
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,8 @@
|
||||||
|
*****************
|
||||||
|
Segment reference
|
||||||
|
*****************
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:glob:
|
||||||
|
|
||||||
|
segment-reference/*
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
*************
|
***************
|
||||||
Tips & Tricks
|
Tips and tricks
|
||||||
*************
|
***************
|
||||||
|
|
||||||
Vim
|
Vim
|
||||||
===
|
===
|
||||||
|
|
@ -0,0 +1,8 @@
|
||||||
|
***************
|
||||||
|
Troubleshooting
|
||||||
|
***************
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
|
||||||
|
Linux <troubleshooting/linux>
|
||||||
|
OS X <troubleshooting/osx>
|
||||||
|
|
@ -0,0 +1,3 @@
|
||||||
|
************************
|
||||||
|
Troubleshooting on Linux
|
||||||
|
************************
|
||||||
|
|
@ -0,0 +1,3 @@
|
||||||
|
***********************
|
||||||
|
Troubleshooting on OS X
|
||||||
|
***********************
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
*****
|
||||||
|
Usage
|
||||||
|
*****
|
||||||
|
|
||||||
|
Application support matrix
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
Plugins
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
|
||||||
|
usage/shell-prompts
|
||||||
|
usage/wm-widgets
|
||||||
|
usage/other
|
||||||
|
|
@ -0,0 +1,6 @@
|
||||||
|
*************
|
||||||
|
Other plugins
|
||||||
|
*************
|
||||||
|
|
||||||
|
tmux statusline
|
||||||
|
---------------
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
*************
|
||||||
|
Shell prompts
|
||||||
|
*************
|
||||||
|
|
||||||
|
bash
|
||||||
|
----
|
||||||
|
|
||||||
|
zsh
|
||||||
|
---
|
||||||
|
|
||||||
|
fish
|
||||||
|
----
|
||||||
|
|
||||||
|
IPython
|
||||||
|
-------
|
||||||
|
|
@ -0,0 +1,9 @@
|
||||||
|
**********************
|
||||||
|
Window manager widgets
|
||||||
|
**********************
|
||||||
|
|
||||||
|
Awesome
|
||||||
|
-------
|
||||||
|
|
||||||
|
Qtile
|
||||||
|
-----
|
||||||
Loading…
Reference in New Issue