vim-startify/doc/startify.txt

*startify.txt*  Showing recently used stuff like a boss.
*startify*
                __                    __           ___
               /\ \__                /\ \__  __  /'___\
           ____\ \ ,_\    __     _ __\ \ ,_\/\_\/\ \__/  __  __
          /',__\\ \ \/  /'__`\  /\`'__\ \ \/\/\ \ \ ,__\/\ \/\ \
         /\__, `\\ \ \_/\ \L\.\_\ \ \/ \ \ \_\ \ \ \ \_/\ \ \_\ \
         \/\____/ \ \__\ \__/.\_\\ \_\  \ \__\\ \_\ \_\  \/`____ \
          \/___/   \/__/\/__/\/_/ \/_/   \/__/ \/_/\/_/   `/___/> \
                                                             /\___/
                                                             \/__/
  by Marco Hinz~

  Twitter: https://twitter.com/_mhinz_
  Github:  http://github.com/mhinz
  IRC:     mhi^ (Freenode)
>
  If you use any of my plugins, please star them on github. It's a great way
  of getting feedback and gives me the kick to put more time into their
  development.

  If you encounter any bugs or have feature requests, just open an issue
  report on Github.

  Thank you for flying mhi^ airlines. Get the Vim on!
<
==============================================================================
CONTENTS                                                     *startify-contents*

    INTRO .......................................... |startify-intro|
    USAGE .......................................... |startify-usage|
    OPTIONS ........................................ |startify-options|
    AUTOCMD ........................................ |startify-autocmd|
    COMMANDS ....................................... |startify-commands|
    MAPPINGS ....................................... |startify-mappings|
    COLORS ......................................... |startify-colors|
    FAQ ............................................ |startify-faq|
    EXAMPLE ........................................ |startify-example|

==============================================================================
INTRO                                                           *startify-intro*

Startify is a plugin that shows recently used files, bookmarks and
sessions that were saved to a certain directory.

==============================================================================
USAGE                                                           *startify-usage*

Startify basically provides two things:

1) If you start Vim without giving any filenames to it (or pipe stuff to it so
   it reads from STDIN), startify will show a small but pretty start screen
   that shows recently used files (using viminfo) and sessions by default.

   Additionally, you can define bookmarks, thus entries for files that always
   should be available on the start screen.

   You can either navigate to a certain menu entry and hit enter or you just
   key in whatever is written between the square brackets on that line. You
   can even double-click anywhere on the line now.

   In addition, 'e' creates an empty buffer, 'i' creates an empty buffer and
   jumps into insert mode, 'q' quits.

   Moreover, you can open several files at one go. Navigate to an entry and
   hit either 'b' (open in same window), 's' (open in split), 'v' (open in
   vertical split) or 't' (open in tab). You can do that for multiple entries.
   You can also mix them. The order of the selections will be remembered.
   Afterwards execute these actions via <cr>.

   When the selection is finished, Startify will close automatically. You can
   reopen the screen via :Startify.

   And you can define your own custom ascii art header now!

2) It eases handling of loading and saving sessions by only working with a
   certain directory. These commands are used for convenience:

      :SLoad    load a session
      :SSave    save a session
      :SDelete  delete a session
      :SClose   close a session

==============================================================================
OPTIONS                                                       *startify-options*

Put these variables into your vimrc. The shown assignments are also the
default values.

    |g:startify_bookmarks|
    |g:startify_change_to_dir|
    |g:startify_change_to_vcs_root|
    |g:startify_custom_footer|
    |g:startify_custom_header|
    |g:startify_custom_indices|
    |g:startify_disable_at_vimenter|
    |g:startify_enable_special|
    |g:startify_enable_unsafe|
    |g:startify_files_number|
    |g:startify_list_order|
    |g:startify_relative_path|
    |g:startify_session_autoload|
    |g:startify_session_delete_buffers|
    |g:startify_session_dir|
    |g:startify_session_persistence|
    |g:startify_session_remove_lines|
    |g:startify_session_savecmds|
    |g:startify_session_savevars|
    |g:startify_skiplist_server|
    |g:startify_skiplist|

------------------------------------------------------------------------------
                                                        *g:startify_session_dir*
>
    let g:startify_session_dir = '~/.vim/session'
<
The directory to save/load sessions to/from.

The default for Windows systems is '$HOME\vimfiles\session'.

------------------------------------------------------------------------------
                                                         *g:startify_list_order*
>
    let g:startify_list_order = ['files', 'dir', 'bookmarks', 'sessions']
<
At the moment startify supports these lists:~

