diff --git a/doc/startify.txt b/doc/startify.txt index 2eea369..d60c9ce 100644 --- a/doc/startify.txt +++ b/doc/startify.txt @@ -1202,4 +1202,3619 @@ EXAMPLE *startify-example* hi StartifySpecial ctermfg=240 < ============================================================================== -vim: tw=78 +vim: tw=80 ft=help et ts=2 +*startify.txt* The fancy start screen. +*startify* + __ __ ___ + /\ \__ /\ \__ __ /'___\ + ____\ \ ,_\ __ _ __\ \ ,_\/\_\/\ \__/ __ __ + /',__\\ \ \/ /'__`\ /\`'__\ \ \/\/\ \ \ ,__\/\ \/\ \ + /\__, `\\ \ \_/\ \L\.\_\ \ \/ \ \ \_\ \ \ \ \_/\ \ \_\ \ + \/\____/ \ \__\ \__/.\_\\ \_\ \ \__\\ \_\ \_\ \/`____ \ + \/___/ \/__/\/__/\/_/ \/_/ \/__/ \/_/\/_/ `/___/> \ + /\___/ + \/__/ + by Marco Hinz~ +> + 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 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| + MISC ........................................... |startify-misc| + FAQ ............................................ |startify-faq| + EXAMPLE ........................................ |startify-example| + +============================================================================== +INTRO *startify-intro* + +Startify is a plugin that shows recently used files, bookmarks, commands 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 pretty start screen that shows + recently used files (using viminfo/shada) and sessions by default. + + Additionally, you can define bookmarks (thus entries for files) and + commands that always should be available on the start screen. + + You can either navigate to a certain menu entry and hit `` or just + enter the index (the index is whatever is written between the square + brackets on that line). You can even double-click anywhere on the line. + + In addition, `e` creates an empty buffer, `i` creates an empty buffer and + jumps into insert mode, `q` quits either the buffer or, if there is no + other listed buffer left, Vim itself. + + Moreover, you can open multiple buffers at once. 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 ``. + + The uppercase variants of b/s/v/t enable the batchmode which lets you + select any entries without navigating there first. Every following index + will be opened in the currently active mode. E.g. to open the buffers with + the indices 0, 2, and 4, use `B024` instead of `bjjbjjb`. To disable + batchmode, just use the same uppercase key again, or any of the lowercase + variants. + + 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! + +2) The plugin eases the handling of loading and saving sessions by putting + sessions in a central directory. + + :SLoad load a session |startify-:SLoad| + :SSave[!] save a session |startify-:SSave| + :SDelete[!] delete a session |startify-:SDelete| + :SClose close a session |startify-:SClose| + + If ! is given, you won't get prompted. + + It also supports session persistence, so once a session is loaded, it gets + saved automatically when Vim is quit: |g:startify_session_persistence| + +============================================================================== +OPTIONS *startify-options* + +Put these variables into your vimrc. The shown assignments are also the +default values. + + Most used options:~ + |g:startify_bookmarks| + |g:startify_change_to_dir| + |g:startify_change_to_vcs_root| + |g:startify_change_cmd| + |g:startify_custom_header| + |g:startify_enable_special| + |g:startify_list_order| + |g:startify_lists| + |g:startify_skiplist| + |g:startify_update_oldfiles| + + Misc options:~ + |g:startify_commands| + |g:startify_custom_footer| + |g:startify_custom_header_quotes| + |g:startify_custom_indices| + |g:startify_disable_at_vimenter| + |g:startify_enable_unsafe| + |g:startify_files_number| + |g:startify_fortune_use_unicode| + |g:startify_padding_left| + |g:startify_relative_path| + |g:startify_skiplist_server| + |g:startify_use_env| + + Sessions:~ + |g:startify_session_autoload| + |g:startify_session_before_save| + |g:startify_session_delete_buffers| + |g:startify_session_dir| + |g:startify_session_number| + |g:startify_session_persistence| + |g:startify_session_remove_lines| + |g:startify_session_savecmds| + |g:startify_session_savevars| + |g:startify_session_sort| + +------------------------------------------------------------------------------ + *g:startify_session_dir* +> + let g:startify_session_dir = '~/.vim/session' +< +The directory to save/load sessions to/from. + +Defaults:~ + + Nvim: `$XDG_DATA_HOME/nvim/session` (`:echo stdpath('data')`) + Vim (Unix): `$HOME/.vim/session` + Vim (Windows): `$HOME/vimfiles/session` + +------------------------------------------------------------------------------ + *g:startify_list_order* + +This option is DEPRECATED in favor of |g:startify_lists|. + +------------------------------------------------------------------------------ + *g:startify_lists* +> + let g:startify_lists = [ + \ { 'type': 'files', 'header': [' MRU'] }, + \ { 'type': 'dir', 'header': [' MRU '. getcwd()] }, + \ { 'type': 'sessions', 'header': [' Sessions'] }, + \ { 'type': 'bookmarks', 'header': [' Bookmarks'] }, + \ { 'type': 'commands', 'header': [' Commands'] }, + \ ] +< +Startify displays lists. Each list consists of a `type` and optionally a `header` +and custom `indices`. + +The 'type' is either a string of a built-in type or a |Funcref|. + +The 'header' is a list of strings, whereas each string will be put on its own +line in the header. + +The 'indices' is a list of strings, which act as indices for the current list. +Opposed to the global |g:startify_custom_indices|, this is limited to the +current list. + +Built-in types:~ + +'files' + + This lists the most recently used files using viminfo. The number of files + is limited by |g:startify_files_number|. + +'dir' + + This lists the files from the current directory sorted by modification + time. The number of files is limited by |g:startify_files_number|. + +'bookmarks' + + This lists bookmarks, thus hardcoded files or directories that will always + be shown. Have a look at |g:startify_bookmarks|. + +'sessions' + + This lists all the sessions saved in the directory |g:startify_session_dir|. + +'commands' + + This lists commands defined in |g:startify_commands|. + +Funcref type:~ + +The referenced function must return a list of dictionaries. Each dictionary +is an entry that consists of these keys: + + 'line' The text to display for this entry. (required) + + 'cmd' The Vim command to execute when the entry gets chosen. + (required unless 'path' is given) + + 'path' Points to a file. This way you can even use the standard markers + like `s` or `v` etc. to open multiple entries at once. + (required unless 'cmd' is given) + +Example #1:~ +> + function s:foobar() + return [ + \ { 'line': 'foo', 'cmd': 'echo "FOO!"' }, + \ { 'line': 'bar', 'cmd': 'echo "BAR!"' }, + \ ] + endfunction + + let g:startify_lists = [ + \ { 'type': 'files', 'header': [' MRU:'] }, + \ { 'type': function('s:foobar'), 'header': ['foo', ' and', ' bar'] }, + \ ] +< +Example #2:~ + +This more practical example assumes a git repo at ~/repo and vim-fugitive +installed (for `:Git`). +> + function! s:list_commits() + let git = 'git -C ~/repo' + let commits = systemlist(git .' log --oneline | head -n10') + let git = 'G'. git[1:] + return map(commits, '{"line": matchstr(v:val, "\\s\\zs.*"), "cmd": "'. git .' show ". matchstr(v:val, "^\\x\\+") }') + endfunction + + let g:startify_lists = [ + \ { 'header': [' MRU'], 'type': 'files' }, + \ { 'header': [' MRU '. getcwd()], 'type': 'dir' }, + \ { 'header': [' Sessions'], 'type': 'sessions' }, + \ { 'header': [' Commits'], 'type': function('s:list_commits') }, + \ ] +< +NOTE: Headers are context-sensitive: If the list for a type is empty, the +header won't be shown. + +NOTE: Headers use the StartifySection highlight group. See |startify-colors|. + +------------------------------------------------------------------------------ + *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 is the path. + +Example: +> + let g:startify_bookmarks = [ {'c': '~/.vimrc'}, '~/.zshrc' ] +< +NOTE: Avoid using keys from |startify-mappings| if providing custom indices. + +------------------------------------------------------------------------------ + *g:startify_commands* +> + let g:startify_commands = [] +< +A list of commands to execute on selection. Leading colons are optional. It +supports optional custom indices and/or command descriptions. + +Example: +> + let g:startify_commands = [ + \ ':help reference', + \ ['Vim Reference', 'h ref'], + \ {'h': 'h ref'}, + \ {'m': ['My magical function', 'call Magic()']}, + \ ] +< +NOTE: Avoid using keys from |startify-mappings| if providing custom indices. + +------------------------------------------------------------------------------ + *g:startify_files_number* +> + let g:startify_files_number = 10 +< +The number of files to list. + +------------------------------------------------------------------------------ + *g:startify_update_oldfiles* +> + let g:startify_update_oldfiles = 0 +< +Usually |v:oldfiles| only gets updated when Vim exits. Using this option updates +it on-the-fly, so that :Startify is always up-to-date. + +------------------------------------------------------------------------------ + *g:startify_session_autoload* +> + let g:startify_session_autoload = 0 +< +If this option is enabled and you start 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. + +The same happens when you |:cd| to a directory that contains a `Session.vim` +and execute |:Startify|. + +It also works if you open a bookmarked directory. See |g:startify_bookmarks|. + +This is great way to create a portable project folder! + +NOTE: This option is affected by |g:startify_session_delete_buffers|. + +------------------------------------------------------------------------------ + *g:startify_session_before_save* +> + let g:startify_session_before_save = [] +< +This is a list of commands to be executed before saving a session. + +Example: +> + let g:startify_session_before_save = [ 'silent! tabdo NERDTreeClose' ] +< +------------------------------------------------------------------------------ + *g:startify_session_persistence* +> + let g:startify_session_persistence = 0 +< +Automatically update sessions in two cases: + + - Before leaving Vim + - 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 = 1 +< +Delete all buffers when loading or closing a session: + + - When using |startify-:SLoad|. + - When using |startify-:SClose|. + - When using |g:startify_session_autoload|. + - When choosing a session from the Startify buffer. + +NOTE: Buffers with unsaved changes are silently ignored. + +------------------------------------------------------------------------------ + *g:startify_change_to_dir* +> + let g:startify_change_to_dir = 1 +< +When opening a file or bookmark, change to its directory. + +You want to disable this, if you're using |'autochdir'| as well. + +NOTE: It defaults to 1, because that was already the behaviour at the time +this option was introduced. + +------------------------------------------------------------------------------ + *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_change_cmd* +> + let g:startify_change_cmd = 'lcd' +< +The default command for switching directories. Valid values: + + 'cd' (|:cd|) + 'lcd' (|:lcd|) + 'tcd' (|:tcd|) + +Affects |g:startify_change_to_dir| and |g:startify_change_to_vcs_root|. + +------------------------------------------------------------------------------ + *g:startify_skiplist* +> + let g:startify_skiplist = [] +< +A list of Vim regular expressions that is used to filter recently used files. +See |pattern.txt| for what patterns can be used. + +The following patterns are filtered by default: + + 'runtime/doc/.*\.txt$' + 'bundle/.*/doc/.*\.txt$' + 'plugged/.*/doc/.*\.txt$' + '/.git/' + 'fugitiveblame$' + escape(fnamemodify(resolve($VIMRUNTIME), ':p'), '\') .'doc/.*\.txt$' + +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: |/\~|. + +NOTE: When using backslashes as path separators, escape them. Otherwise using +"C:\this\vim\path\is\problematic" would not match what you would expect, since +|/\v| is a pattern, too. + +Example: +> + let g:startify_skiplist = [ + \ '\.vimgolf', + \ '^/tmp', + \ '/project/.*/documentation', + \ escape(fnamemodify($HOME, ':p'), '\') .'mysecret.txt', + \ ] +< +------------------------------------------------------------------------------ + *g:startify_fortune_use_unicode* +> + let g:startify_fortune_use_unicode = 0 +< +By default, the fortune header uses ASCII characters, because they work for +everyone. If you set this option to 1 and your 'encoding' is "utf-8", Unicode +box-drawing characters will be used instead. + +This is not the default, because users of East Asian languages often set +'ambiwidth' to "double" or make their terminal emulator treat characters of +ambiguous width as double width. Both would make the drawn box look funny. + +For more information: http://unicode.org/reports/tr11 + +------------------------------------------------------------------------------ + *g:startify_padding_left* +> + let g:startify_padding_left = 3 +< +The number of spaces used for left padding. + +------------------------------------------------------------------------------ + *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 and . +------------------------------------------------------------------------------ + *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_session_number* +> + let g:startify_session_number = 999 +< +The maximum number of sessions to display. Makes the most sense together with +|g:startify_session_sort|. + +------------------------------------------------------------------------------ + *g:startify_session_sort* +> + let g:startify_session_sort = 0 +< +Sort sessions by modification time (when the session files were written) +rather than alphabetically. + +------------------------------------------------------------------------------ + *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! + Avoid using keys from |startify-mappings|. + +------------------------------------------------------------------------------ + *g:startify_custom_header* +> + let g:startify_custom_header = 'startify#pad(startify#fortune#cowsay())' +< +Define your own header. + +This option takes a `list of strings`, whereas each string will be put on its +own line. If it is a simple `string`, it should evaluate to a list of strings. + +Helper functions:~ + + startify#fortune#quote() random quote + startify#fortune#boxed(...) random quote in a box + startify#fortune#cowsay(...) random quote in a box + cow + +The last two functions optionally take a quote in the list of strings format. +They also return a list of strings, suitable for this option. + + startify#pad([strings]) pad strings in list according to + |g:startify_padding_left| or the default of 3 + startify#center([strings]) center list of strings without removing + its strings indentations + +Example #1:~ +> + let g:startify_custom_header = [ + \ ' ________ __ __ ', + \ ' __ /\_____ \/\ \\ \ ', + \ ' __ __ /\_\ ___ ___ \/___//''/''\ \ \\ \ ', + \ ' /\ \/\ \\/\ \ /'' __` __`\ /'' /'' \ \ \\ \_ ', + \ ' \ \ \_/ |\ \ \/\ \/\ \/\ \ /'' /''__ \ \__ ,__\', + \ ' \ \___/ \ \_\ \_\ \_\ \_\ /\_/ /\_\ \/_/\_\_/ ', + \ ' \/__/ \/_/\/_/\/_/\/_/ \// \/_/ \/_/ ', + \ ] +< +Example #2:~ +> + let g:startify_custom_header = + \ startify#pad(split(system('fortune | cowsay'), '\n')) +< +Example #3:~ + +Let's assume you like the default boxed random quote, but not the ASCII art +cow. You'd rather have another small ASCII art come before the quote. No +problem! +> + let g:ascii = [ + \ ' __', + \ '.--.--.|__|.--------.', + \ '| | || || |', + \ ' \___/ |__||__|__|__|', + \ '' + \] + let g:startify_custom_header = g:ascii + startify#fortune#boxed() +< +Looks great! But it's not on the same column as the indices below which makes +it look awkward. Let's indent the header by 3 spaces: +> + let g:startify_custom_header = + \ startify#pad(g:ascii + startify#fortune#boxed()) +< +Ah, much better! There's only one issue left. If you set +g:startify_custom_header this way, it will only be done once. Hence spamming +:Startify will always show the same quote. + +If you provide a string to it instead, Startify will evaluate it every time +:Startify is run: +> + let g:startify_custom_header = + \ 'startify#pad(g:ascii + startify#fortune#boxed())' +< +Happy customizing! + +Also have a look at |startify-faq-08|. + +------------------------------------------------------------------------------ + *g:startify_custom_header_quotes* + +If you don't set |g:startify_custom_header|, the internal cowsay implementation +with predefined random quotes will be used. + +To use your own quotes, set this option to a list of quotes. Each quote is +either another list or a |Funcref| (see |expr-lambda|) that returns a list. + +Each element of the inner lists is put on an own line in the custom header. +> + let g:startify_custom_header_quotes = [ + \ ['quote #1'], + \ ['quote #2', 'using', 'three lines'], + \ {-> systemlist('echo quote #3')} + \ ] +< +If you want the predefined quotes as well, use this: +> + let g:startify_custom_header_quotes = + \ startify#fortune#predefined_quotes() + [['quote 1', 'quote 2']] +< +------------------------------------------------------------------------------ + *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 +< +If the file is in or below the current working directory, use a relative path. +Otherwise an absolute path is used. The latter prevents hard to grasp entries +like `../../../../../foo`. + +NOTE: This only applies to the "files" list, since the "dir" list is +relative by nature. + +----------------------------------------------------------------------------- + *g:startify_use_env* +> + let g:startify_use_env = 0 +< +Show environment variables in path, if their name is shorter than their value. +See |startify-colors| for highlighting them. + +$PWD and $OLDPWD are ignored. + +============================================================================== +AUTOCMD *startify-autocmd* + +In certain situations Startify emits events which can be hooked into via +|autocmd|s. Those can be used for further customization. + +StartifyReady~ + + When the Startify buffer is ready. + +StartifyBufferOpened~ + + For each buffer that got opened by Startify. When you open multiple files at + once (see |startify-usage|), this event fires multiple times as well. + +StartifyAllBuffersOpened~ + + No matter how many buffers you open, this event fires only once after the + last buffer was opened. + +Example: +> + autocmd User StartifyReady let &l:stl = ' This statusline rocks!' +< +Or use it to disable single mappings: |startify-faq-16|. + +NOTE: Autocmds don't nest by default. If you use any command that triggers new +events, be sure to add "nested": |autocmd-nested|. + +============================================================================== +COMMANDS *startify-commands* + *startify-:Startify* +> + :Startify +< +Open the startify buffer. + *startify-:SSave* + *startify-:SDelete* +> + :SSave[!] [session] + :SDelete[!] [session] +< +Save or delete a session. If you don't specify a session name, it will prompt +you for one. + +Use `:SSave!` or `:SDelete!` to always overwrite or delete an existing session. + + *startify-:SLoad* +> + :SLoad[!] [session] +< +Load a session. If you don't specify a session name, it will prompt you for +one. + +If the `!` is given, it tries to source the last used session (only Unix). + +Providing only a part of the session name works too, if you complete the +argument with either or afterwards. + +NOTE: This command is affected by |g:startify_session_delete_buffers|. + + *startify-:SClose* +> + :SClose +< +Save and close the current session, close all listed buffers, and open the +Startify buffer. + +NOTE: This command is affected by |g:startify_session_delete_buffers|. + +============================================================================== +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 + +< +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. +> + +< +Open all marked entries. If nothing was marked beforehand, just open the +current entry. + +If you want to use another key instead of , put this in your vimrc: +> + autocmd User Startified nmap o (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 | linked to Identifier + StartifyFooter | the custom footer | linked to Title + StartifyHeader | the custom header | linked to Title + StartifyNumber | the numbers between [] | linked to Number + StartifyPath | the path to a file | linked to Directory + StartifySection | section headers | linked to Statement + StartifySelect | selected entries | linked to Title + StartifySlash | slashes in paths | linked to Delimiter + StartifySpecial | , | linked to Comment + StartifyVar | environment variables | linked to StartifyPath + +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 +< +============================================================================== +MISC *startify-misc* + +Changing the entry format:~ + +You can create a function `StartifyEntryFormat()` which returns a string that +gets evaluated in Startify. In that string, `entry_path` and `absolute_path` +will be replaced by their respective values. + +`absolute_path` is self-explaining and `entry_path` is the same path but +potentially shortened, depending on options like |g:startify_relative_path|. + +Let us assume you have vim-devicons installed. That plugin has a function +`WebDevIconsGetFileTypeSymbol()` which returns an icon depending on the given +file. Prepend the logo to each Startify entry by putting this in your vimrc: +> + function! StartifyEntryFormat() + return 'WebDevIconsGetFileTypeSymbol(absolute_path) ." ". entry_path' + endfunction +< +============================================================================== +FAQ *startify-faq* + + |startify-faq-01| I want 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| Why is the Startify buffer not using buftype=nofile? + |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-09| tmux-resurrect? + |startify-faq-10| Temporarily skip Startify at start? + |startify-faq-11| How to use the output of a command as header? + |startify-faq-12| There is an empty window with vim-plug! + |startify-faq-13| How to disable random quotes header? + |startify-faq-14| NERDTree with NERDTreeTabs does not work in gvim! + |startify-faq-15| Startify is cluttered with help files! + |startify-faq-16| How to disable single mappings? + |startify-faq-17| Run Startify for each new tab! + |startify-faq-18| Files from remote file system slow down startup! + +------------------------------------------------------------------------------ + *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* +Why is the Startify buffer not using buftype=nofile?~ + +Did you accidentally use |:write| in the Startify buffer and it was saved to +an actual file on disk? It's because buftype=nofile is not used. + +This is done to improve compatibility with other plugins. When buftype=nofile +was set, plugins like CtrlP or NERDTree would open splits instead of reusing +the window showing the Startify buffer. + +If you understand this but want it anyway, put this in your vimrc: +> + autocmd User Startified setlocal buftype=nofile +< +------------------------------------------------------------------------------ + *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?~ +> + let g:startify_custom_header = + \ 'startify#center(startify#fortune#cowsay())' +< +------------------------------------------------------------------------------ + *startify-faq-09* +tmux-resurrect?~ + +If you use tmux-resurrect to restore your tmux environment, you can use :SLoad +to load your last used session right away: +> + set -g @resurrect-processes '"vim->vim +SLoad"' +< +------------------------------------------------------------------------------ + *startify-faq-10* +Temporarily skip Startify at start?~ + +In some cases you might need to skip Startify at start. E.g. +> + vim +VimwikiMakeDiaryNote +< +Startify would interfere in this case. A simple way to avoid that would be: +> + vim --cmd 'let g:startify_disable_at_vimenter = 1' +VimwikiMakeDiaryNote +< +------------------------------------------------------------------------------ + *startify-faq-11* +How to use the output of a command as header?~ +> + redir => test + silent echo 'one' + silent echo 'two' + silent echo 'three' + redir END + + let g:startify_custom_header = + \ map(split(test), 'repeat(" ", 10) . v:val') +< +|:redir| puts a string into 'test'. Then we turn it into a list of strings. +Then we shift each string to the right by 10 spaces. Afterwards we add an +empty string to the list, which results in an empty line in the header. + +------------------------------------------------------------------------------ + *startify-faq-12* +There is an empty window with vim-plug!~ + +After start there might be only the Startify buffer which is marked as +|unlisted-buffer|. The problem arises if you use :PlugUpdate followed by 'D' +to see the changes. An empty window! + +The actual problem is that Vim won't close the last listed buffer. Try this: +> + $ vim -u NONE -N + :set nobuflisted + :new + :bd +< +It won't close the buffer and therefore the window. This also happens in +vim-plug. Note that this is no bug in neither plugin, it's a Vim weirdness. + +Workaround #1:~ +> + autocmd User Startified setlocal buflisted +< +In some cases this could break other plugins at start (I look at you +NERDTree), but works well most of the time. + +Workaround #2:~ +> + let g:plug_window = 'enew' " or maybe 'tabnew' +< +This will open the plug buffer in the current window instead of creating a new +window on the left side. Mind that this will also close the Startify buffer +since it will be hidden. + +------------------------------------------------------------------------------ + *startify-faq-13* +How to disable random quotes header?~ +> + let g:startify_custom_header = [] +< +See |g:startify_custom_header|. + +------------------------------------------------------------------------------ + *startify-faq-14* +NERDTree with NERDTreeTabs does not work in gvim!~ + +Mind that `https://github.com/jistr/vim-nerdtree-tabs` is no longer maintained +and has quite some issues. + +Anyway, this particular issue can be resolved in different ways. See: + + https://github.com/mhinz/vim-startify/issues/24 + +------------------------------------------------------------------------------ + *startify-faq-15* +Startify is cluttered with help files!~ + +Every time you use |:h|, you open a file from the Vim runtime directory or of +an installed plugin. By default, Startify detects these files and skips them. + +This works for most use cases, but not for all. + +If the default fails for you and the Startify buffer is cluttered with help +files, add that path to the skiplist yourself: |g:startify_skiplist|. + +------------------------------------------------------------------------------ + *startify-faq-16* +How to disable single mappings?~ + +Use |startify-autocmd|: +> + autocmd User Startified for key in ['b','s','t','v'] | + \ execute 'nunmap ' key | endfor +< +------------------------------------------------------------------------------ + *startify-faq-17* +Run Startify for each new tab!~ +> + if has('nvim') + autocmd TabNewEntered * Startify + else + autocmd BufWinEnter * + \ if !exists('t:startify_new_tab') + \ && empty(expand('%')) + \ && empty(&l:buftype) + \ && &l:modifiable | + \ let t:startify_new_tab = 1 | + \ Startify | + \ endif + endif +< +NOTE: I do not recommend this. It can lead to all kinds of issues, so you +should know exactly what the above code does. E.g. any plugin using |:tabnew| +is probably expecting an empty buffer afterwards, but it won't be empty, it +will be filled with the Startify buffer and fail. I suggest mapping +`:Startify` to something convenient instead. + +------------------------------------------------------------------------------ + *startify-faq-18* +Files from remote file system slow down startup!~ + +I/O actions like resolving symbolic links or checking if a file is readable +can be very slow on some remote file systems (Samba, NFS, FUSE, etc.) Even +more so when done for many files. + +In that case it is often better to add the mount point of the remote file +system to |g:startify_skiplist|: +> + let g:startify_skiplist = ['^/mnt/nfs'] +< +============================================================================== +EXAMPLE *startify-example* +> + 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_update_oldfiles = 1 + let g:startify_session_autoload = 1 + let g:startify_session_persistence = 1 + + 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 = [ + \ { 'c': '~/.vim/vimrc' }, + \ '~/golfing', + \ ] + + let g:startify_custom_header = + \ startify#fortune#cowsay('', '═','║','╔','╗','╝','╚') + + let g:startify_custom_footer = + \ ['', " Vim is charityware. Please read ':help uganda'.", ''] + + 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=80 ft=help noet ts=8 +*startify.txt* The fancy start screen. +*startify* + __ __ ___ + /\ \__ /\ \__ __ /'___\ + ____\ \ ,_\ __ _ __\ \ ,_\/\_\/\ \__/ __ __ + /',__\\ \ \/ /'__`\ /\`'__\ \ \/\/\ \ \ ,__\/\ \/\ \ + /\__, `\\ \ \_/\ \L\.\_\ \ \/ \ \ \_\ \ \ \ \_/\ \ \_\ \ + \/\____/ \ \__\ \__/.\_\\ \_\ \ \__\\ \_\ \_\ \/`____ \ + \/___/ \/__/\/__/\/_/ \/_/ \/__/ \/_/\/_/ `/___/> \ + /\___/ + \/__/ + by Marco Hinz~ +> + 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 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| + MISC ........................................... |startify-misc| + FAQ ............................................ |startify-faq| + EXAMPLE ........................................ |startify-example| + +============================================================================== +INTRO *startify-intro* + +Startify is a plugin that shows recently used files, bookmarks, commands 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 pretty start screen that shows + recently used files (using viminfo/shada) and sessions by default. + + Additionally, you can define bookmarks (thus entries for files) and + commands that always should be available on the start screen. + + You can either navigate to a certain menu entry and hit `` or just + enter the index (the index is whatever is written between the square + brackets on that line). You can even double-click anywhere on the line. + + In addition, `e` creates an empty buffer, `i` creates an empty buffer and + jumps into insert mode, `q` quits either the buffer or, if there is no + other listed buffer left, Vim itself. + + Moreover, you can open multiple buffers at once. 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 ``. + + The uppercase variants of b/s/v/t enable the batchmode which lets you + select any entries without navigating there first. Every following index + will be opened in the currently active mode. E.g. to open the buffers with + the indices 0, 2, and 4, use `B024` instead of `bjjbjjb`. To disable + batchmode, just use the same uppercase key again, or any of the lowercase + variants. + + 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! + +2) The plugin eases the handling of loading and saving sessions by putting + sessions in a central directory. + + :SLoad load a session |startify-:SLoad| + :SSave[!] save a session |startify-:SSave| + :SDelete[!] delete a session |startify-:SDelete| + :SClose close a session |startify-:SClose| + + If ! is given, you won't get prompted. + + It also supports session persistence, so once a session is loaded, it gets + saved automatically when Vim is quit: |g:startify_session_persistence| + +============================================================================== +OPTIONS *startify-options* + +Put these variables into your vimrc. The shown assignments are also the +default values. + + Most used options:~ + |g:startify_bookmarks| + |g:startify_change_to_dir| + |g:startify_change_to_vcs_root| + |g:startify_change_cmd| + |g:startify_custom_header| + |g:startify_enable_special| + |g:startify_list_order| + |g:startify_lists| + |g:startify_skiplist| + |g:startify_update_oldfiles| + + Misc options:~ + |g:startify_commands| + |g:startify_custom_footer| + |g:startify_custom_header_quotes| + |g:startify_custom_indices| + |g:startify_disable_at_vimenter| + |g:startify_enable_unsafe| + |g:startify_files_number| + |g:startify_fortune_use_unicode| + |g:startify_padding_left| + |g:startify_relative_path| + |g:startify_skiplist_server| + |g:startify_use_env| + + Sessions:~ + |g:startify_session_autoload| + |g:startify_session_before_save| + |g:startify_session_delete_buffers| + |g:startify_session_dir| + |g:startify_session_number| + |g:startify_session_persistence| + |g:startify_session_remove_lines| + |g:startify_session_savecmds| + |g:startify_session_savevars| + |g:startify_session_sort| + +------------------------------------------------------------------------------ + *g:startify_session_dir* +> + let g:startify_session_dir = '~/.vim/session' +< +The directory to save/load sessions to/from. + +Defaults:~ + + Nvim: `$XDG_DATA_HOME/nvim/session` (`:echo stdpath('data')`) + Vim (Unix): `$HOME/.vim/session` + Vim (Windows): `$HOME/vimfiles/session` + +------------------------------------------------------------------------------ + *g:startify_list_order* + +This option is DEPRECATED in favor of |g:startify_lists|. + +------------------------------------------------------------------------------ + *g:startify_lists* +> + let g:startify_lists = [ + \ { 'type': 'files', 'header': [' MRU'] }, + \ { 'type': 'dir', 'header': [' MRU '. getcwd()] }, + \ { 'type': 'sessions', 'header': [' Sessions'] }, + \ { 'type': 'bookmarks', 'header': [' Bookmarks'] }, + \ { 'type': 'commands', 'header': [' Commands'] }, + \ ] +< +Startify displays lists. Each list consists of a `type` and optionally a `header` +and custom `indices`. + +The 'type' is either a string of a built-in type or a |Funcref|. + +The 'header' is a list of strings, whereas each string will be put on its own +line in the header. + +The 'indices' is a list of strings, which act as indices for the current list. +Opposed to the global |g:startify_custom_indices|, this is limited to the +current list. + +Built-in types:~ + +'files' + + This lists the most recently used files using viminfo. The number of files + is limited by |g:startify_files_number|. + +'dir' + + This lists the files from the current directory sorted by modification + time. The number of files is limited by |g:startify_files_number|. + +'bookmarks' + + This lists bookmarks, thus hardcoded files or directories that will always + be shown. Have a look at |g:startify_bookmarks|. + +'sessions' + + This lists all the sessions saved in the directory |g:startify_session_dir|. + +'commands' + + This lists commands defined in |g:startify_commands|. + +Funcref type:~ + +The referenced function must return a list of dictionaries. Each dictionary +is an entry that consists of these keys: + + 'line' The text to display for this entry. (required) + + 'cmd' The Vim command to execute when the entry gets chosen. + (required unless 'path' is given) + + 'path' Points to a file. This way you can even use the standard markers + like `s` or `v` etc. to open multiple entries at once. + (required unless 'cmd' is given) + +Example #1:~ +> + function s:foobar() + return [ + \ { 'line': 'foo', 'cmd': 'echo "FOO!"' }, + \ { 'line': 'bar', 'cmd': 'echo "BAR!"' }, + \ ] + endfunction + + let g:startify_lists = [ + \ { 'type': 'files', 'header': [' MRU:'] }, + \ { 'type': function('s:foobar'), 'header': ['foo', ' and', ' bar'] }, + \ ] +< +Example #2:~ + +This more practical example assumes a git repo at ~/repo and vim-fugitive +installed (for `:Git`). +> + function! s:list_commits() + let git = 'git -C ~/repo' + let commits = systemlist(git .' log --oneline | head -n10') + let git = 'G'. git[1:] + return map(commits, '{"line": matchstr(v:val, "\\s\\zs.*"), "cmd": "'. git .' show ". matchstr(v:val, "^\\x\\+") }') + endfunction + + let g:startify_lists = [ + \ { 'header': [' MRU'], 'type': 'files' }, + \ { 'header': [' MRU '. getcwd()], 'type': 'dir' }, + \ { 'header': [' Sessions'], 'type': 'sessions' }, + \ { 'header': [' Commits'], 'type': function('s:list_commits') }, + \ ] +< +NOTE: Headers are context-sensitive: If the list for a type is empty, the +header won't be shown. + +NOTE: Headers use the StartifySection highlight group. See |startify-colors|. + +------------------------------------------------------------------------------ + *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 is the path. + +Example: +> + let g:startify_bookmarks = [ {'c': '~/.vimrc'}, '~/.zshrc' ] +< +NOTE: Avoid using keys from |startify-mappings| if providing custom indices. + +------------------------------------------------------------------------------ + *g:startify_commands* +> + let g:startify_commands = [] +< +A list of commands to execute on selection. Leading colons are optional. It +supports optional custom indices and/or command descriptions. + +Example: +> + let g:startify_commands = [ + \ ':help reference', + \ ['Vim Reference', 'h ref'], + \ {'h': 'h ref'}, + \ {'m': ['My magical function', 'call Magic()']}, + \ ] +< +NOTE: Avoid using keys from |startify-mappings| if providing custom indices. + +------------------------------------------------------------------------------ + *g:startify_files_number* +> + let g:startify_files_number = 10 +< +The number of files to list. + +------------------------------------------------------------------------------ + *g:startify_update_oldfiles* +> + let g:startify_update_oldfiles = 0 +< +Usually |v:oldfiles| only gets updated when Vim exits. Using this option updates +it on-the-fly, so that :Startify is always up-to-date. + +------------------------------------------------------------------------------ + *g:startify_session_autoload* +> + let g:startify_session_autoload = 0 +< +If this option is enabled and you start 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. + +The same happens when you |:cd| to a directory that contains a `Session.vim` +and execute |:Startify|. + +It also works if you open a bookmarked directory. See |g:startify_bookmarks|. + +This is great way to create a portable project folder! + +NOTE: This option is affected by |g:startify_session_delete_buffers|. + +------------------------------------------------------------------------------ + *g:startify_session_before_save* +> + let g:startify_session_before_save = [] +< +This is a list of commands to be executed before saving a session. + +Example: +> + let g:startify_session_before_save = [ 'silent! tabdo NERDTreeClose' ] +< +------------------------------------------------------------------------------ + *g:startify_session_persistence* +> + let g:startify_session_persistence = 0 +< +Automatically update sessions in two cases: + + - Before leaving Vim + - 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 = 1 +< +Delete all buffers when loading or closing a session: + + - When using |startify-:SLoad|. + - When using |startify-:SClose|. + - When using |g:startify_session_autoload|. + - When choosing a session from the Startify buffer. + +NOTE: Buffers with unsaved changes are silently ignored. + +------------------------------------------------------------------------------ + *g:startify_change_to_dir* +> + let g:startify_change_to_dir = 1 +< +When opening a file or bookmark, change to its directory. + +You want to disable this, if you're using |'autochdir'| as well. + +NOTE: It defaults to 1, because that was already the behaviour at the time +this option was introduced. + +------------------------------------------------------------------------------ + *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_change_cmd* +> + let g:startify_change_cmd = 'lcd' +< +The default command for switching directories. Valid values: + + 'cd' (|:cd|) + 'lcd' (|:lcd|) + 'tcd' (|:tcd|) + +Affects |g:startify_change_to_dir| and |g:startify_change_to_vcs_root|. + +------------------------------------------------------------------------------ + *g:startify_skiplist* +> + let g:startify_skiplist = [] +< +A list of Vim regular expressions that is used to filter recently used files. +See |pattern.txt| for what patterns can be used. + +The following patterns are filtered by default: + + 'runtime/doc/.*\.txt$' + 'bundle/.*/doc/.*\.txt$' + 'plugged/.*/doc/.*\.txt$' + '/.git/' + 'fugitiveblame$' + escape(fnamemodify(resolve($VIMRUNTIME), ':p'), '\') .'doc/.*\.txt$' + +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: |/\~|. + +NOTE: When using backslashes as path separators, escape them. Otherwise using +"C:\this\vim\path\is\problematic" would not match what you would expect, since +|/\v| is a pattern, too. + +Example: +> + let g:startify_skiplist = [ + \ '\.vimgolf', + \ '^/tmp', + \ '/project/.*/documentation', + \ escape(fnamemodify($HOME, ':p'), '\') .'mysecret.txt', + \ ] +< +------------------------------------------------------------------------------ + *g:startify_fortune_use_unicode* +> + let g:startify_fortune_use_unicode = 0 +< +By default, the fortune header uses ASCII characters, because they work for +everyone. If you set this option to 1 and your 'encoding' is "utf-8", Unicode +box-drawing characters will be used instead. + +This is not the default, because users of East Asian languages often set +'ambiwidth' to "double" or make their terminal emulator treat characters of +ambiguous width as double width. Both would make the drawn box look funny. + +For more information: http://unicode.org/reports/tr11 + +------------------------------------------------------------------------------ + *g:startify_padding_left* +> + let g:startify_padding_left = 3 +< +The number of spaces used for left padding. + +------------------------------------------------------------------------------ + *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 and . +------------------------------------------------------------------------------ + *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_session_number* +> + let g:startify_session_number = 999 +< +The maximum number of sessions to display. Makes the most sense together with +|g:startify_session_sort|. + +------------------------------------------------------------------------------ + *g:startify_session_sort* +> + let g:startify_session_sort = 0 +< +Sort sessions by modification time (when the session files were written) +rather than alphabetically. + +------------------------------------------------------------------------------ + *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! + Avoid using keys from |startify-mappings|. + +------------------------------------------------------------------------------ + *g:startify_custom_header* +> + let g:startify_custom_header = 'startify#pad(startify#fortune#cowsay())' +< +Define your own header. + +This option takes a `list of strings`, whereas each string will be put on its +own line. If it is a simple `string`, it should evaluate to a list of strings. + +Helper functions:~ + + startify#fortune#quote() random quote + startify#fortune#boxed(...) random quote in a box + startify#fortune#cowsay(...) random quote in a box + cow + +The last two functions optionally take a quote in the list of strings format. +They also return a list of strings, suitable for this option. + + startify#pad([strings]) pad strings in list according to + |g:startify_padding_left| or the default of 3 + startify#center([strings]) center list of strings without removing + its strings indentations + +Example #1:~ +> + let g:startify_custom_header = [ + \ ' ________ __ __ ', + \ ' __ /\_____ \/\ \\ \ ', + \ ' __ __ /\_\ ___ ___ \/___//''/''\ \ \\ \ ', + \ ' /\ \/\ \\/\ \ /'' __` __`\ /'' /'' \ \ \\ \_ ', + \ ' \ \ \_/ |\ \ \/\ \/\ \/\ \ /'' /''__ \ \__ ,__\', + \ ' \ \___/ \ \_\ \_\ \_\ \_\ /\_/ /\_\ \/_/\_\_/ ', + \ ' \/__/ \/_/\/_/\/_/\/_/ \// \/_/ \/_/ ', + \ ] +< +Example #2:~ +> + let g:startify_custom_header = + \ startify#pad(split(system('fortune | cowsay'), '\n')) +< +Example #3:~ + +Let's assume you like the default boxed random quote, but not the ASCII art +cow. You'd rather have another small ASCII art come before the quote. No +problem! +> + let g:ascii = [ + \ ' __', + \ '.--.--.|__|.--------.', + \ '| | || || |', + \ ' \___/ |__||__|__|__|', + \ '' + \] + let g:startify_custom_header = g:ascii + startify#fortune#boxed() +< +Looks great! But it's not on the same column as the indices below which makes +it look awkward. Let's indent the header by 3 spaces: +> + let g:startify_custom_header = + \ startify#pad(g:ascii + startify#fortune#boxed()) +< +Ah, much better! There's only one issue left. If you set +g:startify_custom_header this way, it will only be done once. Hence spamming +:Startify will always show the same quote. + +If you provide a string to it instead, Startify will evaluate it every time +:Startify is run: +> + let g:startify_custom_header = + \ 'startify#pad(g:ascii + startify#fortune#boxed())' +< +Happy customizing! + +Also have a look at |startify-faq-08|. + +------------------------------------------------------------------------------ + *g:startify_custom_header_quotes* + +If you don't set |g:startify_custom_header|, the internal cowsay implementation +with predefined random quotes will be used. + +To use your own quotes, set this option to a list of quotes. Each quote is +either another list or a |Funcref| (see |expr-lambda|) that returns a list. + +Each element of the inner lists is put on an own line in the custom header. +> + let g:startify_custom_header_quotes = [ + \ ['quote #1'], + \ ['quote #2', 'using', 'three lines'], + \ {-> systemlist('echo quote #3')} + \ ] +< +If you want the predefined quotes as well, use this: +> + let g:startify_custom_header_quotes = + \ startify#fortune#predefined_quotes() + [['quote 1', 'quote 2']] +< +------------------------------------------------------------------------------ + *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 +< +If the file is in or below the current working directory, use a relative path. +Otherwise an absolute path is used. The latter prevents hard to grasp entries +like `../../../../../foo`. + +NOTE: This only applies to the "files" list, since the "dir" list is +relative by nature. + +----------------------------------------------------------------------------- + *g:startify_use_env* +> + let g:startify_use_env = 0 +< +Show environment variables in path, if their name is shorter than their value. +See |startify-colors| for highlighting them. + +$PWD and $OLDPWD are ignored. + +============================================================================== +AUTOCMD *startify-autocmd* + +In certain situations Startify emits events which can be hooked into via +|autocmd|s. Those can be used for further customization. + +StartifyReady~ + + When the Startify buffer is ready. + +StartifyBufferOpened~ + + For each buffer that got opened by Startify. When you open multiple files at + once (see |startify-usage|), this event fires multiple times as well. + +StartifyAllBuffersOpened~ + + No matter how many buffers you open, this event fires only once after the + last buffer was opened. + +Example: +> + autocmd User StartifyReady let &l:stl = ' This statusline rocks!' +< +Or use it to disable single mappings: |startify-faq-16|. + +NOTE: Autocmds don't nest by default. If you use any command that triggers new +events, be sure to add "nested": |autocmd-nested|. + +============================================================================== +COMMANDS *startify-commands* + *startify-:Startify* +> + :Startify +< +Open the startify buffer. + *startify-:SSave* + *startify-:SDelete* +> + :SSave[!] [session] + :SDelete[!] [session] +< +Save or delete a session. If you don't specify a session name, it will prompt +you for one. + +Use `:SSave!` or `:SDelete!` to always overwrite or delete an existing session. + + *startify-:SLoad* +> + :SLoad[!] [session] +< +Load a session. If you don't specify a session name, it will prompt you for +one. + +If the `!` is given, it tries to source the last used session (only Unix). + +Providing only a part of the session name works too, if you complete the +argument with either or afterwards. + +NOTE: This command is affected by |g:startify_session_delete_buffers|. + + *startify-:SClose* +> + :SClose +< +Save and close the current session, close all listed buffers, and open the +Startify buffer. + +NOTE: This command is affected by |g:startify_session_delete_buffers|. + +============================================================================== +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 + +< +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. +> + +< +Open all marked entries. If nothing was marked beforehand, just open the +current entry. + +If you want to use another key instead of , put this in your vimrc: +> + autocmd User Startified nmap o (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 | linked to Identifier + StartifyFooter | the custom footer | linked to Title + StartifyHeader | the custom header | linked to Title + StartifyNumber | the numbers between [] | linked to Number + StartifyPath | the path to a file | linked to Directory + StartifySection | section headers | linked to Statement + StartifySelect | selected entries | linked to Title + StartifySlash | slashes in paths | linked to Delimiter + StartifySpecial | , | linked to Comment + StartifyVar | environment variables | linked to StartifyPath + +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 +< +============================================================================== +MISC *startify-misc* + +Changing the entry format:~ + +You can create a function `StartifyEntryFormat()` which returns a string that +gets evaluated in Startify. In that string, `entry_path` and `absolute_path` +will be replaced by their respective values. + +`absolute_path` is self-explaining and `entry_path` is the same path but +potentially shortened, depending on options like |g:startify_relative_path|. + +Let us assume you have vim-devicons installed. That plugin has a function +`WebDevIconsGetFileTypeSymbol()` which returns an icon depending on the given +file. Prepend the logo to each Startify entry by putting this in your vimrc: +> + function! StartifyEntryFormat() + return 'WebDevIconsGetFileTypeSymbol(absolute_path) ." ". entry_path' + endfunction +< +============================================================================== +FAQ *startify-faq* + + |startify-faq-01| I want 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| Why is the Startify buffer not using buftype=nofile? + |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-09| tmux-resurrect? + |startify-faq-10| Temporarily skip Startify at start? + |startify-faq-11| How to use the output of a command as header? + |startify-faq-12| There is an empty window with vim-plug! + |startify-faq-13| How to disable random quotes header? + |startify-faq-14| NERDTree with NERDTreeTabs does not work in gvim! + |startify-faq-15| Startify is cluttered with help files! + |startify-faq-16| How to disable single mappings? + |startify-faq-17| Run Startify for each new tab! + |startify-faq-18| Files from remote file system slow down startup! + +------------------------------------------------------------------------------ + *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* +Why is the Startify buffer not using buftype=nofile?~ + +Did you accidentally use |:write| in the Startify buffer and it was saved to +an actual file on disk? It's because buftype=nofile is not used. + +This is done to improve compatibility with other plugins. When buftype=nofile +was set, plugins like CtrlP or NERDTree would open splits instead of reusing +the window showing the Startify buffer. + +If you understand this but want it anyway, put this in your vimrc: +> + autocmd User Startified setlocal buftype=nofile +< +------------------------------------------------------------------------------ + *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?~ +> + let g:startify_custom_header = + \ 'startify#center(startify#fortune#cowsay())' +< +------------------------------------------------------------------------------ + *startify-faq-09* +tmux-resurrect?~ + +If you use tmux-resurrect to restore your tmux environment, you can use :SLoad +to load your last used session right away: +> + set -g @resurrect-processes '"vim->vim +SLoad"' +< +------------------------------------------------------------------------------ + *startify-faq-10* +Temporarily skip Startify at start?~ + +In some cases you might need to skip Startify at start. E.g. +> + vim +VimwikiMakeDiaryNote +< +Startify would interfere in this case. A simple way to avoid that would be: +> + vim --cmd 'let g:startify_disable_at_vimenter = 1' +VimwikiMakeDiaryNote +< +------------------------------------------------------------------------------ + *startify-faq-11* +How to use the output of a command as header?~ +> + redir => test + silent echo 'one' + silent echo 'two' + silent echo 'three' + redir END + + let g:startify_custom_header = + \ map(split(test), 'repeat(" ", 10) . v:val') +< +|:redir| puts a string into 'test'. Then we turn it into a list of strings. +Then we shift each string to the right by 10 spaces. Afterwards we add an +empty string to the list, which results in an empty line in the header. + +------------------------------------------------------------------------------ + *startify-faq-12* +There is an empty window with vim-plug!~ + +After start there might be only the Startify buffer which is marked as +|unlisted-buffer|. The problem arises if you use :PlugUpdate followed by 'D' +to see the changes. An empty window! + +The actual problem is that Vim won't close the last listed buffer. Try this: +> + $ vim -u NONE -N + :set nobuflisted + :new + :bd +< +It won't close the buffer and therefore the window. This also happens in +vim-plug. Note that this is no bug in neither plugin, it's a Vim weirdness. + +Workaround #1:~ +> + autocmd User Startified setlocal buflisted +< +In some cases this could break other plugins at start (I look at you +NERDTree), but works well most of the time. + +Workaround #2:~ +> + let g:plug_window = 'enew' " or maybe 'tabnew' +< +This will open the plug buffer in the current window instead of creating a new +window on the left side. Mind that this will also close the Startify buffer +since it will be hidden. + +------------------------------------------------------------------------------ + *startify-faq-13* +How to disable random quotes header?~ +> + let g:startify_custom_header = [] +< +See |g:startify_custom_header|. + +------------------------------------------------------------------------------ + *startify-faq-14* +NERDTree with NERDTreeTabs does not work in gvim!~ + +Mind that `https://github.com/jistr/vim-nerdtree-tabs` is no longer maintained +and has quite some issues. + +Anyway, this particular issue can be resolved in different ways. See: + + https://github.com/mhinz/vim-startify/issues/24 + +------------------------------------------------------------------------------ + *startify-faq-15* +Startify is cluttered with help files!~ + +Every time you use |:h|, you open a file from the Vim runtime directory or of +an installed plugin. By default, Startify detects these files and skips them. + +This works for most use cases, but not for all. + +If the default fails for you and the Startify buffer is cluttered with help +files, add that path to the skiplist yourself: |g:startify_skiplist|. + +------------------------------------------------------------------------------ + *startify-faq-16* +How to disable single mappings?~ + +Use |startify-autocmd|: +> + autocmd User Startified for key in ['b','s','t','v'] | + \ execute 'nunmap ' key | endfor +< +------------------------------------------------------------------------------ + *startify-faq-17* +Run Startify for each new tab!~ +> + if has('nvim') + autocmd TabNewEntered * Startify + else + autocmd BufWinEnter * + \ if !exists('t:startify_new_tab') + \ && empty(expand('%')) + \ && empty(&l:buftype) + \ && &l:modifiable | + \ let t:startify_new_tab = 1 | + \ Startify | + \ endif + endif +< +NOTE: I do not recommend this. It can lead to all kinds of issues, so you +should know exactly what the above code does. E.g. any plugin using |:tabnew| +is probably expecting an empty buffer afterwards, but it won't be empty, it +will be filled with the Startify buffer and fail. I suggest mapping +`:Startify` to something convenient instead. + +------------------------------------------------------------------------------ + *startify-faq-18* +Files from remote file system slow down startup!~ + +I/O actions like resolving symbolic links or checking if a file is readable +can be very slow on some remote file systems (Samba, NFS, FUSE, etc.) Even +more so when done for many files. + +In that case it is often better to add the mount point of the remote file +system to |g:startify_skiplist|: +> + let g:startify_skiplist = ['^/mnt/nfs'] +< +============================================================================== +EXAMPLE *startify-example* +> + 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_update_oldfiles = 1 + let g:startify_session_autoload = 1 + let g:startify_session_persistence = 1 + + 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 = [ + \ { 'c': '~/.vim/vimrc' }, + \ '~/golfing', + \ ] + + let g:startify_custom_header = + \ startify#fortune#cowsay('', '═','║','╔','╗','╝','╚') + + let g:startify_custom_footer = + \ ['', " Vim is charityware. Please read ':help uganda'.", ''] + + 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=80 ft=help et ts=2 +*startify.txt* The fancy start screen. +*startify* + __ __ ___ + /\ \__ /\ \__ __ /'___\ + ____\ \ ,_\ __ _ __\ \ ,_\/\_\/\ \__/ __ __ + /',__\\ \ \/ /'__`\ /\`'__\ \ \/\/\ \ \ ,__\/\ \/\ \ + /\__, `\\ \ \_/\ \L\.\_\ \ \/ \ \ \_\ \ \ \ \_/\ \ \_\ \ + \/\____/ \ \__\ \__/.\_\\ \_\ \ \__\\ \_\ \_\ \/`____ \ + \/___/ \/__/\/__/\/_/ \/_/ \/__/ \/_/\/_/ `/___/> \ + /\___/ + \/__/ + by Marco Hinz~ +> + 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 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| + MISC ........................................... |startify-misc| + FAQ ............................................ |startify-faq| + EXAMPLE ........................................ |startify-example| + +============================================================================== +INTRO *startify-intro* + +Startify is a plugin that shows recently used files, bookmarks, commands 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 pretty start screen that shows + recently used files (using viminfo/shada) and sessions by default. + + Additionally, you can define bookmarks (thus entries for files) and + commands that always should be available on the start screen. + + You can either navigate to a certain menu entry and hit `` or just + enter the index (the index is whatever is written between the square + brackets on that line). You can even double-click anywhere on the line. + + In addition, `e` creates an empty buffer, `i` creates an empty buffer and + jumps into insert mode, `q` quits either the buffer or, if there is no + other listed buffer left, Vim itself. + + Moreover, you can open multiple buffers at once. 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 ``. + + The uppercase variants of b/s/v/t enable the batchmode which lets you + select any entries without navigating there first. Every following index + will be opened in the currently active mode. E.g. to open the buffers with + the indices 0, 2, and 4, use `B024` instead of `bjjbjjb`. To disable + batchmode, just use the same uppercase key again, or any of the lowercase + variants. + + 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! + +2) The plugin eases the handling of loading and saving sessions by putting + sessions in a central directory. + + :SLoad load a session |startify-:SLoad| + :SSave[!] save a session |startify-:SSave| + :SDelete[!] delete a session |startify-:SDelete| + :SClose close a session |startify-:SClose| + + If ! is given, you won't get prompted. + + It also supports session persistence, so once a session is loaded, it gets + saved automatically when Vim is quit: |g:startify_session_persistence| + +============================================================================== +OPTIONS *startify-options* + +Put these variables into your vimrc. The shown assignments are also the +default values. + + Most used options:~ + |g:startify_bookmarks| + |g:startify_change_to_dir| + |g:startify_change_to_vcs_root| + |g:startify_change_cmd| + |g:startify_custom_header| + |g:startify_enable_special| + |g:startify_list_order| + |g:startify_lists| + |g:startify_skiplist| + |g:startify_update_oldfiles| + + Misc options:~ + |g:startify_commands| + |g:startify_custom_footer| + |g:startify_custom_header_quotes| + |g:startify_custom_indices| + |g:startify_disable_at_vimenter| + |g:startify_enable_unsafe| + |g:startify_files_number| + |g:startify_fortune_use_unicode| + |g:startify_padding_left| + |g:startify_relative_path| + |g:startify_skiplist_server| + |g:startify_use_env| + + Sessions:~ + |g:startify_session_autoload| + |g:startify_session_before_save| + |g:startify_session_delete_buffers| + |g:startify_session_dir| + |g:startify_session_number| + |g:startify_session_persistence| + |g:startify_session_remove_lines| + |g:startify_session_savecmds| + |g:startify_session_savevars| + |g:startify_session_sort| + +------------------------------------------------------------------------------ + *g:startify_session_dir* +> + let g:startify_session_dir = '~/.vim/session' +< +The directory to save/load sessions to/from. + +Defaults:~ + + Nvim: `$XDG_DATA_HOME/nvim/session` (`:echo stdpath('data')`) + Vim (Unix): `$HOME/.vim/session` + Vim (Windows): `$HOME/vimfiles/session` + +------------------------------------------------------------------------------ + *g:startify_list_order* + +This option is DEPRECATED in favor of |g:startify_lists|. + +------------------------------------------------------------------------------ + *g:startify_lists* +> + let g:startify_lists = [ + \ { 'type': 'files', 'header': [' MRU'] }, + \ { 'type': 'dir', 'header': [' MRU '. getcwd()] }, + \ { 'type': 'sessions', 'header': [' Sessions'] }, + \ { 'type': 'bookmarks', 'header': [' Bookmarks'] }, + \ { 'type': 'commands', 'header': [' Commands'] }, + \ ] +< +Startify displays lists. Each list consists of a `type` and optionally a `header` +and custom `indices`. + +The 'type' is either a string of a built-in type or a |Funcref|. + +The 'header' is a list of strings, whereas each string will be put on its own +line in the header. + +The 'indices' is a list of strings, which act as indices for the current list. +Opposed to the global |g:startify_custom_indices|, this is limited to the +current list. + +Built-in types:~ + +'files' + + This lists the most recently used files using viminfo. The number of files + is limited by |g:startify_files_number|. + +'dir' + + This lists the files from the current directory sorted by modification + time. The number of files is limited by |g:startify_files_number|. + +'bookmarks' + + This lists bookmarks, thus hardcoded files or directories that will always + be shown. Have a look at |g:startify_bookmarks|. + +'sessions' + + This lists all the sessions saved in the directory |g:startify_session_dir|. + +'commands' + + This lists commands defined in |g:startify_commands|. + +Funcref type:~ + +The referenced function must return a list of dictionaries. Each dictionary +is an entry that consists of these keys: + + 'line' The text to display for this entry. (required) + + 'cmd' The Vim command to execute when the entry gets chosen. + (required unless 'path' is given) + + 'path' Points to a file. This way you can even use the standard markers + like `s` or `v` etc. to open multiple entries at once. + (required unless 'cmd' is given) + +Example #1:~ +> + function s:foobar() + return [ + \ { 'line': 'foo', 'cmd': 'echo "FOO!"' }, + \ { 'line': 'bar', 'cmd': 'echo "BAR!"' }, + \ ] + endfunction + + let g:startify_lists = [ + \ { 'type': 'files', 'header': [' MRU:'] }, + \ { 'type': function('s:foobar'), 'header': ['foo', ' and', ' bar'] }, + \ ] +< +Example #2:~ + +This more practical example assumes a git repo at ~/repo and vim-fugitive +installed (for `:Git`). +> + function! s:list_commits() + let git = 'git -C ~/repo' + let commits = systemlist(git .' log --oneline | head -n10') + let git = 'G'. git[1:] + return map(commits, '{"line": matchstr(v:val, "\\s\\zs.*"), "cmd": "'. git .' show ". matchstr(v:val, "^\\x\\+") }') + endfunction + + let g:startify_lists = [ + \ { 'header': [' MRU'], 'type': 'files' }, + \ { 'header': [' MRU '. getcwd()], 'type': 'dir' }, + \ { 'header': [' Sessions'], 'type': 'sessions' }, + \ { 'header': [' Commits'], 'type': function('s:list_commits') }, + \ ] +< +NOTE: Headers are context-sensitive: If the list for a type is empty, the +header won't be shown. + +NOTE: Headers use the StartifySection highlight group. See |startify-colors|. + +------------------------------------------------------------------------------ + *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 is the path. + +Example: +> + let g:startify_bookmarks = [ {'c': '~/.vimrc'}, '~/.zshrc' ] +< +NOTE: Avoid using keys from |startify-mappings| if providing custom indices. + +------------------------------------------------------------------------------ + *g:startify_commands* +> + let g:startify_commands = [] +< +A list of commands to execute on selection. Leading colons are optional. It +supports optional custom indices and/or command descriptions. + +Example: +> + let g:startify_commands = [ + \ ':help reference', + \ ['Vim Reference', 'h ref'], + \ {'h': 'h ref'}, + \ {'m': ['My magical function', 'call Magic()']}, + \ ] +< +NOTE: Avoid using keys from |startify-mappings| if providing custom indices. + +------------------------------------------------------------------------------ + *g:startify_files_number* +> + let g:startify_files_number = 10 +< +The number of files to list. + +------------------------------------------------------------------------------ + *g:startify_update_oldfiles* +> + let g:startify_update_oldfiles = 0 +< +Usually |v:oldfiles| only gets updated when Vim exits. Using this option updates +it on-the-fly, so that :Startify is always up-to-date. + +------------------------------------------------------------------------------ + *g:startify_session_autoload* +> + let g:startify_session_autoload = 0 +< +If this option is enabled and you start 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. + +The same happens when you |:cd| to a directory that contains a `Session.vim` +and execute |:Startify|. + +It also works if you open a bookmarked directory. See |g:startify_bookmarks|. + +This is great way to create a portable project folder! + +NOTE: This option is affected by |g:startify_session_delete_buffers|. + +------------------------------------------------------------------------------ + *g:startify_session_before_save* +> + let g:startify_session_before_save = [] +< +This is a list of commands to be executed before saving a session. + +Example: +> + let g:startify_session_before_save = [ 'silent! tabdo NERDTreeClose' ] +< +------------------------------------------------------------------------------ + *g:startify_session_persistence* +> + let g:startify_session_persistence = 0 +< +Automatically update sessions in two cases: + + - Before leaving Vim + - 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 = 1 +< +Delete all buffers when loading or closing a session: + + - When using |startify-:SLoad|. + - When using |startify-:SClose|. + - When using |g:startify_session_autoload|. + - When choosing a session from the Startify buffer. + +NOTE: Buffers with unsaved changes are silently ignored. + +------------------------------------------------------------------------------ + *g:startify_change_to_dir* +> + let g:startify_change_to_dir = 1 +< +When opening a file or bookmark, change to its directory. + +You want to disable this, if you're using |'autochdir'| as well. + +NOTE: It defaults to 1, because that was already the behaviour at the time +this option was introduced. + +------------------------------------------------------------------------------ + *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_change_cmd* +> + let g:startify_change_cmd = 'lcd' +< +The default command for switching directories. Valid values: + + 'cd' (|:cd|) + 'lcd' (|:lcd|) + 'tcd' (|:tcd|) + +Affects |g:startify_change_to_dir| and |g:startify_change_to_vcs_root|. + +------------------------------------------------------------------------------ + *g:startify_skiplist* +> + let g:startify_skiplist = [] +< +A list of Vim regular expressions that is used to filter recently used files. +See |pattern.txt| for what patterns can be used. + +The following patterns are filtered by default: + + 'runtime/doc/.*\.txt$' + 'bundle/.*/doc/.*\.txt$' + 'plugged/.*/doc/.*\.txt$' + '/.git/' + 'fugitiveblame$' + escape(fnamemodify(resolve($VIMRUNTIME), ':p'), '\') .'doc/.*\.txt$' + +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: |/\~|. + +NOTE: When using backslashes as path separators, escape them. Otherwise using +"C:\this\vim\path\is\problematic" would not match what you would expect, since +|/\v| is a pattern, too. + +Example: +> + let g:startify_skiplist = [ + \ '\.vimgolf', + \ '^/tmp', + \ '/project/.*/documentation', + \ escape(fnamemodify($HOME, ':p'), '\') .'mysecret.txt', + \ ] +< +------------------------------------------------------------------------------ + *g:startify_fortune_use_unicode* +> + let g:startify_fortune_use_unicode = 0 +< +By default, the fortune header uses ASCII characters, because they work for +everyone. If you set this option to 1 and your 'encoding' is "utf-8", Unicode +box-drawing characters will be used instead. + +This is not the default, because users of East Asian languages often set +'ambiwidth' to "double" or make their terminal emulator treat characters of +ambiguous width as double width. Both would make the drawn box look funny. + +For more information: http://unicode.org/reports/tr11 + +------------------------------------------------------------------------------ + *g:startify_padding_left* +> + let g:startify_padding_left = 3 +< +The number of spaces used for left padding. + +------------------------------------------------------------------------------ + *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 and . +------------------------------------------------------------------------------ + *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_session_number* +> + let g:startify_session_number = 999 +< +The maximum number of sessions to display. Makes the most sense together with +|g:startify_session_sort|. + +------------------------------------------------------------------------------ + *g:startify_session_sort* +> + let g:startify_session_sort = 0 +< +Sort sessions by modification time (when the session files were written) +rather than alphabetically. + +------------------------------------------------------------------------------ + *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! + Avoid using keys from |startify-mappings|. + +------------------------------------------------------------------------------ + *g:startify_custom_header* +> + let g:startify_custom_header = 'startify#pad(startify#fortune#cowsay())' +< +Define your own header. + +This option takes a `list of strings`, whereas each string will be put on its +own line. If it is a simple `string`, it should evaluate to a list of strings. + +Helper functions:~ + + startify#fortune#quote() random quote + startify#fortune#boxed(...) random quote in a box + startify#fortune#cowsay(...) random quote in a box + cow + +The last two functions optionally take a quote in the list of strings format. +They also return a list of strings, suitable for this option. + + startify#pad([strings]) pad strings in list according to + |g:startify_padding_left| or the default of 3 + startify#center([strings]) center list of strings without removing + its strings indentations + +Example #1:~ +> + let g:startify_custom_header = [ + \ ' ________ __ __ ', + \ ' __ /\_____ \/\ \\ \ ', + \ ' __ __ /\_\ ___ ___ \/___//''/''\ \ \\ \ ', + \ ' /\ \/\ \\/\ \ /'' __` __`\ /'' /'' \ \ \\ \_ ', + \ ' \ \ \_/ |\ \ \/\ \/\ \/\ \ /'' /''__ \ \__ ,__\', + \ ' \ \___/ \ \_\ \_\ \_\ \_\ /\_/ /\_\ \/_/\_\_/ ', + \ ' \/__/ \/_/\/_/\/_/\/_/ \// \/_/ \/_/ ', + \ ] +< +Example #2:~ +> + let g:startify_custom_header = + \ startify#pad(split(system('fortune | cowsay'), '\n')) +< +Example #3:~ + +Let's assume you like the default boxed random quote, but not the ASCII art +cow. You'd rather have another small ASCII art come before the quote. No +problem! +> + let g:ascii = [ + \ ' __', + \ '.--.--.|__|.--------.', + \ '| | || || |', + \ ' \___/ |__||__|__|__|', + \ '' + \] + let g:startify_custom_header = g:ascii + startify#fortune#boxed() +< +Looks great! But it's not on the same column as the indices below which makes +it look awkward. Let's indent the header by 3 spaces: +> + let g:startify_custom_header = + \ startify#pad(g:ascii + startify#fortune#boxed()) +< +Ah, much better! There's only one issue left. If you set +g:startify_custom_header this way, it will only be done once. Hence spamming +:Startify will always show the same quote. + +If you provide a string to it instead, Startify will evaluate it every time +:Startify is run: +> + let g:startify_custom_header = + \ 'startify#pad(g:ascii + startify#fortune#boxed())' +< +Happy customizing! + +Also have a look at |startify-faq-08|. + +------------------------------------------------------------------------------ + *g:startify_custom_header_quotes* + +If you don't set |g:startify_custom_header|, the internal cowsay implementation +with predefined random quotes will be used. + +To use your own quotes, set this option to a list of quotes. Each quote is +either another list or a |Funcref| (see |expr-lambda|) that returns a list. + +Each element of the inner lists is put on an own line in the custom header. +> + let g:startify_custom_header_quotes = [ + \ ['quote #1'], + \ ['quote #2', 'using', 'three lines'], + \ {-> systemlist('echo quote #3')} + \ ] +< +If you want the predefined quotes as well, use this: +> + let g:startify_custom_header_quotes = + \ startify#fortune#predefined_quotes() + [['quote 1', 'quote 2']] +< +------------------------------------------------------------------------------ + *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 +< +If the file is in or below the current working directory, use a relative path. +Otherwise an absolute path is used. The latter prevents hard to grasp entries +like `../../../../../foo`. + +NOTE: This only applies to the "files" list, since the "dir" list is +relative by nature. + +----------------------------------------------------------------------------- + *g:startify_use_env* +> + let g:startify_use_env = 0 +< +Show environment variables in path, if their name is shorter than their value. +See |startify-colors| for highlighting them. + +$PWD and $OLDPWD are ignored. + +============================================================================== +AUTOCMD *startify-autocmd* + +In certain situations Startify emits events which can be hooked into via +|autocmd|s. Those can be used for further customization. + +StartifyReady~ + + When the Startify buffer is ready. + +StartifyBufferOpened~ + + For each buffer that got opened by Startify. When you open multiple files at + once (see |startify-usage|), this event fires multiple times as well. + +StartifyAllBuffersOpened~ + + No matter how many buffers you open, this event fires only once after the + last buffer was opened. + +Example: +> + autocmd User StartifyReady let &l:stl = ' This statusline rocks!' +< +Or use it to disable single mappings: |startify-faq-16|. + +NOTE: Autocmds don't nest by default. If you use any command that triggers new +events, be sure to add "nested": |autocmd-nested|. + +============================================================================== +COMMANDS *startify-commands* + *startify-:Startify* +> + :Startify +< +Open the startify buffer. + *startify-:SSave* + *startify-:SDelete* +> + :SSave[!] [session] + :SDelete[!] [session] +< +Save or delete a session. If you don't specify a session name, it will prompt +you for one. + +Use `:SSave!` or `:SDelete!` to always overwrite or delete an existing session. + + *startify-:SLoad* +> + :SLoad[!] [session] +< +Load a session. If you don't specify a session name, it will prompt you for +one. + +If the `!` is given, it tries to source the last used session (only Unix). + +Providing only a part of the session name works too, if you complete the +argument with either or afterwards. + +NOTE: This command is affected by |g:startify_session_delete_buffers|. + + *startify-:SClose* +> + :SClose +< +Save and close the current session, close all listed buffers, and open the +Startify buffer. + +NOTE: This command is affected by |g:startify_session_delete_buffers|. + +============================================================================== +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 + +< +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. +> + +< +Open all marked entries. If nothing was marked beforehand, just open the +current entry. + +If you want to use another key instead of , put this in your vimrc: +> + autocmd User Startified nmap o (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 | linked to Identifier + StartifyFooter | the custom footer | linked to Title + StartifyHeader | the custom header | linked to Title + StartifyNumber | the numbers between [] | linked to Number + StartifyPath | the path to a file | linked to Directory + StartifySection | section headers | linked to Statement + StartifySelect | selected entries | linked to Title + StartifySlash | slashes in paths | linked to Delimiter + StartifySpecial | , | linked to Comment + StartifyVar | environment variables | linked to StartifyPath + +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 +< +============================================================================== +MISC *startify-misc* + +Changing the entry format:~ + +You can create a function `StartifyEntryFormat()` which returns a string that +gets evaluated in Startify. In that string, `entry_path` and `absolute_path` +will be replaced by their respective values. + +`absolute_path` is self-explaining and `entry_path` is the same path but +potentially shortened, depending on options like |g:startify_relative_path|. + +Let us assume you have vim-devicons installed. That plugin has a function +`WebDevIconsGetFileTypeSymbol()` which returns an icon depending on the given +file. Prepend the logo to each Startify entry by putting this in your vimrc: +> + function! StartifyEntryFormat() + return 'WebDevIconsGetFileTypeSymbol(absolute_path) ." ". entry_path' + endfunction +< +============================================================================== +FAQ *startify-faq* + + |startify-faq-01| I want 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| Why is the Startify buffer not using buftype=nofile? + |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-09| tmux-resurrect? + |startify-faq-10| Temporarily skip Startify at start? + |startify-faq-11| How to use the output of a command as header? + |startify-faq-12| There is an empty window with vim-plug! + |startify-faq-13| How to disable random quotes header? + |startify-faq-14| NERDTree with NERDTreeTabs does not work in gvim! + |startify-faq-15| Startify is cluttered with help files! + |startify-faq-16| How to disable single mappings? + |startify-faq-17| Run Startify for each new tab! + |startify-faq-18| Files from remote file system slow down startup! + +------------------------------------------------------------------------------ + *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* +Why is the Startify buffer not using buftype=nofile?~ + +Did you accidentally use |:write| in the Startify buffer and it was saved to +an actual file on disk? It's because buftype=nofile is not used. + +This is done to improve compatibility with other plugins. When buftype=nofile +was set, plugins like CtrlP or NERDTree would open splits instead of reusing +the window showing the Startify buffer. + +If you understand this but want it anyway, put this in your vimrc: +> + autocmd User Startified setlocal buftype=nofile +< +------------------------------------------------------------------------------ + *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?~ +> + let g:startify_custom_header = + \ 'startify#center(startify#fortune#cowsay())' +< +------------------------------------------------------------------------------ + *startify-faq-09* +tmux-resurrect?~ + +If you use tmux-resurrect to restore your tmux environment, you can use :SLoad +to load your last used session right away: +> + set -g @resurrect-processes '"vim->vim +SLoad"' +< +------------------------------------------------------------------------------ + *startify-faq-10* +Temporarily skip Startify at start?~ + +In some cases you might need to skip Startify at start. E.g. +> + vim +VimwikiMakeDiaryNote +< +Startify would interfere in this case. A simple way to avoid that would be: +> + vim --cmd 'let g:startify_disable_at_vimenter = 1' +VimwikiMakeDiaryNote +< +------------------------------------------------------------------------------ + *startify-faq-11* +How to use the output of a command as header?~ +> + redir => test + silent echo 'one' + silent echo 'two' + silent echo 'three' + redir END + + let g:startify_custom_header = + \ map(split(test), 'repeat(" ", 10) . v:val') +< +|:redir| puts a string into 'test'. Then we turn it into a list of strings. +Then we shift each string to the right by 10 spaces. Afterwards we add an +empty string to the list, which results in an empty line in the header. + +------------------------------------------------------------------------------ + *startify-faq-12* +There is an empty window with vim-plug!~ + +After start there might be only the Startify buffer which is marked as +|unlisted-buffer|. The problem arises if you use :PlugUpdate followed by 'D' +to see the changes. An empty window! + +The actual problem is that Vim won't close the last listed buffer. Try this: +> + $ vim -u NONE -N + :set nobuflisted + :new + :bd +< +It won't close the buffer and therefore the window. This also happens in +vim-plug. Note that this is no bug in neither plugin, it's a Vim weirdness. + +Workaround #1:~ +> + autocmd User Startified setlocal buflisted +< +In some cases this could break other plugins at start (I look at you +NERDTree), but works well most of the time. + +Workaround #2:~ +> + let g:plug_window = 'enew' " or maybe 'tabnew' +< +This will open the plug buffer in the current window instead of creating a new +window on the left side. Mind that this will also close the Startify buffer +since it will be hidden. + +------------------------------------------------------------------------------ + *startify-faq-13* +How to disable random quotes header?~ +> + let g:startify_custom_header = [] +< +See |g:startify_custom_header|. + +------------------------------------------------------------------------------ + *startify-faq-14* +NERDTree with NERDTreeTabs does not work in gvim!~ + +Mind that `https://github.com/jistr/vim-nerdtree-tabs` is no longer maintained +and has quite some issues. + +Anyway, this particular issue can be resolved in different ways. See: + + https://github.com/mhinz/vim-startify/issues/24 + +------------------------------------------------------------------------------ + *startify-faq-15* +Startify is cluttered with help files!~ + +Every time you use |:h|, you open a file from the Vim runtime directory or of +an installed plugin. By default, Startify detects these files and skips them. + +This works for most use cases, but not for all. + +If the default fails for you and the Startify buffer is cluttered with help +files, add that path to the skiplist yourself: |g:startify_skiplist|. + +------------------------------------------------------------------------------ + *startify-faq-16* +How to disable single mappings?~ + +Use |startify-autocmd|: +> + autocmd User Startified for key in ['b','s','t','v'] | + \ execute 'nunmap ' key | endfor +< +------------------------------------------------------------------------------ + *startify-faq-17* +Run Startify for each new tab!~ +> + if has('nvim') + autocmd TabNewEntered * Startify + else + autocmd BufWinEnter * + \ if !exists('t:startify_new_tab') + \ && empty(expand('%')) + \ && empty(&l:buftype) + \ && &l:modifiable | + \ let t:startify_new_tab = 1 | + \ Startify | + \ endif + endif +< +NOTE: I do not recommend this. It can lead to all kinds of issues, so you +should know exactly what the above code does. E.g. any plugin using |:tabnew| +is probably expecting an empty buffer afterwards, but it won't be empty, it +will be filled with the Startify buffer and fail. I suggest mapping +`:Startify` to something convenient instead. + +------------------------------------------------------------------------------ + *startify-faq-18* +Files from remote file system slow down startup!~ + +I/O actions like resolving symbolic links or checking if a file is readable +can be very slow on some remote file systems (Samba, NFS, FUSE, etc.) Even +more so when done for many files. + +In that case it is often better to add the mount point of the remote file +system to |g:startify_skiplist|: +> + let g:startify_skiplist = ['^/mnt/nfs'] +< +============================================================================== +EXAMPLE *startify-example* +> + 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_update_oldfiles = 1 + let g:startify_session_autoload = 1 + let g:startify_session_persistence = 1 + + 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 = [ + \ { 'c': '~/.vim/vimrc' }, + \ '~/golfing', + \ ] + + let g:startify_custom_header = + \ startify#fortune#cowsay('', '═','║','╔','╗','╝','╚') + + let g:startify_custom_footer = + \ ['', " Vim is charityware. Please read ':help uganda'.", ''] + + 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:ts=8:noet:ft=help: