git.r.bdr.sh - rbdr/dotfiles/blob - 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: