GitHub Action to setup Vim and Neovim

action-setup-vim is an action for GitHub Actions to setup Vim or Neovim on Linux, macOS and Windows. Stable releases, nightly releases and specifying versions are supported.

For stable releases, this action will install Vim or Neovim from system's package manager or official releases since it is the most popular way to install them and it's faster than building from source.

For nightly release, this action basically installs the nightly release of Vim or Neovim from official releases. If unavailable, it builds executables from sources.

For more details, please read the following 'Installation details' section.

Why?

Since preparing Vim editor is highly depending on a platform. On Linux, Vim is usually installed via system's package manager like apt. On macOS, MacVim is the most popular Vim distribution and usually installed via Homebrew. On Windows, official installers are provided.

Neovim provides releases on GitHub and system package managers.

If you're an author of Vim and/or Neovim plugin and your plugin has some tests, you'd like to run them across platforms on Vim and/or Neovim. action-setup-vim will help the installation with only one step. You don't need to separate workflow jobs for each platforms and Vim/Neovim.

Usage

Install the latest stable Vim

- uses: rhysd/action-setup-vim@v1

Install the latest nightly Vim

- uses: rhysd/action-setup-vim@v1
  with:
    version: nightly

Install the latest Vim v8.1.123. The version is a tag name in vim/vim repository. Please see the following 'Choose specific version' section also

- uses: rhysd/action-setup-vim@v1
  with:
    version: v8.1.0123

Install the latest stable Neovim

- uses: rhysd/action-setup-vim@v1
  with:
    neovim: true

Install the latest nightly Neovim

- uses: rhysd/action-setup-vim@v1
  with:
    neovim: true
    version: nightly

Install the Neovim v0.4.3. Please see the following 'Choose specific version' section also

- uses: rhysd/action-setup-vim@v1
  with:
    neovim: true
    version: v0.4.3

After the setup, vim executable will be available for Vim and nvim executable will be available for Neovim.

Real-world examples are workflows in clever-f.vim and git-messenger.vim. And you can see this repository's CI workflows. They run this action with all combinations of the inputs.

For comprehensive lists of inputs and outputs, please refer action.yml.

Outputs

This action sets installed executable path to the action's executable output. You can use it for running Vim command in the steps later.

Here is an example to set Vim executable to run unit tests with themis.vim.

- uses: actions/checkout@v2
  with:
    repository: thinca/vim-themis
    path: vim-themis
- uses: rhysd/action-setup-vim@v1
  id: vim
- name: Run unit tests with themis.vim
  env:
    THEMIS_VIM: ${{ steps.vim.outputs.executable }}
  run: |
    ./vim-themis/bin/themis ./test

Installation details

Vim

vX.Y.Z represents a specific version such as v8.2.0126.

For stable releases on all platforms and nightly on Windows, gvim executable is also available.

When installing without system's package manager, Vim is installed at $HOME/vim.

Neovim

vX.Y.Z represents a specific version such as v0.4.3.

Only on Windows, nvim-qt.exe executable is available for GUI.

When installing without system's package manager, Neovim is installed at $HOME/nvim.

Note: Ubuntu 18.04 supports official neovim package but this action does not install it. As of now, GitHub Actions also supports Ubuntu 16.04.

Note: When downloading a Neovim asset from stable release on GitHub, the asset is rarely missing in the release. In the case, this action will get the latest version tag from GitHub API and use it instead of stable tag (see #5 for more details).

Note: When downloading a Neovim asset from nightly release on GitHub, it might cause 'Asset Not Found' error. This is because the Nightly build failed due to some reason in neovim/neovim CI workflow. In the case, this action tries to build Neovim from sources on Linux and macOS workers. It gives up installation on other platforms.

Choose specific version

Vim

If Vim is built from source, any tag version should be available.

If Vim is installed via release asset (on Windows), please check vim-win32-installer releases page to know which versions are available. The repository makes a release once per day (nightly).

Note that Vim's patch number in version tags is in 4-digits like v8.2.0126. Omitting leading zeros such as v8.2.126 or v8.2.1 is not allowed.

Neovim

When installing the specific version of Neovim, this action downloads release assets from neovim/neovim. Please check neovim/neovim releases page to know which versions have release assets. For example, Neovim 0.4.0 has no Windows releases so it is not available for installing Neovim on Windows.

Current limitation

• GUI version (gVim and nvim-qt) is supported partially as described in above section.
• Building Vim is not configurale. For example, arguments cannot be passed to ./configure.
• Installing Vim/Neovim from system's package manager is not configurable. For example, arguments cannot be passed to brew install.

These are basically not a technical limitation. Please let me know by creating an issue if you want some of them.

License

Distributed under the MIT license.