Plugin-info file¶

Plugin-info file is a regular JSON file that contains JSON dictionary with the following keys:

Required keys:

repository

Repository description, must not be present in top-level plugin-info file. Contains a dictionary with the following keys:

type

Required. Must contain one of the following strings:

archive: Designates that this dictionary describes an archive downloaded from given URL.
file: Designates that this dictionary describes a plain .vim file.
hg, git, svn, bzr, darcs: Designates that this dictionary describes a repository controlled by the given version control system.
any name starting with _: Reserved for plugin managers. Must not be present in the database.

url: Required. For archive and file repository types it determines URL of the file to download, for various VCS repository types it determines location from where it should clone the repository.

Note

Plugin managers are supposed to use this URL when updating.

revision: Optional if repository type is one of VCS types, must not be present otherwise. Determines revision that should be checked out, may be a branch name.
vim-directory: Describes directory where plugin .vim file(s) should be moved if repository type happens to be file.

unpack-sequence

Required if repository type happens to be archive, optional if it happens to be file and must be absent in other cases. Contains a list of strings which determine the unpack sequence that should be performed by a plugin manager to unpack downloaded archive. If type is file then this list must contain only stream compress formats. Known formats:

Format	Description
`gz`, `xz`, `lzma`, `bz2`	Stream compress formats: gzip, xz, lzma, bzip2.
`tar`	Tape archive (tar) format.
`zip`	Zip archive format.
`rar`	RAR archive format.
`cab`	CAB (CABinet) archive format.
`arj`	ARJ archive format.
`jar`	JAR (Java ARchive) archive format.
`7z`	7z archive format (should not be used for non-.7z archives supported by 7-zip, but not listed here).
`vmb`	Vimball archives.

file-name: Required if repository type happens to be file, optional if it happens to be archive and must be absent in other cases. Contains a string that is the name of the .vim file (when type is file) or downloaded archive name (when type is archive) and must not be used for anything but determining how to name file downloaded from the given URL.

Note

For archived files like pt.vim.gz (repository-type is file) the file-name key is pt.vim.gz, not pt.vim. It is up to the plugin manager to determine what will the name of the file be after unpacking.
strip-components: Optional. Tells plugin manager to strip given number of top-level directories. Only valid for repositories with type archive.

Note

Plugin managers must strip given number of path components when this key is present. They are free to do automatic detection in case it is not present.

name

String, name of the plugin. Value must match plugin directory name.

version: String. In database it is required to be the same as {version} component of release directory and be absent in any other plugin-info files.

Optional keys:

dependencies

Dictionary, description of the dependencies. Must be present in the form dependency_name : dependency_description: dependency_name is a dictionary key, dependency_description is a dictionary. The latter may contain keys listed below:

version

A single string describing allowed dependency versions. String must look like the following:

version :: top_constraints " " version_base
top_constraints :: [<=>]? "=" | [<>]
version_base :: version_component ( "." version_component )*
version_component :: same_as_current | number | any
same_as_current :: "~"
number :: [^.~*] [^.]*
any :: "*"

Absense of this key works like if == * was specified.

Description of the format string:

Versions are supposed to have format like 1.2.3.4. Semantic versioning is preferred, but not forced. In place of numbers any alphanumeric sequence may appear. When comparing versions only the first numeric part at the start of each version component will be taken into account: alpha1 equals zero because a is not a digit, components 123rc and 123rc are considered equal, as well as 1rc2 and 1rc3.

When parsing version any non-alpha-numeric character that is not dot or ~ is stripped out, producing new component: 2014-05-16 is converted into 2014.05.16. This applies both to version key in dependencies dictionary and version key of the actual dependency. Using identical to constraint disables this.
top_constraints specify which versions should be considered to be allowed. Possible variants: < (lesser then), > (greater then), <= (lesser then or equal to), >= (greater then or equal to), = (equal to), == (identical to).

Checked version is considered matched if its first differing component matches given constraint. Missing component is strictly lesser then any other value.

When using “indentical to” constraint corresponding string is always treated as a single component and is matched literally unless it is equal to same_as_current or any.
same_as_current is substituted with value of the component in the same position of the version of the package for which dependencies are defined. any means that version component may have any value, and all of the following components may have any value, including missing. It thus must be the last atom.

All lesser and greater constraint variants automatically receive any as the last component, no matter whether or not it is specified.

“Identical to” top constraint allows either a single component same_as_current or a random string.

Examples (assuming version key is 2.6.10):

Version definition	Matched examples	Not matched examples
`>= 1.2`	1.2, 1.2.5	1.1, 0.1
`> 1.2`	1.2rc1, 1.3	1.1, 1.2
`= 1.2`	1.2, 1foo2	1.2.1, 1.1, 1.3
`= 1.2.*`	1.2, 1.2.3	1.3, 1.1, 1
`= ~.~.*`	2.6, 2.6.5	2.5, 2
`== ~`	2.6.10	2f6f10, 2.6.10.1
`== 1alpha2`	1alpha2	1.2, 1.0.2, 1foo2
`== *`	1, alpha, ∫	{no examples}
`= *`	1.0, 1, 1.2.3	{no examples}
`< 1.2`	1.0, 1	1.2, 2.0
`<= 1.2`	1.2, 1.0, 1	1.2.3, 2.5

optional

Boolean. Determines whether described dependency is optional. Defaults to false.

build

Boolean. Determines whether this is build-time dependency. Defaults to true.

homepage

String, the home page of the plugin.

vim-script-nr

Number, script number on vim.org website.

author

String. Describes author of the plugin in format name <email>.

maintainer

String. Describes maintainer of the plugin in format name <email>.

description

String. Plugin description.

deprecation-warning: String, deprecation warning message that should be displayed when installing the plugin.

Note

Plugin managers must display this message when they attempt attended installation of plugins with this key in plugin-info file. They may also display this message when attempting attended update and it appears that this key is present in new plugin-info, but did not exist in the old one.

replacements: List of strings, plugins that are suggested to replace deprecated plugin. Must not be present if there is no deprecation-warning key. Contributors must not list plugin competitors here unless plugin was deprecated for one of the listed reasons.

pre-install, post-install, pre-update, post-update: Tells plugin manager what to run in different cases: *-install hooks are run before or after plugin installation, *-update hooks are run before or after update. Value is a plain string that must correspond to one of the file names in hooks directory without an extension. Note that hook may also be located in release-specific hooks directory.
alternate-names: List of strings: alternate names of the plugin. Used for populating alternate-names key in the index.json file.