README.rst
1Powerline
2=========
3
4.. image:: https://api.travis-ci.org/powerline/powerline.svg?branch=develop
5 :target: `travis-build-status`_
6 :alt: Build status
7.. _travis-build-status: https://travis-ci.org/powerline/powerline
8
9**Powerline is a statusline plugin for vim, and provides statuslines and
10prompts for several other applications, including zsh, bash, fish, tmux,
11IPython, Awesome, i3 and Qtile.**
12
13+---------+---------------------------------------------------+
14| Author | Kim Silkebækken (kim.silkebaekken+vim@gmail.com) |
15+---------+---------------------------------------------------+
16| Source | https://github.com/powerline/powerline |
17+---------+---------------------------------------------------+
18| Version | beta |
19+---------+---------------------------------------------------+
20
21**Powerline does not support python2 anymore and powerline will stop working with python2 in the near future.**
22
23Features
24--------
25
26* **Extensible and feature rich, written in Python.** Powerline was
27 completely rewritten in Python to get rid of as much vimscript as
28 possible. This has allowed much better extensibility, leaner and better
29 config files, and a structured, object-oriented codebase with no mandatory
30 third-party dependencies other than a Python interpreter.
31* **Stable and testable code base.** Using Python has allowed unit testing
32 of all the project code. The code is tested to work in Python 3.6+.
33* **Support for prompts and statuslines in many applications.** Originally
34 created exclusively for vim statuslines, the project has evolved to
35 provide statuslines in tmux and several WMs, and prompts for shells like
36 bash/zsh and other applications. It’s simple to write renderers for any
37 other applications that Powerline doesn’t yet support.
38* **Configuration and colorschemes written in JSON.** JSON is
39 a standardized, simple and easy to use file format that allows for easy
40 user configuration across all of Powerline’s supported applications.
41* **Fast and lightweight, with daemon support for even better performance.**
42 Although the code base spans a couple of thousand lines of code with no
43 goal of “less than X lines of code”, the main focus is on good performance
44 and as little code as possible while still providing a rich set of
45 features. The new daemon also ensures that only one Python instance is
46 launched for prompts and statuslines, which provides excellent
47 performance.
48
49*But I hate Python / I don’t need shell prompts / this is just too much
50hassle for me / what happened to the original vim-powerline project / …*
51
52You should check out some of the Powerline derivatives. The most lightweight
53and feature-rich alternative is currently the `vim-airline
54<https://github.com/vim-airline/vim-airline>`_ project.
55
56Configuration
57-------------
58
59Basic powerline configuration is done via `JSON` files located at `.config/powerline/`. It is a good idea to start by copying the default configuration located at `powerline_root/powerline/config_files/` to `.config/powerline/`.
60If you installed the powerline from the AUR or via pip, `powerline_root` should be `/usr/lib/python3.6/site-packages/` or something similar, depending on your python version.
61
62If you installed powerline via apt-get 'powerline_root' should be '/usr/share/powerline/'.
63
64This should yield you the following directory structure:
65
66 ::
67
68 .config/powerline/
69 ├── colorschemes
70 │ ├── ...
71 │ └── wm
72 | └── default.json // Your configuration goes here
73 ├── colors.json
74 ├── config.json
75 └── themes
76 ├── ...
77 └── wm
78 └── default.json // Your configuration goes here
79
80
81
82The files in the subdirectories of `themes` are used to specify which segments shall be shown; the files in subdirectories of `colorschemes` are used to specify which colors (as defined in `colors.json`) shall be used to display a segment.
83
84Note that your local configuration only overrides the global configuration, it does not replace it, i.e. if you don't configure something locally, the global default will be used instead.
85
86* Consult the `documentation <https://powerline.readthedocs.org/en/latest/configuration.html#quick-setup-guide>`_ for more details. See also the `segment reference <https://powerline.readthedocs.org/en/latest/configuration/segments.html>`_ for available segments and their configuration.
87* Check out `powerline-fonts <https://github.com/powerline/fonts>`_ for
88 pre-patched versions of popular, open source coding fonts.
89
90Screenshots
91-----------
92
93Vim statusline
94^^^^^^^^^^^^^^
95
96**Mode-dependent highlighting**
97
98* .. image:: https://raw.github.com/powerline/powerline/develop/docs/source/_static/img/pl-mode-normal.png
99 :alt: Normal mode
100* .. image:: https://raw.github.com/powerline/powerline/develop/docs/source/_static/img/pl-mode-insert.png
101 :alt: Insert mode
102* .. image:: https://raw.github.com/powerline/powerline/develop/docs/source/_static/img/pl-mode-visual.png
103 :alt: Visual mode
104* .. image:: https://raw.github.com/powerline/powerline/develop/docs/source/_static/img/pl-mode-replace.png
105 :alt: Replace mode
106
107**Automatic truncation of segments in small windows**
108
109* .. image:: https://raw.github.com/powerline/powerline/develop/docs/source/_static/img/pl-truncate1.png
110 :alt: Truncation illustration
111* .. image:: https://raw.github.com/powerline/powerline/develop/docs/source/_static/img/pl-truncate2.png
112 :alt: Truncation illustration
113* .. image:: https://raw.github.com/powerline/powerline/develop/docs/source/_static/img/pl-truncate3.png
114 :alt: Truncation illustration
115
116----
117
118The font in the screenshots is `Pragmata Pro`_ by Fabrizio Schiavi.
119
120.. _`Pragmata Pro`: http://www.fsd.it/shop/fonts/pragmatapro
121
