GitLab plugin for Neovim - gitlab.vim
The GitLab plugin integrates GitLab with Neovim, and is built in Lua.
GitLab for Neovim supports GitLab Duo Code Suggestions. Code Suggestions provides a LSP (Language Server Protocol) server, to support the built-in Control+x, Control+o Omni Completion key mapping:
Mode | Key mappings | Type | Description |
---|---|---|---|
INSERT
| Control+x, Control+o | Built-in | Requests completions from GitLab Duo Code Suggestions through the language server. |
NORMAL
| <Plug>(GitLabToggleCodeSuggestions)
| <Plug>
| Toggles Code Suggestions on or off for the current buffer. Requires configuration. |
Install the extension
Prerequisites:
- For both GitLab.com and self-managed, you have GitLab version 16.1 or later.
While many extension features might work with earlier versions, they are unsupported.
- The GitLab Duo Code Suggestions feature requires GitLab version 16.8 or later.
- You have Neovim version 0.9 or later.
To install the extension, follow the installation steps for your chosen plugin manager:
Run this command to include this project with
packadd
on startup:
git clone https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim.git ~/.local/share/nvim/site/pack/gitlab/start/gitlab.vim
lazy.nvim
Add this plugin to your lazy.nvim configuration:
{
'git@gitlab.com:gitlab-org/editor-extensions/gitlab.vim.git',
-- Activate when a file is created/opened
event = { 'BufReadPre', 'BufNewFile' },
-- Activate when a supported filetype is open
ft = { 'go', 'javascript', 'python', 'ruby' },
cond = function()
-- Only activate if token is present in environment variable.
-- Remove this line to use the interactive workflow.
return vim.env.GITLAB_TOKEN ~= nil and vim.env.GITLAB_TOKEN ~= ''
end,
opts = {
statusline = {
-- Hook into the built-in statusline to indicate the status
-- of the GitLab Duo Code Suggestions integration
enabled = true,
},
},
}
packer.nvim
Declare the plugin in your packer.nvim configuration:
use {
"git@gitlab.com:gitlab-org/editor-extensions/gitlab.vim.git",
}
Configure the extension
-
Configure environment variables. While these are the most common, a full list is available in this plugin’s help text at
doc/gitlab.txt
:Environment variable Default Description GITLAB_TOKEN
.not applicable The default GitLab personal access token to use for authenticated requests. If provided, skips interactive authentication. GITLAB_VIM_URL
.https://gitlab.com
Override the GitLab instance to connect with. Defaults to https://gitlab.com
. -
Configure your desired file types. For example, because this plugin supports Ruby, it adds a
FileType ruby
auto-command. To configure this behavior for additional file types, add more file types to thecode_suggestions.auto_filetypes
setup option:require('gitlab').setup({ statusline = { enabled = false }, code_suggestions = { # For the full list of default languages, see the 'auto_filetypes' array in # https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim/-/blob/main/lua/gitlab/config/defaults.lua auto_filetypes = { 'ruby', 'javascript' }, -- Default is { 'ruby' } } })
- Optional. Configure Omni Completion.
- Optional. Configure
<Plug>
key mappings. - Optional. Set up helptags using
:helptags ALL
for access to:help gitlab.txt
.
Configure Omni Completion
To enable Omni Completion with Code Suggestions:
- Create a personal access token with the
api
scope. - Install the Code Suggestions language server.
-
Optional. Consider configuring Omni Completion’s dialog even for a single suggestion:
vim.o.completeopt = 'menu,menuone'
When working in a supported file type, open the Omni Completion menu by pressing Ctrl+x then Ctrl+o.
Configure <Plug>
key mappings
For convenience, this plugin provides <Plug>
key mappings. To use the <Plug>(GitLab...)
key mapping,
you must include your own key mapping that references it:
-- Toggle Code Suggestions on/off with CTRL-g in normal mode:
vim.keymap.set('n', '<C-g>', '<Plug>(GitLabToggleCodeSuggestions)')
Disable gitlab.statusline
By default, this plugin enables gitlab.statusline
, which uses the built-in statusline
to show the status of the Code Suggestions integration. If you want to disable gitlab.statusline
,
add this to your configuration:
require('gitlab').setup({
statusline = {
enabled = false
}
})
Report issues with the extension
Report any issues, bugs, or feature requests in the
gitlab.vim
issue queue.
Submit your feedback in issue 22
in the gitlab.vim
repository.
Uninstall the extension
To uninstall the extension, remove this plugin and any language server binaries with these commands:
rm -r ~/.local/share/nvim/site/pack/gitlab/start/gitlab.vim
rm ~/.local/share/nvim/gitlab-code-suggestions-language-server-*