mirror of
https://github.com/powerline/powerline.git
synced 2025-04-08 19:25:04 +02:00
f39b1dcf20
tmux configuration has become very fragmented between versions due to a combination of new features and deprecation of older options. As such, version checking for tmux became a requirement to allow maximum functionality along with version-appropriate configuration. However, wrapping nearly every line with `if-shell` is tedious and becomes virtually unreadable. This enhancement to tmux version-checking creates a logical configuration file structure that reflects the development of tmux. As additional configurations are added and tmux development continues, this structure can be leveraged appropriately and extended as needed. Rather than having multiple `if-shell` checks for the same version, each version or version group with specific requirements can be checked only once. This leads to simpler and fewer `if-shell` version checks. It also reduces the ambiguity introduced by complex `if-shell` commands that include an 'else' conditional. A caveat to adding this enhancement is the additional requirement of the end user to add a tmux variable definition (`POWERLINE_BINDINGS_DIR`) to his/her `~/.tmux.conf` file. For existing tmux users leveraging powerline, this may prove to be a slight one-time nuisance immediately after upgrading. Without this definition, there is no way to determine the location of the additional tmux powerline config files that have been added with this enhancement. The docs have also been updated in this commit to reflect this initial configuration requirement change. Also added are some additional troubleshooting notes that point to definition of this variable as a potential issue. Powerline will continue to work without the definition of `POWERLINE_BINDINGS_DIR`, but some of the functionality will be reduced and the appearance incomplete (i.e. colors). Ultimately, the caveat above is a small price to pay in exchange for a framework that can be leveraged for proper version-appropriate configuration of tmux going forward.
263 lines
8.1 KiB
ReStructuredText
263 lines
8.1 KiB
ReStructuredText
********
|
||
Overview
|
||
********
|
||
|
||
Requirements
|
||
============
|
||
|
||
Powerline requires Python 3.3 or Python 2.7 to work.
|
||
|
||
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.
|
||
|
||
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
|
||
--------------
|
||
|
||
If installed using pip just add
|
||
|
||
.. code-block:: vim
|
||
|
||
python from powerline.vim import setup as powerline_setup
|
||
python powerline_setup()
|
||
python del powerline_setup
|
||
|
||
(replace ``python`` with ``python3`` if appropriate) to your :file:`vimrc`.
|
||
|
||
If you just cloned the repository add the following line to your :file:`vimrc`,
|
||
where ``{repository_root}`` is the absolute path to your Powerline installation
|
||
directory:
|
||
|
||
.. code-block:: vim
|
||
|
||
set rtp+={repository_root}/powerline/bindings/vim
|
||
|
||
If you're using Vundle or Pathogen and don't want Powerline functionality in
|
||
any other applications, simply add Powerline as a bundle and point the path
|
||
above to the Powerline bundle directory, e.g.
|
||
``~/.vim/bundle/powerline/powerline/bindings/vim``. For vim-addon-manager it is
|
||
even easier since you don’t need to write this big path or install anything by
|
||
hand: ``powerline`` is installed and run just like any other plugin using
|
||
|
||
.. code-block:: vim
|
||
|
||
call vam#ActivateAddons(['powerline'])
|
||
|
||
Note: when using Gentoo ebuild you need to specify ``USE=vim`` to enable
|
||
powerline.
|
||
|
||
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:
|
||
|
||
Tmux statusline
|
||
---------------
|
||
|
||
Add the following lines to your :file:`.tmux.conf`, where ``{repository_root}``
|
||
is the absolute path to your Powerline installation directory (please note that
|
||
the definition of the ``POWERLINE_BINDINGS_DIR`` variable is required for full
|
||
powerline support)::
|
||
|
||
POWERLINE_BINDINGS_DIR="{repository_root}/powerline/bindings"
|
||
source "$POWERLINE_BINDINGS_DIR/tmux/powerline.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.
|