1) "files"

   This lists the most recently used files using viminfo. The number of files
   is limited by g:startify_files_number.

2) "dir"

   This lists the files from the current directory sorted by modification
   time. The number of files is limited by g:startify_files_number.

3) "bookmarks"

   This lists bookmarks, thus hardcoded files or directories that will always
   be shown. Have a look at g:startify_bookmarks.

4) "sessions"

   This lists all the sessions saved in the directory
   g:startify_session_dir.

Section headers:~

Additionally you can add lists of strings to that list. These will be shown
above the following item in |g:startify_list_order|.

NOTE: Section headers are context-senstive. This means that if the following
item is a startify list ("dir", "bookmarks", ...) and empty (no files in the
current directory, no bookmarks defined, ...), the section header won't be
shown as well.

NOTE: The section header use the StartifySection highlight group.

Section headers example:~
>
    let g:startify_list_order = [
            \ ['   My most recently', '   used files'],
            \ 'files',
            \ ['   My most recently used files in the current directory:'],
            \ 'dir',
            \ ['   These are my sessions:'],
            \ 'sessions',
            \ ['   These are my bookmarks:'],
            \ 'bookmarks',
            \ ]
<
Feel free to add some cool ASCII action!

------------------------------------------------------------------------------
                                                          *g:startify_bookmarks*
>
    let g:startify_bookmarks = []
<
A list of files or directories to bookmark. The list can contain two kinds of
types. Either a path or a dictionary whereas the key is the custom index and
the value the path.

Example:
>
    let g:startify_bookmarks = [ {'v': '~/.vimrc'}, '~/.zshrc' ]
<
------------------------------------------------------------------------------
                                                       *g:startify_files_number*
>
    let g:startify_files_number = 10
<
The number of files to list.

------------------------------------------------------------------------------
                                                   *g:startify_session_autoload*
>
    let g:startify_session_autoload = 0
<
If you fire up "vim" in a directory that contains a "Session.vim", that session
will be loaded automatically. Otherwise it will be shown as the top entry in
the Startify buffer.

This also works if you open a bookmarked directory.

Great way to create a portable project folder.

------------------------------------------------------------------------------
                                                *g:startify_session_persistence*
>
    let g:startify_session_persistence = 0
<
Automatically update sessions in two cases:

    1) Before leaving Vim
    2) Before loading a new session via :SLoad

This also works for sessions started with:
>
    vim -S mysession.vim
<
------------------------------------------------------------------------------
                                             *g:startify_session_delete_buffers*
>
    let g:startify_session_delete_buffers = 0
<
Delete open buffers before loading a new session.

------------------------------------------------------------------------------
                                                      *g:startify_change_to_dir*
>
    let g:startify_change_to_dir = 1
<
When opening a file or bookmark, change to its directory.

------------------------------------------------------------------------------
                                                 *g:startify_change_to_vcs_root*
>
    let g:startify_change_to_vcs_root = 0
<
When opening a file or bookmark, seek and change to the root directory of the
VCS (if there is one).

At the moment only git, hg, bzr and svn are supported.

------------------------------------------------------------------------------
                                                           *g:startify_skiplist*
