]> git.r.bdr.sh - rbdr/dotfiles/blob - vim/doc/Powerline.txt
7ec7a50cc4adedb4d8b5fa8e828ffef71c9e6910
[rbdr/dotfiles] / vim / doc / Powerline.txt
1 *Powerline.txt* For Vim version 7.3. Last change: 2011 Nov 23
2
3 ______
4 _________ \ /__
5 \_____ \______ _ _____________ / /'__' ___ ____
6 | ___/ _ \ \/ \/ / __ \_ ___\ / | |/ \_/ __ \
7 | | | (_) \ _ / ___/| | / /__| | | \ ___/
8 '___' \____/ \/ \/ \___ |__' /___ /'__'__| /\___ \
9 \/ / / \/ \/
10 | /
11 |/
12 '
13
14 ==============================================================================
15 CONTENTS *Powerline-contents*
16
17 1. Introduction ....................... |Powerline-introduction|
18 2. Usage .............................. |Powerline-usage|
19 3. Requirements ....................... |Powerline-requirements|
20 3.1 Recommended settings ........... |Powerline-recommended-settings|
21 4. Configuration ...................... |Powerline-configuration|
22 4.1 Powerline_cache_file ........... |Powerline_cache_file|
23 4.1.1 Clearing the cache ....... |:PowerlineClearCache|
24 4.2 Powerline_cache_enabled ........ |Powerline_cache_enabled|
25 4.3 Powerline_symbols .............. |Powerline_symbols|
26 4.3.1 Compatible symbols ....... |Powerline-symbols-compatible|
27 4.3.2 Fancy symbols ............ |Powerline-symbols-fancy|
28 4.4 Powerline_theme ................ |Powerline_theme|
29 4.5 Powerline_colorscheme .......... |Powerline_colorscheme|
30 5. Fonts .............................. |Powerline-fonts|
31 6. Customization ...................... |Powerline-customization|
32 6.1 Basic customization ............ |Powerline-basic-customization|
33 6.2 Advanced customization ......... |Powerline-advanced-customization|
34 6.2.1 Colorschemes ............. |Powerline-cust-colorschemes|
35 6.2.2 Functions ................ |Powerline-cust-functions|
36 6.2.3 Segments ................. |Powerline-cust-segments|
37 6.2.4 Themes ................... |Powerline-cust-themes|
38 7. License ............................ |Powerline-license|
39 8. Known issues ....................... |Powerline-known-issues|
40 9. Contributing ....................... |Powerline-contributing|
41
42 ==============================================================================
43 1. Introduction *Powerline* *Powerline-introduction*
44
45 Powerline is a utility plugin which allows you to create better-looking, more
46 functional vim statuslines.
47
48 ==============================================================================
49 2. Usage *Powerline-usage*
50
51 Powerline is automatically enabled when it's installed, either by unzipping
52 the provided archive or by adding it as a Pathogen/Vundle bundle.
53
54 ==============================================================================
55 3. Requirements *Powerline-requirements*
56
57 Powerline has been developed and tested in vim 7.3, but it should run without
58 any problems in vim 7.2. The default configuration requires a Unix-like system
59 to work properly.
60
61 The plugin only works with vim running in an 88/256-color terminal or gvim.
62
63 Vi-compatible mode must be disabled.
64
65 ------------------------------------------------------------------------------
66 3.1 Recommended settings *Powerline-recommended-settings*
67
68 The following configuration options should be set in your |vimrc|: >
69
70 set nocompatible " Disable vi-compatibility
71 set laststatus=2 " Always show the statusline
72 set encoding=utf-8 " Necessary to show unicode glyphs
73
74 Note: If you're using an 88/256-color terminal but still don't see the colored
75 statusline, you may have to set the following option as well: >
76
77 set t_Co=256 " Explicitly tell vim that the terminal supports 256 colors
78
79 ==============================================================================
80 4. Configuration *Powerline-configuration*
81
82 Powerline will work fine without any user configuration, but default behavior
83 can be overridden by setting configuration variables globally in your |vimrc|
84 file.
85
86 ------------------------------------------------------------------------------
87 4.1 Powerline_cache_file *Powerline_cache_file*
88
89 By default Powerline caches all the statuslines and colors in a cache file in
90 the plugin's directory (or the vim directory, depending on the installation
91 method used).
92
93 It's recommended that you enable the cache, as this dramatically improves vim
94 startup time after the cache file has been generated (the plugin usually loads
95 within ~100ms without the cache and ~1ms with the cache).
96
97 Note: The default cache filename includes the current theme, colorscheme and
98 symbol settings in order to tie the cache file your current configuration, so
99 the cache file will be regenerated when you change any settings. This may
100 leave several old cache files in your vim folder, and these may safely be
101 deleted.
102
103 Defaults: "<plugin_directory>/Powerline_<theme>_<colorscheme>_<symbols>.cache"
104
105 ------------------------------------------------------------------------------
106 4.1.1 Clearing the cache *:PowerlineClearCache*
107
108 Powerline provides a command to easily clear the cache after changing your
109 settings or updating your theme. Simply run the following command to clear
110 your cache, and restart vim afterwards: >
111
112 :PowerlineClearCache
113 <
114 ------------------------------------------------------------------------------
115 4.2 Powerline_cache_enabled *Powerline_cache_enabled*
116
117 It's possible to disable statusline caching by setting this option to 0. This
118 is mostly useful when developing statuslines.
119
120 Default: 1
121
122 ------------------------------------------------------------------------------
123 4.3 Powerline_symbols *Powerline_symbols*
124
125 This option defines which set of symbols and dividers you want to use. There
126 are currently three available options: "compatible", "unicode" and "fancy".
127
128 TYPE DESCRIPTION ~
129 compatible Doesn't use any special characters.
130 unicode Simulates icons and arrows using similar unicode glyphs.
131 fancy Custom icons and arrows. Requires a patched font.
132
133 Symbols can be inserted into statuslines by using the following variables
134 (just insert the variables as text in your segments):
135
136 VARIABLE DESCRIPTION ~
137 $BRANCH Inserts a branch symbol
138 $RO Inserts a read-only symbol
139 $FT Inserts a filetype symbol
140 $LINE Inserts a line number symbol
141
142 Default: "compatible"
143
144 ------------------------------------------------------------------------------
145 4.3.1 Compatible symbols *Powerline-symbols-compatible*
146
147 These symbols will work in any configuration, and do not require a special
148 font to work. This option will replace the fancy icons with plain text, and
149 the pointy dividers with straight lines.
150
151 ------------------------------------------------------------------------------
152 4.3.2 Fancy symbols *Powerline-symbols-fancy*
153
154 These symbols require a custom font to work. A font patcher is provided for
155 adding the required symbols to any outline font and some bitmap fonts, see
156 |Powerline-fonts| and the provided README file for usage details.
157
158 ------------------------------------------------------------------------------
159 4.4 Powerline_theme *Powerline_theme*
160
161 This option defines the theme Powerline uses. The available themes are located
162 in autoload/Powerline/Themes/.
163
164 Default: "default"
165
166 ------------------------------------------------------------------------------
167 4.5 Powerline_colorscheme *Powerline_colorscheme*
168
169 This option defines the colorscheme Powerline uses. The available colorschemes
170 are located in autoload/Powerline/Colorschemes/.
171
172 Default: "default"
173
174 ==============================================================================
175 5. Fonts *Powerline-fonts*
176
177 TODO
178
179 ==============================================================================
180 6. Customization *Powerline-customization*
181
182 There are currently two ways of customizing Powerline: Basic customization
183 using a couple of functions to insert and remove existing segments from the
184 statusline, and advanced customization using your own autoload files. The
185 customization features of Powerline allow you to create your own statuslines
186 without ever touching the original source code.
187
188 ------------------------------------------------------------------------------
189 6.1 Basic customization *Powerline-basic-customization*
190
191 Powerline provides the following functions to alter the default statusline
192 look. These functions should be called from your |vimrc| file or another file
193 which is sourced at vim startup.
194
195 Note: These functions are currently applied to all statuslines, so if you
196 insert a segment after a segment which is present in many statuslines (e.g.
197 the "filename" segment), all the statuslines will have the inserted segment.
198 This behavior may be changed in a future version of Powerline.
199
200 Note: Remember to clear your cache with |:PowerlineClearCache| after changing
201 your statusline!
202
203 Example: >
204
205 " Insert the charcode segment after the filetype segment
206 call Pl#Theme#InsertSegment('charcode', 'after', 'filetype')
207
208 " Replace the scrollpercent segment with the charcode segment
209 call Pl#Theme#ReplaceSegment('scrollpercent', 'fileinfo')
210 <
211 *Pl#Theme#InsertSegment*
212 Pl#Theme#InsertSegment({newsegment}, {location}, {targetsegment})
213
214 This function inserts {newsegment} before or after {targetsegment}. The
215 {location} parameter specifies the location of the new segment, valid values
216 are "before" and "after". You can see all the available segments in
217 autoload/Powerline/Segments.vim and the files specified in
218 |Powerline-cust-segments|.
219
220 Pl#Theme#RemoveSegment({targetsegment}) *Pl#Theme#RemoveSegment*
221
222 This function removes the {targetsegment} segment entirely.
223
224 Pl#Theme#ReplaceSegment({oldsegment}, {newsegment}) *Pl#Theme#ReplaceSegment*
225
226 This function replaces {oldsegment} with {newsegment}.
227
228 ------------------------------------------------------------------------------
229 6.2 Advanced customization *Powerline-advanced-customization*
230
231 Because Powerline utilizes vim's autoload functionality, you can easily create
232 your own segments, themes, functions and colorschemes without touching the
233 original source code. This is a bit more complex than using the utility
234 functions, but it allows you to do a lot more with your statusline.
235
236 Your custom autoload files should be stored in your |runtimepath| (usually in
237 "~/.vim/autoload/Powerline/*").
238
239 Note: Remember to clear your cache with |:PowerlineClearCache| after changing
240 your statusline!
241
242 6.2.1 Colorschemes *Powerline-cust-colorschemes*
243 ------------------------------------------------------------------------------
244
245 Colorschemes should be stored as separate files in
246 {runtimepath}/autoload/Powerline/Colorschemes/.
247
248 SYNTAX ~
249
250 TODO
251
252 EXAMPLE ~
253
254 TODO
255
256 6.2.2 Functions *Powerline-cust-functions*
257 ------------------------------------------------------------------------------
258
259 Functions should be stored as separate files in
260 {runtimepath}/autoload/Powerline/Functions/.
261
262 SYNTAX ~
263
264 TODO
265
266 EXAMPLE ~
267
268 TODO
269
270 6.2.3 Segments *Powerline-cust-segments*
271 ------------------------------------------------------------------------------
272
273 Segments should be stored as separate files in
274 {runtimepath}/autoload/Powerline/Segments/.
275
276 SYNTAX ~
277
278 TODO
279
280 EXAMPLE ~
281
282 TODO
283
284 6.2.4 Themes *Powerline-cust-themes*
285 ------------------------------------------------------------------------------
286
287 Themes should be stored as separate files in
288 {runtimepath}/autoload/Powerline/Themes/.
289
290 SYNTAX ~
291
292 TODO
293
294 EXAMPLE ~
295
296 TODO
297
298 ==============================================================================
299 7. License *Powerline-license*
300
301 Creative Commons Attribution-ShareAlike 3.0 Unported
302
303 http://creativecommons.org/licenses/by-sa/3.0/
304
305 ==============================================================================
306 8. Known issues *Powerline-known-issues*
307
308 See the issue tracker at
309 https://github.com/Lokaltog/vim-powerline/issues
310
311 ==============================================================================
312 9. Contributing *Powerline-contributing*
313
314 If you experience any bugs or have feature requests, please open an issue on
315 GitHub. Fork the source repository on GitHub and send a pull request if you
316 have any code improvements.
317
318 Author: Kim Silkebækken <kim.silkebaekken+vim@gmail.com>
319 Source repository: https://github.com/Lokaltog/vim-powerline
320
321 ==============================================================================
322 vim:tw=78:sw=4:ts=8:ft=help:norl: