Skip to content

Latest commit

 

History

History
236 lines (178 loc) · 9.99 KB

README.md

File metadata and controls

236 lines (178 loc) · 9.99 KB
Raw

GitHub Action to setup Vim and Neovim

Build status Action Marketplace

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 as well:

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

When you want to customize the build configuration for Vim, configure-args input is available. The input is passed to ./configure option when building Vim from source:

- uses: rhysd/action-setup-vim@v1
  with:
    version: nightly
    configure-args: |
      --with-features=huge --enable-fail-if-missing --disable-nls

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 as well:

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

OS Version Installation
Linux stable Install vim-gtk3 via apt package manager
Linux nightly Build the HEAD of vim/vim repository
Linux vX.Y.Z Build the vX.Y.Z tag of vim/vim repository
macOS stable Install MacVim via brew install macvim
macOS nightly Build the HEAD of vim/vim repository
macOS vX.Y.Z Build the vX.Y.Z tag of vim/vim repository
Windows stable There is no stable release for Windows so fall back to nightly
Windows nightly Install the latest release from the installer repository
Windows vX.Y.Z Install the release at vX.Y.Z tag of the installer repository

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.

Note: When you build Vim older than 8.2.1119 on macOS, Xcode 11 or earlier is necessary due to lack of this patch. Please try macos-11 runner instead of the latest macOS runner in the case.

Neovim

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

OS Version Installation
Linux stable Install from the latest Neovim stable release
Linux nightly Install from the latest Neovim nightly release
Linux vX.Y.Z Install the release at vX.Y.Z tag of neovim/neovim repository
macOS stable brew install neovim using Homebrew
macOS nightly Install from the latest Neovim nightly release
macOS vX.Y.Z Install the release at vX.Y.Z tag of neovim/neovim repository
Windows stable Install from the latest Neovim stable release
Windows nightly Install from the latest Neovim nightly release
Windows vX.Y.Z Install the release at vX.Y.Z tag of neovim/neovim repository

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.
  • 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.