>
    let g:startify_skiplist = [
        \ 'COMMIT_EDITMSG',
        \ escape(fnamemodify(resolve($VIMRUNTIME), ':p'), '\') .'doc',
        \ 'bundle/.*/doc',
        \ ]
<
A list of Vim regular expressions that is used to filter recently used files.
See |pattern.txt| for what patterns can be used.

NOTE: Due to the nature of patterns, you can't just use "~/mysecret" but have
to use "$HOME .'/mysecret.txt'". The former would do something entirely
different: |/\~|. When using backslashes as path separators, escape them.
Otherwise using "C:\this\vim\path\is\problematic" would not match what you
expect, since |/\v| is a pattern, too.

Example:
>
    let g:startify_skiplist = [
           \ '\.vimgolf',
           \ '^/tmp',
           \ '/project/.*/documentation',
           \ escape(fnamemodify($HOME, ':p'), '\') .'mysecret.txt',
           \ ]
<
------------------------------------------------------------------------------
                                                    *g:startify_skiplist_server*
>
    let g:startify_skiplist_server = []
<
Do not create the startify buffer, if this is a Vim server instance with a
name contained in this list.

Example:
>
    let g:startify_skiplist_server = [ 'GVIM' ]
<
------------------------------------------------------------------------------
                                                     *g:startify_enable_special*
>
    let g:startify_enable_special = 1
<
Show <empty buffer> and <quit>.
------------------------------------------------------------------------------
                                                      *g:startify_enable_unsafe*
>
    let g:startify_enable_unsafe = 0
<
Enable the option only in case you think Vim starts too slowly (because of
:Startify) or if you often edit files on remote filesystems.

It's called unsafe because it improves the time :Startify needs to execute by
reducing the amount of syscalls to the underlying operating system, but
sacrifices the precision of shown entries.

This could lead to inconsistences in the shown :Startify entries (e.g. the
same file could be shown twice, because one time file was opened via absolute
path and another time via symlink).

Currently this option does this:

    - don't resolves symlinks (readlink(2))
    - don't check every file if it's readable (stat(2))
    - don't filter through the bookmark list

------------------------------------------------------------------------------
                                               *g:startify_session_remove_lines*
>
    let g:startify_session_remove_lines = []
<
Lines matching any of the patterns in this list, will be removed from the
session file.

Example:
>
    let g:startify_session_remove_lines = ['setlocal', 'winheight']
<
Internally this simply does:
>
    :global/setlocal/delete
    :global/winheight/delete
<
So you can use any |pattern|.

NOTE: Take care not to mess up any expressions within the session file,
otherwise you'll probably get problems when trying to load it.

------------------------------------------------------------------------------
                                                   *g:startify_session_savevars*
>
    let g:startify_session_savevars = []
<
Include a list of variables in here which you would like Startify to save into
the session file in addition to what Vim normally saves into the session file.
For example, Vim will not normally save all-lowercase global variables, which
are common for plugin settings.  It may be advisable to include
|g:startify_session_savevars| and |g:startify_session_savecmds| into this list
so they are saved every time the session saves.

Example:
>
    let g:startify_session_savevars = [
           \ 'g:startify_session_savevars',
           \ 'g:startify_session_savecmds',
           \ 'g:random_plugin_use_feature'
           \ ]
<
------------------------------------------------------------------------------
                                                   *g:startify_session_savecmds*
>
    let g:startify_session_savecmds = []
<
Include a list of cmdline commands which Vim will run upon loading the
session.  This can be useful to set various things (other than variables,
|g:startify_session_savevars| above) which Vim may not normally save into the
session file, as well as run external commands upon loading a session.

Example:
>
    let g:startify_session_savecmds = [
           \ 'silent !pdfreader ~/latexproject/main.pdf &'
           \ ]
<
------------------------------------------------------------------------------
                                                     *g:startify_custom_indices*
>
    let g:startify_custom_indices = []
<
Use any list of strings as indices instead of increasing numbers. If there are
more startify entries than actual items in the custom list, the remaining
entries will be filled using the default numbering scheme starting from 0.

Thus you can create your own indexing scheme that fits your keyboard layout.
You don't want to leave the home row, do you?!

Example:
>
    let g:startify_custom_indices = ['f', 'g', 'h']
<
This would result in:

    [f]  /most/recently/used/file1
    [g]  /most/recently/used/file2
    [h]  /most/recently/used/file3
    [0]  /most/recently/used/file4
    [1]  /most/recently/used/file5
    [2]  /most/recently/used/file6
    etc.

If you want numbers to start at 1 instead of 0, you could use this:
>
    let g:startify_custom_indices = map(range(1,100), 'string(v:val)')
<
NOTE: There is no sanitizing going on, so you should know what you're doing!

Best practices:

- do not use 'e', 'i' or 'q'  (they will be overwritten anyway)
- do not use 'b', 's', 't', 'v'  (used for opening several files at once)
- do not use duplicates  (previous mappings will be overwritten)
- do not uses empty strings  (creates unreachable entries)
- you might want to keep 'j' and 'k'  (for navigation)

------------------------------------------------------------------------------
                                                      *g:startify_custom_header*
>
    let g:startify_custom_header = ''
<
This is a list of single-quoted strings to be shown before everything else.
Every string will be written on its own line.

NOTE: If a string contains ', you have to quote it with another '.

A programmatic example:
>
    let g:startify_custom_header =
      \ map(split(system('fortune | cowsay'), '\n'), '"   ". v:val') + ['','']
<
A hardcoded example:
>
    let g:startify_custom_header = [
            \ '                                 ________  __ __        ',
            \ '            __                  /\_____  \/\ \\ \       ',
            \ '    __  __ /\_\    ___ ___      \/___//''/''\ \ \\ \    ',
            \ '   /\ \/\ \\/\ \ /'' __` __`\        /'' /''  \ \ \\ \_ ',
            \ '   \ \ \_/ |\ \ \/\ \/\ \/\ \      /'' /''__  \ \__ ,__\',
            \ '    \ \___/  \ \_\ \_\ \_\ \_\    /\_/ /\_\  \/_/\_\_/  ',
            \ '     \/__/    \/_/\/_/\/_/\/_/    \//  \/_/     \/_/    ',
            \ '',
            \ '',
            \ ]
<

Also have a look at |startify-faq-08|.

------------------------------------------------------------------------------
                                                      *g:startify_custom_footer*
>
    let g:startify_custom_footer = ''
<
Same as the custom header, but shown at the bottom of the startify buffer.

------------------------------------------------------------------------------
                                                *g:startify_disable_at_vimenter*
>
    let g:startify_disable_at_vimenter = 0
<
Don't run Startify at Vim startup. You can still call it anytime via
:Startify.

-----------------------------------------------------------------------------
                                                     *g:startify_relative_path*
>
    let g:startify_relative_path = 0
<
Show filenames relative to the current working directory instead of as
absolute paths. This only applies to the "files" list, since the "dir" list is
relative by nature.

==============================================================================
AUTOCMD                                                       *startify-autocmd*

In case you want to alter the startify buffer to cause all kinds of mayhem, an
user autocmd is issued. You can hook into it like this:
>
    autocmd User Startified let &l:stl = ' This statusline rocks!'
<
==============================================================================
COMMANDS                                                     *startify-commands*
>
    :SSave [session]
    :SDelete [session]
<
Save or delete a session. If you don't specify a session name, it will prompt
you for one.
>
    :SLoad [session]
<
Load a session. If you don't specify a session name, it will either prompt you
for one (Windows) or load the last used session (Unix).

Providing only a part of the session name works too, if you complete the
argument with either <c-d> or <tab> afterwards.
>
    :SClose
<
Save and close the current session, close all listed buffers, and open the
Startify buffer.
>
    :Startify
<
Open the startify buffer.

==============================================================================
MAPPINGS                                                     *startify-mappings*

Some things are remapped in the startify buffer..
>
    q
<
Close startify. Also quit Vim if it is the only buffer.
>
    e
<
Close startify and create a blank buffer.
>
    i
    <insert>
<
Close startify, create a blank buffer and jump into insert mode right away.
>
    <2-LeftMouse>
<
Use a simple mouse click to open the targeted entry.
>
    [any number that is shown between square brackets]
<
Open the entry with the given number.
>
    b
    s
    v
    t
<
Mark current entry to be opened in either the same window, in a split window,
in a vertical split window or in a new tab.
>
    <cr>
<
Open all marked entries. If nothing was marked beforehand, just open the
current entry.

If you want to use another key instead of <cr>, put this in your vimrc:
>
    autocmd User Startified nmap <buffer> o <plug>(startify-open-buffers)
<
==============================================================================
COLORS                                                         *startify-colors*

You can overwrite the highlight groups used by startify. The plugin defines
these groups:

    Highlight group  |  Description             |  Default
    ------------------------------------------------------------------
                     |                          |
    StartifyBracket  |  [,]                     |  linked to Delimiter
    StartifyFile     |  the actual file         |  <none>
    StartifyFooter   |  the custom footer       |  linked to Normal
    StartifyHeader   |  the custom header       |  linked to Normal
    StartifyNumber   |  the numbers between []  |  linked to Number
    StartifyPath     |  the path to a file      |  <none>
    StartifySection  |  section headers         |  linked to Special
    StartifySelect   |  selected entries        |  linked to Title
    StartifySlash    |  slashes in paths        |  <none>
    StartifySpecial  |  <empty buffer>,<quit>   |  <none>

Example: (my terminal emulator supports 256 colors)
>
    highlight StartifyBracket ctermfg=240
    highlight StartifyFooter  ctermfg=240
    highlight StartifyHeader  ctermfg=114
    highlight StartifyNumber  ctermfg=215
    highlight StartifyPath    ctermfg=245
    highlight StartifySlash   ctermfg=240
    highlight StartifySpecial ctermfg=240
<
==============================================================================
FAQ                                                               *startify-faq*

    |startify-faq-01|  I don't want the start screen to use cursorline!
    |startify-faq-02|  Recent files aren't shown!
    |startify-faq-03|  I have broken colors when using sessions!
    |startify-faq-04|  How to disable common but unimportant files?
    |startify-faq-05|  CtrlP or NERDTree open a split in Startify!
    |startify-faq-06|  How do I get both NERDTree and Startify working at
                     startup?
    |startify-faq-07|  The session autoload feature is not working!
    |startify-faq-08|  How do I center my header/footer?

------------------------------------------------------------------------------
                                                               *startify-faq-01*
I want to use cursorline!~

Startify issues a User event when it's finished. It can be used to set
buffer-local options etc.
>
    autocmd User Startified setlocal cursorline
<
------------------------------------------------------------------------------
                                                               *startify-faq-02*
Recent files aren't shown!~

Perhaps the problem is that the viminfo file..

    - doesn't exist
    - is invalid
    - is empty
    - can't be read (check permissions)

I suggest the following steps:

    1) Create a new directory:
>
        $ mkdir -p ~/.vim/files/info
<
    2) Put this into your vimrc:
>
        set viminfo='100,n$HOME/.vim/files/info/viminfo
<
See |'viminfo'| for information about the second step and what it does
exactly.

------------------------------------------------------------------------------
                                                               *startify-faq-03*
I have broken colors when using sessions!~

Nothing this plugin could do about. Try playing around with 'sessionoptions'.

NOTE: Startify removes 'options' from the session options automatically,
because it's the source of many problems.

Some people swear it works for them with these settings:
>
    set sessionoptions=blank,curdir,folds,help,tabpages,winpos
<
------------------------------------------------------------------------------
                                                               *startify-faq-04*
How to disable common but unimportant files?~

Use |g:startify_skiplist|.

------------------------------------------------------------------------------
                                                               *startify-faq-05*
CtrlP or NERDTree open a split in Startify!~

Put this in your vimrc:
>
    autocmd User Startified setlocal buftype=
<
If you're using CtrlP without NERDTree, there is an even more elegant
solution:
>
    let g:ctrlp_reuse_window = 'startify'
<
------------------------------------------------------------------------------
                                                               *startify-faq-06*
How do I get both NERDTree and Startify working at startup?~

Put this in your vimrc:
>
    autocmd VimEnter *
                \   if !argc()
                \ |   Startify
                \ |   NERDTree
                \ |   wincmd w
                \ | endif
