Explore the docs »

Report Bug · Request Feature · Ask Question

Use rocks.nvim to install plugins from git!

[![LuaRocks][luarocks-shield]][luarocks-url]

:star2: Summary

rocks-git.nvim extends rocks.nvim with the ability to install plugins from git repositories.

It does so by hooking into the :Rocks {install|update|sync|prune} commands, allowing you to add plugins entries to your rocks.toml as follows:

[plugins.neorg]
git = "nvim-neorg/neorg"
or...
[plugins] neorg = { git = "nvim-neorg/neorg" }

[!IMPORTANT]

This plugin is meant as a simple, minimal bridge for plugins that cannot

be installed with luarocks.

For Lua plugins, we recommend requesting (or creating a PR)

to upload them to luarocks, as this enables proper SemVer versioning.

:pencil: Requirements

• rocks.nvim >= 2.12.0
• The git command line utility.

:hammer: Installation

Simply run :Rocks install rocks-git.nvim, and you are good to go!

:books: Usage

You can use the same :Rocks {install|update|sync|prune} commands as you would use to install rocks with rocks.nvim.

The only difference is the :Rocks install {plugin} {args?} command.

Arguments:

• plugin: The plugin short name[^1], e.g. owner/repo or a git HTTPS/SSH URL.
• args: (optional) key=value pairs, see Configuration options.

Configuration options

The following fields can be set in a rocks.toml entry that is managed by this plugin:

| Field | Type | Required? | Description | |:-- |:-- |:-- |:-- | | name | string | Yes | Name of the plugin | | git | string | Yes | Git short name[^1], e.g. "lumen-oss/rocks-git.nvim" or a git URL. | | opt | boolean | No (default: false) | Plugins with opt = true will not be loaded on startup. See :h packadd | | rev | string | No | Git revision or tag to checkout | | branch | string | No | Git branch to checkout | | build | string | No | Shell or Vimscript command to run after install/update. Will run a vim command if prefixed with : | | ignore_tags | boolean | No (default: false) | rocks-git.nvim prioritises semver tags by default. This option disables that behaviour. |

[^1]: Also supports github:, gitlab:, codeberg: and sourcehut: prefixes, e.g. gitlab:owner/repo (HTTPS only).

[!TIP]

See also :h rocks-git.

:stethoscope: Troubleshooting

Git commands and error logs will show up in :Rocks log.

:book: License

rocks-git.nvim is licensed under GPLv3.

:green_heart: Contributing

Contributions are more than welcome! See CONTRIBUTING.md for a guide.

[luarocks-shield]: https://img.shields.io/luarocks/v/neorocks/rocks-git.nvim?logo=lua&color=purple&style=for-the-badge [luarocks-url]: https://luarocks.org/modules/neorocks/rocks-git.nvim