plugins.startify.settings

The configuration options for startify without the startify_ prefix.

For example, the following settings are equivialent to these :setglobal commands:

  • foo_bar = 1 -> :setglobal startify_foo_bar=1
  • hello = "world" -> :setglobal startify_hello="world"
  • some_toggle = true -> :setglobal startify_some_toggle
  • other_toggle = false -> :setglobal nostartify_other_toggle

Type: attribute set of anything

Default: { }

Example:

{
  change_to_dir = false;
  custom_header = [
    ""
    "     ███╗   ██╗██╗██╗  ██╗██╗   ██╗██╗███╗   ███╗"
    "     ████╗  ██║██║╚██╗██╔╝██║   ██║██║████╗ ████║"
    "     ██╔██╗ ██║██║ ╚███╔╝ ██║   ██║██║██╔████╔██║"
    "     ██║╚██╗██║██║ ██╔██╗ ╚██╗ ██╔╝██║██║╚██╔╝██║"
    "     ██║ ╚████║██║██╔╝ ██╗ ╚████╔╝ ██║██║ ╚═╝ ██║"
    "     ╚═╝  ╚═══╝╚═╝╚═╝  ╚═╝  ╚═══╝  ╚═╝╚═╝     ╚═╝"
  ];
  fortune_use_unicode = true;
}

Declared by:

plugins.startify.settings.enable_special

Show <empty buffer> and <quit>.

Plugin default: true

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.startify.settings.enable_unsafe

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

Plugin default: false

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.startify.settings.bookmarks

A list of files or directories to bookmark. The list can contain two kinds of types. Either a path (str) or an attrs where the key is the custom index and the value is the path.

Plugin default: []

Type: null or (list of (string or raw lua code or (attribute set) or raw lua code))

Default: null

Declared by:

plugins.startify.settings.change_cmd

The default command for switching directories.

Valid values:

  • cd
  • lcd
  • tcd

Affects change_to_dir and change_to_vcs_root.

Plugin default: "lcd"

Type: null or string or raw lua code

Default: null

Declared by:

plugins.startify.settings.change_to_dir

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 true, because that was already the behaviour at the time this option was introduced.

Plugin default: true

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.startify.settings.change_to_vcs_root

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.

Plugin default: false

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.startify.settings.commands

A list of commands to execute on selection. Leading colons are optional. It supports optional custom indices and/or command descriptions.

Example:

  [
    ":help reference"
    ["Vim Reference" "h ref"]
    {h = "h ref";}
    {m = ["My magical function" "call Magic()"];}
  ]

Plugin default: []

Type: null or (list of (string or attribute set of (string or list of string) or list of string or raw lua code))

Default: null

Declared by:

Same as the custom header, but shown at the bottom of the startify buffer.

Type: null or (list of (string or raw lua code)) or raw lua code

Default: null

Declared by:

plugins.startify.settings.custom_header

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.

Example:

  [
    ""
    "     ███╗   ██╗██╗██╗  ██╗██╗   ██╗██╗███╗   ███╗"
    "     ████╗  ██║██║╚██╗██╔╝██║   ██║██║████╗ ████║"
    "     ██╔██╗ ██║██║ ╚███╔╝ ██║   ██║██║██╔████╔██║"
    "     ██║╚██╗██║██║ ██╔██╗ ╚██╗ ██╔╝██║██║╚██╔╝██║"
    "     ██║ ╚████║██║██╔╝ ██╗ ╚████╔╝ ██║██║ ╚═╝ ██║"
    "     ╚═╝  ╚═══╝╚═╝╚═╝  ╚═╝  ╚═══╝  ╚═╝╚═╝     ╚═╝"
  ]

Type: null or (list of (string or raw lua code)) or raw lua code

Default: null

Declared by:

plugins.startify.settings.custom_header_quotes

Example:

  [
    ["quote #1"]
    ["quote #2" "using" "three lines"]
  ]

Plugin default: []

Type: null or (list of ((list of string) or raw lua code))

Default: null

Declared by:

plugins.startify.settings.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:

  ["f" "g" "h"]

Plugin default: []

Type: null or (list of string) or raw lua code

Default: null

Declared by:

plugins.startify.settings.disable_at_vimenter

Don’t run Startify at Vim startup. You can still call it anytime via :Startify.

Plugin default: false

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.startify.settings.files_number

The number of files to list.

Plugin default: 10

Type: null or unsigned integer, meaning >=0, or raw lua code

Default: null

Declared by:

plugins.startify.settings.fortune_use_unicode

By default, the fortune header uses ASCII characters, because they work for everyone. If you set this option to true 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

Plugin default: false

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.startify.settings.lists

Startify displays lists. Each list consists of a type and optionally a header and custom indices.

Default:

  [
    {
      type = "files";
      header = ["   MRU"];
    }
    {
      type = "dir";
      header = [{__raw = "'   MRU' .. vim.loop.cwd()";}];
    }
    {
      type = "sessions";
      header = ["   Sessions"];
    }
    {
      type = "bookmarks";
      header = ["   Bookmarks"];
    }
    {
      type = "commands";
      header = ["   Commands"];
    }
  ]

Type: list of (lua code string or (attribute set of anything))

Default: [ ]

Declared by:

plugins.startify.settings.padding_left

The number of spaces used for left padding.

Plugin default: 3

Type: null or unsigned integer, meaning >=0, or raw lua code

Default: null

Declared by:

plugins.startify.settings.relative_path

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.

Plugin default: false

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.startify.settings.session_autoload

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 the bookmarks option.

This is great way to create a portable project folder!

NOTE: This option is affected by session_delete_buffers.

Plugin default: false

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.startify.settings.session_before_save

This is a list of commands to be executed before saving a session.

Example: ["silent! tabdo NERDTreeClose"]

Plugin default: []

Type: null or (list of (string or raw lua code))

Default: null

Declared by:

plugins.startify.settings.session_delete_buffers

Delete all buffers when loading or closing a session:

  • When using |startify-:SLoad|.
  • When using |startify-:SClose|.
  • When using session_autoload.
  • When choosing a session from the Startify buffer.

NOTE: Buffers with unsaved changes are silently ignored.

Plugin default: true

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.startify.settings.session_dir

The directory to save/load sessions to/from.

Plugin default: "~/.vim/session"

Type: null or string or raw lua code

Default: null

Declared by:

plugins.startify.settings.session_number

The maximum number of sessions to display. Makes the most sense together with session_sort.

Plugin default: 999

Type: null or unsigned integer, meaning >=0, or raw lua code

Default: null

Declared by:

plugins.startify.settings.session_persistence

Automatically update sessions in two cases:

  • Before leaving Vim
  • Before loading a new session via :SLoad

Plugin default: false

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.startify.settings.session_remove_lines

Lines matching any of the patterns in this list, will be removed from the session file.

Example:

  ["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.

Plugin default: []

Type: null or (list of (string or raw lua code))

Default: null

Declared by:

plugins.startify.settings.session_savecmds

Include a list of cmdline commands which Vim will run upon loading the session.

Example:

  [
    "silent !pdfreader ~/latexproject/main.pdf &"
  ]

Plugin default: []

Type: null or (list of (string or raw lua code))

Default: null

Declared by:

plugins.startify.settings.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.

Example:

  [
   "g:startify_session_savevars"
   "g:startify_session_savecmds"
   "g:random_plugin_use_feature"
  ]

Plugin default: []

Type: null or (list of (string or raw lua code))

Default: null

Declared by:

plugins.startify.settings.session_sort

Sort sessions by modification time (when the session files were written) rather than alphabetically.

Plugin default: false

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.startify.settings.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:

  [
   "\.vimgolf"
   "^/tmp"
   "/project/.*/documentation"
  ]

Plugin default: []

Type: null or (list of (string or raw lua code))

Default: null

Declared by:

plugins.startify.settings.skiplist_server

Do not create the startify buffer, if this is a Vim server instance with a name contained in this list.

Example: ["GVIM"]

Plugin default: []

Type: null or (list of (string or raw lua code or raw lua code))

Default: null

Declared by:

plugins.startify.settings.update_oldfiles

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.

Plugin default: false

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.startify.settings.use_env

Show environment variables in path, if their name is shorter than their value. See |startify-colors| for highlighting them.

$PWD and $OLDPWD are ignored.

Plugin default: false

Type: null or boolean or raw lua code

Default: null

Declared by: