Database directory structure¶

Note

Example JSON code blocks show generic JSON structure, not the exact layout of data physically written to the file. E.g. plugin managers must not rely on vim-pi (not) writing the whole file as one long line.

/: Root of the database. Contains all of the following data.

/index.json

Index of all plugins. Is a JSON file containing mapping with the following format:

{
    "{name}": {
        "last-update-time": "{update-time}",
        "last-release-time": "{release-time}",
        "description": "{description}",
        "author": "{author}",
        "vim-script-nr": {scriptnr},
        "alternate-names": ["{name1}", "{name2}", ..., "{nameN}"],
        "deprecated": {deprecated}
    },
    ...
}

Fields:

{name}: Exactly the same name as plugin directory name.

{update-time}

Field {update-time} is written in a very strict variant of ISO-8601 (described below), so unless you are preparing for 101 century you can safely use simple string comparison. This field should be checked by plugin managers when they decide whether they need to update information about plugin.

Required.

{release-time}

Like above, but is only altered when either new release, new fork or new development version were added. Is not altered when description or hooks were changed or when one of the old versions was removed.

Required.

Note

Vim-PI is not tracking development version updates if they use some of the version control systems. Plugin managers are supposed to simply rely on used VCS to update such plugins.

{author}

Author name. Optional.

{description}

Latest description of the plugin. May be used for searches. Optional.

{scriptnr}

A script number on www.vim.org. Optional.

{name1} ... {nameN}: Alternate names may be not unique and are supposed to represent alternative variants of writing plugin: e.g. “VAM” for “vim-addon-manager”. Optional. Plugin managers are supposed to prefer these names over fuzzy matches.

Note

Two plugins may share the same alternate name.
{deprecated}: true if plugin was deprecated. If it was not this field is absent, but may be set to false as well. Optional. Plugin managers are supposed to remove deprecated plugins from search and completion unless configured otherwise.

Note

For forward compatibility plugin managers must not rely on absence of keys that are not described here.

Note

ISO-8601 is very permissive. For index.json there are additional restrictions:

UTC time zone indicated by Z at the end,
nanoseconds; uses comma as decimal fraction separator,
hyphenminuses (ASCII dashes) as year, month and day separator,
no week dates,
T as date/time separator,
: as hour/minute/second separator.

In this format UNIX Epoch will look like this:

1970-01-01T00:00:00,000000000Z

/update-times.dat

Smaller version of the index of all plugins: contains only plugin name – last update time – last time of a new release 3-tuples in the format:

{name1}\0{last-update-time1}\0{last-release-time1}\n
...
{nameN}\0{last-update-timeN}\0{last-release-timeN}\n

, trailing newline is always present and all *-time fields have all separators stripped and are missing timezone: UNIX Epoch will look like 19700101000000000000000 so plugin managers still may use string comparison, but also numeric comparison (if they are written in a language with big integer support and want to waste time on creating it).

It is intended that plugin managers use this file only to check for available updates.

/plugins/

Directory, containing plugin directories.

/plugins/name/

Directory with files specific to the given plugin.

/plugins/name/MANIFEST.json

List of the files in this directory. List format:

{
    "{filename1}": {"size": {size1}, "sha256": "{sha256_1}"},
    "{filename2}": {"size": {size2}, "sha256": "{sha256_2}"},
    …
    "{filenameN}": {"size": {sizeN}, "sha256": "{sha256_N}"}
}

. Each filename is a path relative to /plugins/name directory.

Note

For forward compatibility plugin managers must not rely on presence of sha256 key (it may be replaced with other hash(es) in the future, though it is more likely that they will be just added) or absence of any keys that are not described here.

/plugins/name/plugin-info.json: Top-level plugin-info file. Format is described in plugin-info file documentation.

Note

This file must not contain repository and version keys. These key must be defined in plugin-info file inside release or development directory.

/plugins/name/hooks/: Contains hoodospel hook files used by plugin-info file.

/plugins/name/hooks/hook.hds

Contains one specific hook. You should replace hook with one of the stage names identical to one of the hook keys from plugin-info file. If hook should be applied at both post-install and post-update stages it should be named post. If identical hook should be run at two or more other stages then you should deduce a name on your own and raise an issue at vim-pi documentation issue tracker describing this name and the case in which you need identical names for both stages.

All post* and pre* are reserved for hooks that are described directly in relevant keys in a plugin-info file. Names not starting with post or pre may be used for code that is common to more then one hook.

/plugins/name/releases/

Directory that contains version-specific information for all plugin versions.

/plugins/name/releases/version/: Directory that contains version-specific information for one plugin version. Plugin version must not contain @ character: it is reserved for version variants (e.g. 0.1 contains description for installing plugin version 0.1 from archive and 0.1@git uses git) and forks (e.g. marcweber@0.0 for version 0.0 of a fork created by Marc Weber).

/plugins/name/releases/version/plugin-info.json: Main plugin-info file. Format of this file is described in plugin-info file documentation. Is merged with top-level plugin-info file.

/plugins/name/releases/version/hooks/: Same as top-level hooks directory, but contain hooks specific to given plugin version. These hooks will be used first.
/plugins/name/development/: Directory that contains all variants of development installations.

/plugins/name/development/variant/: Directory that contains version-specific information for development plugin version. Directory structure is the same as for release directory. variant should be either a name of the author of the fork, preceded with fork@, an upstream mirror that uses different VCS in a format mirror@vcs where vcs must be one of the repository types or just upstream.

Note

Forks must not be chosen by plugin managers by default.

/plugins/name/files/: Miscellaneous files that are not any of the above files.