setup-vim

setup-vim is a GitHub Action to setup Vim, Neovim, or MacVim.

Usage

Basic:

# Setup the head version of Vim
- uses: thinca/action-setup-vim@v2

With options:

- uses: thinca/action-setup-vim@v2
  with:
    vim_version: v9.1.0000

Setup Vim and Neovim with 2 versions for each platforms using matrix:

strategy:
  matrix:
    vim_type: ['Vim', 'Neovim']
    version: ['head', 'stable']
    os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
    include:
      - vim_type: 'Vim'
        version: 'stable'
        vim_version: 'v9.1.0000'
runs-on: '${{ matrix.os }}'
steps:
  - uses: 'actions/checkout@v4'
  - name: 'Setup Vim'
    id: 'vim'
    uses: 'thinca/action-setup-vim@v2'
    with:
      vim_version: '${{ matrix.vim_version || matrix.version }}'
      vim_type: '${{ matrix.vim_type }}'
  - name: 'Run test'
    run: |
      # Show Vim's version
      ${{ steps.vim.outputs.executable }} --version
      # ... run tests ...

About installation

This action provides two ways to setup Vim.

1. Build Vim from source code. You can specify Git's ref(tag, branch, or sha1) for vim_version. The result is cached by default. See cache input.

2. Download pre-built Vim from releases page. You can specify semver(v9.1.0146, v0.9.5) or tag name of GitHub Release for vim_version.

Some combinations not available. See the following. By default, uses download if available, otherwise uses build.

Vim

OS	way	GUI	Installation
Linux	build	gvim	Sources from vim/vim.
Linux	download	gvim	Releases from vim/vim-appimage. (*)
MacOS	build	gvim	Sources from vim/vim.
MacOS	download	N/A	Not available.
Windows	build	gvim	Sources from vim/vim.
Windows	download	gvim	Releases from vim/vim-win32-installer.

(*) Downloading Vim from AppImage is available from v8.1.1239. Before v8.1.1234 cannot start vim. This was fixed by vim/vim-appimage#6.

Neovim

OS	way	GUI	Installation
Linux	build	N/A	Sources from neovim/neovim.
Linux	download	N/A	Releases from neovim/neovim.
MacOS	build	N/A	Sources from neovim/neovim. (**)
MacOS	download	N/A	Releases from neovim/neovim.
Windows	build	N/A	Not available(Help wanted).
Windows	download	nvim-qt.exe	Releases from neovim/neovim.

(**) Building Neovim on MacOS(Catalina) has a problem.

Building v0.4.3 and before versions will be failure. See neovim/neovim#11412 for the detail.

MacVim

OS	way	GUI	Installation
Linux	build	N/A	Not available.
Linux	download	N/A	Not available.
MacOS	build	N/A	Sources from macvim-dev/macvim.
MacOS	download	N/A	Releases from macvim-dev/macvim.
Windows	build	N/A	Not available.
Windows	download	N/A	Not available.

MacVim has a GUI version, but it is not supported yet because it is too difficult treating on CI.

Building snapshot-157 and before versions will be failure. See macvim-dev/macvim#946 for the detail.

Action Inputs

vim_version

Version of Vim. The meaning of this value depends on vim_type and download.

The value head is always head version: When download is on, this points head of release. When download is off, this points master of repository.

When download is on and specified a semver such as v8.2.0000, this action finds a minimum version that is higher than a specified version. For example, when there are some released versions: v8.2.0052 v8.2.0057 v8.2.0065 And when a specified version is v8.2.0055, v8.2.0057 is actually selected. Also, when a specified version is v8.2.0060, v8.2.0065 is actually selected.

When download is off, this is a tag of repository. Note that the repository of MacVim has tags like release-xxx instead of like vx.x.xxx.

default: head

vim_type

Type of Vim. This is one of vim, neovim, or macvim.

default: vim

gui

When this is yes, setups the GUI version. And outputs.executable points to GUI version of Vim.

default: no

arch

Architecture of Vim. This is either of x86_64 or x86, enable when vim_type is vim on Windows.

default: x86_64

download

When this is always, downloads the officially released binary, or fail if unavailable. When this is available, downloads the officially released binary if available, otherwise builds from source code. When this is never, always builds from source code.

default: available

cache

When this is true(default), cache the built Vim.

This uses same caching mechanism from actions/cache. Therefore, this consumes the limitation of cache size.

Ref: Caching dependencies to speed up workflows#Usage limits and eviction policy

This is automatically disabled when download is on.

default: true

github_token

Your GitHub API token to access to releases of repositories without limit. Normally this is automatically set so you do not need set this.

default: ${{ github.token }}

Action Outputs

executable

The name of executable file. This is not a full path, just name. When gui is yes, this points to GUI version. e.g. vim nvim gvim

executable_path

The full path of executable file.

actual_vim_version

Version of Vim actually installed. e.g. v8.2.0123 v0.4.3 49cd750d6a72efc0571a89d7a874bbb01081227f

install_type

Install was done with build or download.

install_path

Base path of installed Vim. Note that this does not point to bin.

cache_hit

When cache is enabled and cache was found, this is true. Otherwise this is false.

License

zlib License

Author

thinca thinca@gmail.com