<
------------------------------------------------------------------------------
                                                               *startify-faq-07*
The session autoload feature is not working!~

Do you have NERDTree installed by any chance? If so, try this:
>
    let NERDTreeHijackNetrw = 0
<
------------------------------------------------------------------------------
                                                               *startify-faq-08*
How do I center my header/footer?~

Try something along these lines:
>
    function! s:filter_header(lines) abort
        let longest_line   = max(map(copy(a:lines), 'len(v:val)'))
        let centered_lines = map(copy(a:lines),
            \ 'repeat(" ", (&columns / 2) - (longest_line / 2)) . v:val')
        return centered_lines
    endfunction
    let g:startify_custom_header = s:filter_header(['a', 'bb', 'ccc'])
<
==============================================================================
EXAMPLE                                                       *startify-example*

This is my configuration..
>
    autocmd User Startified setlocal cursorline

    let g:startify_enable_special         = 0
    let g:startify_files_number           = 8
    let g:startify_relative_path          = 1
    let g:startify_change_to_dir          = 1
    let g:startify_session_autoload       = 1
    let g:startify_session_persistence    = 1
    let g:startify_session_delete_buffers = 1

    let g:startify_list_order = [
      \ ['   LRU:'],
      \ 'files',
      \ ['   LRU within this dir:'],
      \ 'dir',
      \ ['   Sessions:'],
      \ 'sessions',
      \ ['   Bookmarks:'],
      \ 'bookmarks',
      \ ]

    let g:startify_skiplist = [
                \ 'COMMIT_EDITMSG',
                \ 'bundle/.*/doc',
                \ '/data/repo/neovim/runtime/doc',
                \ '/Users/mhi/local/vim/share/vim/vim74/doc',
                \ ]

    let g:startify_bookmarks = [
                \ { 'v': '~/.vim/vimrc' },
                \ { 't': '/tmp' },
                \ '/data/vim/golfing',
                \ ]

    let g:startify_custom_footer =
          \ ['', "   Vim is charityware. Please read ':help uganda'.", '']

    let g:startify_custom_header =
          \ map(split(system('tips | cowsay -f apt'), '\n'), '"   ". v:val') + ['']

    hi StartifyBracket ctermfg=240
    hi StartifyFile    ctermfg=147
    hi StartifyFooter  ctermfg=240
    hi StartifyHeader  ctermfg=114
    hi StartifyNumber  ctermfg=215
    hi StartifyPath    ctermfg=245
    hi StartifySlash   ctermfg=240
    hi StartifySpecial ctermfg=240
<
==============================================================================
vim: tw=78