When non-empty, this option determines the content of the status line. Also see status-line.

The option consists of printf style '%' items interspersed with normal text. Each status line item is of the form: %-0**{minwid}.{maxwid}****{item}** All fields except the {item} are optional. A single percent sign can be given as "%%".

When the option starts with "%!" then it is used as an expression, evaluated and the result is used as the option value. Example:

:set statusline=%!MyStatusLine()

The g:statusline_winid variable will be set to the window-ID of the window that the status line belongs to. The result can contain %{} items that will be evaluated too. Note that the "%!" expression is evaluated in the context of the current window and buffer, while %{} items are evaluated in the context of the window that the statusline belongs to.

When there is error while evaluating the option then it will be made empty to avoid further errors. Otherwise screen updating would loop. When the result contains unprintable characters the result is unpredictable.

Note that the only effect of 'ruler' when this option is set (and 'laststatus' is 2) is controlling the output of CTRL-G.

field meaning

•       Left justify the item.  The default is right justified
        when minwid is larger than the length of the item.
  

0 Leading zeroes in numeric items. Overridden by '-'. minwid Minimum width of the item, padding as set by '-' & '0'. Value must be 50 or less. maxwid Maximum width of the item. Truncation occurs with a '<' on the left for text items. Numeric items will be shifted down to maxwid-2 digits followed by '>'number where number is the amount of missing digits, much like an exponential notation. item A one letter code as described below.

Following is a description of the possible statusline items. The second character in "item" is the type: N for number S for string F for flags as described below - not applicable

item meaning f S Path to the file in the buffer, as typed or relative to current directory. F S Full path to the file in the buffer. t S File name (tail) of file in the buffer. m F Modified flag, text is "[+]"; "[-]" if 'modifiable' is off. M F Modified flag, text is ",+" or ",-". r F Readonly flag, text is "[RO]". R F Readonly flag, text is ",RO". h F Help buffer flag, text is "[help]". H F Help buffer flag, text is ",HLP". w F Preview window flag, text is "[Preview]". W F Preview window flag, text is ",PRV". y F Type of file in the buffer, e.g., "[vim]". See 'filetype'. Y F Type of file in the buffer, e.g., ",VIM". See 'filetype'. q S "[Quickfix List]", "[Location List]" or empty. k S Value of "b:keymap_name" or 'keymap' when :lmap mappings are being used: "<keymap>" n N Buffer number. b N Value of character under cursor. B N As above, in hexadecimal. o N Byte number in file of byte under cursor, first byte is 1. Mnemonic: Offset from start of file (with one added) not available when compiled without +byte_offset feature O N As above, in hexadecimal. N N Printer page number. (Only works in the 'printheader' option.) l N Line number. L N Number of lines in buffer. c N Column number (byte index). v N Virtual column number (screen column). V N Virtual column number as -{num}. Not displayed if equal to 'c'. p N Percentage through file in lines as in CTRL-G. P S Percentage through file of displayed window. This is like the percentage described for 'ruler'. Always 3 in length, unless translated. S S 'showcmd' content, see 'showcmdloc'. a S Argument list status as in default title. ({current} of {max}) Empty if the argument file count is zero or one. { NF Evaluate expression between '%{' and '}' and substitute result. Note that there is no '%' before the closing '}'. The expression cannot contain a '}' character, call a function to work around that. See stl-%{ below. {% - This is almost same as { except the result of the expression is re-evaluated as a statusline format string. Thus if the return value of expr contains % items they will get expanded. The expression can contain the } character, the end of expression is denoted by %}. For example:

      func! Stl_filename() abort
          return "%t"
      endfunc

    `stl=%{Stl_filename()}`   results in `"%t"`
    `stl=%{%Stl_filename()%}` results in `"Name of current file"`

%} - End of {% expression ( - Start of item group. Can be used for setting the width and alignment of a section. Must be followed by %) somewhere. ) - End of item group. No width fields allowed. T N For 'tabline': start of tab page N label. Use %T after the last label. This information is used for mouse clicks. X N For 'tabline': start of close tab N label. Use %X after the label, e.g.: %3Xclose%X. Use %999X for a "close current tab" mark. This information is used for mouse clicks. < - Where to truncate line if too long. Default is at the start. No width fields allowed. = - Separation point between alignment sections. Each section will be separated by an equal number of spaces. With one %= what comes after it will be right-aligned. With two %= there is a middle part, with white space left and right of it. No width fields allowed. # - Set highlight group. The name must follow and then a # again. Thus use %#HLname# for highlight group HLname. The same highlighting is used, also for the statusline of non-current windows.

• • Set highlight group to User**{N}, where {N} is taken from the minwid field, e.g. %1*. Restore normal highlight with %* or %0*. The difference between User{N}** and StatusLine will be applied to StatusLineNC for the statusline of non-current windows. The number N must be between 1 and 9. See hl-User1..9

When displaying a flag, Vim removes the leading comma, if any, when that flag comes right after plaintext. This will make a nice display when flags are used like in the examples below.

When all items in a group becomes an empty string (i.e. flags that are not set) and a minwid is not set for the group, the whole group will become empty. This will make a group like the following disappear completely from the statusline when none of the flags are set.

:set statusline=...%(\ [%M%R%H]%)...

Beware that an expression is evaluated each and every time the status line is displayed.

While evaluating %{} the current buffer and current window will be set temporarily to that of the window (and buffer) whose statusline is currently being drawn. The expression will evaluate in this context. The variable "g:actual_curbuf" is set to the bufnr() number of the real current buffer and "g:actual_curwin" to the window-ID of the real current window. These values are strings.

The 'statusline' option will be evaluated in the sandbox if set from a modeline, see sandbox-option. This option cannot be set in a modeline when 'modelineexpr' is off.

It is not allowed to change text or jump to another window while evaluating 'statusline' textlock.

If the statusline is not updated when you want it (e.g., after setting a variable that's used in an expression), you can force an update by using :redrawstatus.

A result of all digits is regarded a number for display purposes. Otherwise the result is taken as flag text and applied to the rules described above.

Watch out for errors in expressions. They may render Vim unusable! If you are stuck, hold down ':' or 'Q' to get a prompt, then quit and edit your .vimrc or whatever with "vim --clean" to get it right.

Examples: Emulate standard status line with 'ruler' set

:set statusline=%<%f\ %h%m%r%=%-14.(%l,%c%V%)\ %P

Similar, but add ASCII value of char under the cursor (like "ga")

:set statusline=%<%f%h%m%r%=%b\ 0x%B\ \ %l,%c%V\ %P

Display byte count and byte value, modified flag in red.

:set statusline=%<%f%=\ [%1*%M%*%n%R%H]\ %-19(%3l,%02c%03V%)%O'%02b'
:hi User1 term=inverse,bold cterm=inverse,bold ctermfg=red

Display a ,GZ flag if a compressed file is loaded

:set statusline=...%r%{VarExists('b:gzflag','\ [GZ]')}%h...

In the :autocmd's:

:let b:gzflag = 1

And:

:unlet b:gzflag

And define this function:

:function VarExists(var, val)
:    if exists(a:var) | return a:val | else | return '' | endif
:endfunction

(default empty)

not available when compiled without the +statusline feature