*gitlab.nvim.txt* Create, review, and manage Gitlab resources without leaving Neovim ============================================================================== Table of Contents *gitlab.nvim.table-of-contents* - Requirements |gitlab.nvim.requirements| - Quick Start |gitlab.nvim.quick-start| - Installation |gitlab.nvim.installation| - Connecting to Gitlab |gitlab.nvim.connecting-to-gitlab| - Configuring the Plugin |gitlab.nvim.configuring-the-plugin| - Usage |gitlab.nvim.usage| - The Summary view |gitlab.nvim.the-summary-view| - Reviewing an MR |gitlab.nvim.reviewing-an-mr| - Temporary registers |gitlab.nvim.temp-registers| - Discussions and Notes |gitlab.nvim.discussions-and-notes| - Labels |gitlab.nvim.labels| - Signs and diagnostics |gitlab.nvim.signs-and-diagnostics| - Emojis |gitlab.nvim.emojis| - Uploading Files |gitlab.nvim.uploading-files| - MR Approvals |gitlab.nvim.mr-approvals| - Merging an MR |gitlab.nvim.merging-an-mr| - Creating an MR |gitlab.nvim.creating-an-mr| - Pipelines |gitlab.nvim.pipelines| - Reviewers and Assignees |gitlab.nvim.reviewers-and-assignees| - Restarting The Go Server |gitlab.nvim.restarting| - Keybindings |gitlab.nvim.keybindings| - Troubleshooting |gitlab.nvim.troubleshooting| - Api |gitlab.nvim.api| OVERVIEW *gitlab.nvim.overview* This Neovim plugin is designed to make it easy to review Gitlab MRs from within the editor. This means you can do things like: - Create, approve, and merge MRs for the current branch - Read and edit an MR description - Add or remove reviewers and assignees - Resolve, reply to, and unresolve discussion threads - Create, edit, delete, and reply to comments - View and manage pipeline Jobs - Upload files, jump to the browser, and a lot more! REQUIREMENTS *gitlab.nvim.requirements* - Go >= v1.19 QUICK START *gitlab.nvim.quick-start* 1. Install Go 2. Add configuration (see Installation section) 5. Run `:lua require("gitlab").choose_merge_request()` This will checkout the branch locally, and up the plugin's reviewer pane. INSTALLATION *gitlab.nvim.installation* With Lazy: >lua { "harrisoncramer/gitlab.nvim", dependencies = { "MunifTanjim/nui.nvim", "nvim-lua/plenary.nvim", "sindrets/diffview.nvim", "stevearc/dressing.nvim", -- Recommended but not required. Better UI for pickers. "nvim-tree/nvim-web-devicons", -- Recommended but not required. Icons in discussion tree. }, build = function () require("gitlab.server").build(true) end, -- Builds the Go binary config = function() require("gitlab").setup() end, } < And with pckr.nvim: >lua { "harrisoncramer/gitlab.nvim", requires = { "MunifTanjim/nui.nvim", "nvim-lua/plenary.nvim", "sindrets/diffview.nvim", "stevearc/dressing.nvim", -- Recommended but not required. Better UI for pickers. "nvim-tree/nvim-web-devicons", -- Recommended but not required. Icons in discussion tree. }, run = function() require("gitlab.server").build() end, -- Builds the Go binary config = function() require("diffview") -- We require some global state from diffview require("gitlab").setup() end, } < CONNECTING TO GITLAB *gitlab.nvim.connecting-to-gitlab* This plugin requires an auth token to connect to Gitlab. The token can be set in the root directory of the project in a `.gitlab.nvim` environment file, or can be set via a shell environment variable called `GITLAB_TOKEN` instead. If both are present, the `.gitlab.nvim` file will take precedence. Optionally provide a GITLAB_URL environment variable (or gitlab_url value in the `.gitlab.nvim` file) to connect to a self-hosted Gitlab instance. This is optional, use ONLY for self-hosted instances. Here’s what they’d look like as environment variables: >bash export GITLAB_TOKEN="your_gitlab_token" export GITLAB_URL="https://my-personal-gitlab-instance.com/" < And as a `.gitlab.nvim` file: > auth_token=your_gitlab_token gitlab_url=https://my-personal-gitlab-instance.com/ < The plugin will look for the `.gitlab.nvim` file in the root of the current project by default. However, you may provide a custom path to the configuration file via the `config_path` option. This must be an absolute path to the directory that holds your `.gitlab.nvim` file. The `connection_settings` block in the `state.lua` file will be used to configure your connection to Gitlab. In case even more control over the auth config is needed, there is the possibility to override the `auth_provider` settings field. It should be a function that returns the `token` as well as the `gitlab_url` value and a nilable error value. If the `gitlab_url` is `nil`, `https://gitlab.com` is used as default. Here an example how to use a custom `auth_provider`: >lua require("gitlab").setup({ auth_provider = function() return "my_token", "https://custom.gitlab.instance.url", nil end, } < CONFIGURING THE PLUGIN *gitlab.nvim.configuring-the-plugin* Here is the default setup function. All of these values are optional, and if you call this function with no values the defaults will be used: >lua require("gitlab").setup({ port = nil, -- The port of the Go server, which runs in the background, if omitted or `nil` the port will be chosen automatically log_path = vim.fn.stdpath("cache") .. "/gitlab.nvim.log", -- Log path for the Go server config_path = nil, -- Custom path for `.gitlab.nvim` file, please read the "Connecting to Gitlab" section debug = { request = false, -- Requests to/from Go server response = false, gitlab_request = false, -- Requests to/from Gitlab gitlab_response = false, }, attachment_dir = nil, -- The local directory for files (see the "summary" section) reviewer_settings = { jump_with_no_diagnostics = false, -- Jump to last position in discussion tree if true, otherwise stay in reviewer and show warning. diffview = { imply_local = false, -- If true, will attempt to use --imply_local option when calling |:DiffviewOpen| }, }, connection_settings = { proxy = "", -- Configure a proxy URL to use when connecting to GitLab. Supports URL schemes: http, https, socks5 insecure = false, -- Like curl's --insecure option, ignore bad x509 certificates on connection remote = "origin", -- The default remote that your MRs target }, keymaps = { disable_all = false, -- Disable all mappings created by the plugin help = "g?", -- Open a help popup for local keymaps when a relevant view is focused (popup, discussion panel, etc) global = { disable_all = false, -- Disable all global mappings created by the plugin add_assignee = "glaa", delete_assignee = "glad", add_label = "glla", delete_label = "glld", add_reviewer = "glra", delete_reviewer = "glrd", approve = "glA", -- Approve MR revoke = "glR", -- Revoke MR approval merge = "glM", -- Merge the feature branch to the target branch and close MR create_mr = "glC", -- Create a new MR for currently checked-out feature branch choose_merge_request = "glc", -- Chose MR for review (if necessary check out the feature branch) start_review = "glS", -- Start review for the currently checked-out branch summary = "gls", -- Show the editable summary of the MR copy_mr_url = "glu", -- Copy the URL of the MR to the system clipboard open_in_browser = "glo", -- Openthe URL of the MR in the default Internet browser create_note = "gln", -- Create a note (comment not linked to a specific line) pipeline = "glp", -- Show the pipeline status toggle_discussions = "gld", -- Toggle the discussions window toggle_draft_mode = "glD", -- Toggle between draft mode (comments posted as drafts) and live mode (comments are posted immediately) publish_all_drafts = "glP", -- Publish all draft comments/notes }, popup = { disable_all = false, -- Disable all default mappings for the popup windows (comments, summary, MR creation, etc.) next_field = "", -- Cycle to the next field. Accepts |count|. prev_field = "", -- Cycle to the previous field. Accepts |count|. perform_action = "ZZ", -- Once in normal mode, does action (like saving comment or applying description edit, etc) perform_linewise_action, = "ZA", -- Once in normal mode, does the linewise action (see logs for this job, etc) discard_changes = "ZQ", -- Quit the popup discarding changes, the popup content is not saved to the `temp_registers` (see `:h gitlab.nvim.temp-registers`) }, discussion_tree = { disable_all = false, -- Disable all default mappings for the discussion tree window add_emoji = "Ea", -- Add an emoji to the note/comment delete_emoji = "Ed", -- Remove an emoji from a note/comment delete_comment = "dd", -- Delete comment edit_comment = "e", -- Edit comment reply = "r", -- Reply to comment toggle_resolved = "-", -- Toggle the resolved status of the whole discussion jump_to_file = "o", -- Jump to comment location in file jump_to_reviewer = "a", -- Jump to the comment location in the reviewer window open_in_browser = "b", -- Jump to the URL of the current note/discussion copy_node_url = "u", -- Copy the URL of the current node to clipboard switch_view = "c", -- Toggle between the notes and discussions views toggle_tree_type = "i", -- Toggle type of discussion tree - "simple", or "by_file_name" publish_draft = "P", -- Publish the currently focused note/comment toggle_date_format = "dt", -- Toggle between date formats: relative (e.g., "5 days ago", "just now", "October 13, 2024" for dates more than a month ago) and absolute (e.g., "03/01/2024 at 11:43") toggle_draft_mode = "D", -- Toggle between draft mode (comments posted as drafts) and live mode (comments are posted immediately) toggle_sort_method = "st", -- Toggle whether discussions are sorted by the "latest_reply", or by "original_comment", see `:h gitlab.nvim.toggle_sort_method` toggle_node = "t", -- Open or close the discussion toggle_all_discussions = "T", -- Open or close separately both resolved and unresolved discussions toggle_resolved_discussions = "R", -- Open or close all resolved discussions toggle_unresolved_discussions = "U", -- Open or close all unresolved discussions refresh_data = "", -- Refresh the data in the view by hitting Gitlab's APIs again print_node = "p", -- Print the current node (for debugging) }, reviewer = { disable_all = false, -- Disable all default mappings for the reviewer windows create_comment = "c", -- Create a comment for the lines that the following {motion} moves over. Repeat the key(s) for creating comment for the current line create_suggestion = "s", -- Create a suggestion for the lines that the following {motion} moves over. Repeat the key(s) for creating comment for the current line move_to_discussion_tree = "a", -- Jump to the comment in the discussion tree }, }, popup = { -- The popup for comment creation, editing, and replying width = "40%", -- Can be a percentage (string or decimal, "40%" = 0.4) of editor screen width, or an integer (number of columns) height = "60%", -- Can be a percentage (string or decimal, "60%" = 0.6) of editor screen width, or an integer (number of rows) position = "50%", -- Position (from the top left corner), either a number or percentage string that applies to both horizontal and vertical position, or a table that specifies them separately, e.g., { row = "90%", col = "100%" } places popups in the bottom right corner while leaving the status line visible border = "rounded", -- One of "rounded", "single", "double", "solid" opacity = 1.0, -- From 0.0 (fully transparent) to 1.0 (fully opaque) comment = nil, -- Individual popup overrides, e.g. { width = "60%", height = "80%", border = "single", opacity = 0.85 }, edit = nil, note = nil, help = nil, -- Width and height are calculated automatically and cannot be overridden pipeline = nil, -- Width and height are calculated automatically and cannot be overridden reply = nil, squash_message = nil, create_mr = { width = "95%", height = "95%" }, summary = { width = "95%", height = "95%" }, temp_registers = {}, -- List of registers for backing up popup content (see `:h gitlab.nvim.temp-registers`) }, discussion_tree = { -- The discussion tree that holds all comments expanders = { -- Discussion tree icons expanded = " ", -- Icon for expanded discussion thread collapsed = " ", -- Icon for collapsed discussion thread indentation = " ", -- Indentation Icon }, spinner_chars = { "/", "|", "\\", "-" }, -- Characters for the refresh animation auto_open = true, -- Automatically open when the reviewer is opened default_view = "discussions", -- Show "discussions" or "notes" by default blacklist = {}, -- List of usernames to remove from tree (bots, CI, etc) sort_by = "latest_reply", -- Sort discussion tree by the "latest_reply", or by "original_comment", see `:h gitlab.nvim.toggle_sort_method` keep_current_open = false, -- If true, current discussion stays open even if it should otherwise be closed when toggling position = "bottom", -- "top", "right", "bottom" or "left" size = "20%", -- Size of split relative = "editor", -- Position of tree split relative to "editor" or "win" (window) resolved = '✓', -- Symbol to show next to resolved discussions unresolved = '-', -- Symbol to show next to unresolved discussions unlinked = "󰌸", -- Symbol to show next to unliked comments (i.e., not threads) draft = "✎", -- Symbol to show next to draft comments/notes tree_type = "simple", -- Type of discussion tree - "simple" means just list of discussions, "by_file_name" means file tree with discussions under file draft_mode = false, -- Whether comments are posted as drafts as part of a review relative_date = true, -- Whether to show relative time like "5 days ago" or absolute time like "03/01/2025 at 01:43" winopts = { -- Window-local options for the discussion tree split number = false, relativenumber = false, breakindent = true, -- Every wrapped line will continue visually indented showbreak = "+ ", -- String to put at the start of lines that have been wrapped } winbar = nil, -- Custom function to return winbar title, should return a string. Provided with WinbarTable (defined in annotations.lua) -- If using lualine, please add "gitlab" to disabled file types, otherwise you will not see the winbar. }, emojis = { -- Function for modifying how emojis are displayed in the picker. This does not affect the actual selected emoji. -- The function is passed an emoji object as a paramter, e.g., -- {"unicode": "1F44D","name": "thumbs up sign", "shortname": ":thumbsup:", "moji": "👍"} -- This is useful if your editor/terminal/font/tmux does not render some emojis properly, -- e.g., you can remove skin tones and additionally show the shortname with -- formatter = function(val) -- return string.format("%s %s %s", val.moji:gsub("[\240][\159][\143][\187-\191]", ""), val.shortname, val.name) -- end formatter = nil, }, choose_merge_request = { open_reviewer = true, -- Open the reviewer window automatically after switching merge requests }, info = { -- Show additional fields in the summary view enabled = true, horizontal = false, -- Display metadata to the left of the summary rather than underneath fields = { -- The fields listed here will be displayed, in whatever order you choose "author", "created_at", "updated_at", "merge_status", "draft", "conflicts", "assignees", "reviewers", "pipeline", "branch", "target_branch", "delete_branch", "squash", "labels", "web_url", "mergeability_checks", -- See more detailed configuration below }, -- Settings for the mergeability checks in the summary view -- https://docs.gitlab.com/api/graphql/reference/#mergeabilitycheckidentifier mergeability_checks = { -- Symbols for individual check statuses. Set values to `false` to hide checks with given status from summary statuses = { SUCCESS = "✅", CHECKING = "🔁", FAILED = "❌", WARNING = "⚠️", INACTIVE = "💤", }, -- Descriptions for individual checks. Set values to `false` to hide given checks from summary checks = { CI_MUST_PASS = "Pipeline must succeed", COMMITS_STATUS = "Source branch exists and contains commits", CONFLICT = "Merge conflicts must be resolved", DISCUSSIONS_NOT_RESOLVED = "Open threads must be resolved", DRAFT_STATUS = "Merge request must not be draft", JIRA_ASSOCIATION_MISSING = "Title or description references a Jira issue", LOCKED_LFS_FILES = "All LFS files must be unlocked", LOCKED_PATHS = "All paths must be unlocked", MERGE_REQUEST_BLOCKED = "Merge request is not blocked", MERGE_TIME = "Merge is not blocked due to a scheduled merge time", NEED_REBASE = "Merge request must be rebased, fast-forward merge is not possible", NOT_APPROVED = "All required approvals must be given", NOT_OPEN = "Merge request must be open", REQUESTED_CHANGES = "Change requests must be approved by the requesting user", SECURITY_POLICY_VIOLATIONS = "Security policies are satisfied", STATUS_CHECKS_MUST_PASS = "External status checks pass", TITLE_REGEX = "Title matches the expected regex", }, }, }, discussion_signs = { enabled = true, -- Show diagnostics for gitlab comments in the reviewer skip_resolved_discussion = false, -- Show diagnostics for resolved discussions severity = vim.diagnostic.severity.INFO, -- ERROR, WARN, INFO, or HINT virtual_text = false, -- Whether to show the comment text inline as floating virtual text use_diagnostic_signs = true, -- Show diagnostic sign (depending on the `severity` setting, e.g., I for INFO) along with the comment icon priority = 100, -- Higher will override LSP warnings, etc icons = { comment = "→|", range = " |", }, skip_old_revision_discussion = false, -- Don't show diagnostics for discussions that were created for earlier MR revisions }, pipeline = { created = "", pending = "", preparing = "", scheduled = "", running = "", canceled = "↪", skipped = "↪", success = "✓", failed = "", }, create_mr = { target = nil, -- Default branch to target when creating an MR template_file = nil, -- Default MR template in .gitlab/merge_request_templates delete_branch = false, -- Whether the source branch will be marked for deletion squash = false, -- Whether the commits will be marked for squashing fork = { enabled = false, -- If making an MR from a fork forked_project_id = nil, -- The ID of the project you are merging into. If nil, will be prompted. }, title_input = { -- Default settings for MR title input window width = 40, border = "rounded", }, }, colors = { discussion_tree = { username = "Keyword", mention = "WarningMsg", date = "Comment", expander = "DiffviewNonText", directory = "Directory", directory_icon = "DiffviewFolderSign", file_name = "Normal", resolved = "DiagnosticSignOk", unresolved = "DiagnosticSignWarn", draft = "DiffviewNonText", draft_mode = "DiagnosticWarn", live_mode = "DiagnosticOk", sort_method = "Keyword", } } }) < USAGE *gitlab.nvim.usage* First, check out the branch that you want to review locally: > git checkout feature-branch < Then open Neovim. To begin, try running the `summary` command or the `review` command. THE SUMMARY VIEW *gitlab.nvim.the-summary-view* The `summary` action will open the MR title and description: >lua require("gitlab").summary() < After editing the description or title, you may save your changes via the `keymaps.popup.perform_action` keybinding. By default this plugin will also show additional metadata about the MR in a separate pane underneath the description. This can be disabled, and these fields can be reordered or removed. Please see the `settings.info` section of the configuration. REVIEWING AN MR *gitlab.nvim.reviewing-an-mr* The `review` action will open a diff of the changes. You can leave comments using the `create_comment` action. In visual mode, add multiline comments with the `create_multiline_comment` command, and add suggested changes with the `create_comment_suggestion` command: >lua require("gitlab").review() require("gitlab").create_comment() require("gitlab").create_multiline_comment() require("gitlab").create_comment_suggestion() < For suggesting changes you can use `create_comment_suggestion` in visual mode which works similar to `create_multiline_comment` but prefills the comment window with Gitlab’s suggest changes code block with prefilled code from the visual selection. Just like the summary, all the different kinds of comments are saved via the `keymaps.popup.perform_action` keybinding. DRAFT NOTES *gitlab.nvim.draft-comments* When you publish a "draft" of any of the above resources, the comment will be added to a review. You can configure the default commenting mode (draft vs live) via the `state.settings.discussion_tree.draft_mode` setting, and you can toggle the setting with the `keymaps.discussion_tree.toggle_draft_mode` keybinding, or by calling the `gitlab.toggle_draft_mode()` function. You may publish all draft comments via the `gitlab.publish_all_drafts()` function, and you can publish an individual comment or note by pressing the `keymaps.discussion_tree.publish_draft` keybinding. Draft notes do not support replying or emojis. TEMPORARY REGISTERS *gitlab.nvim.temp-registers* While writing a note/comment/suggestion/reply, you may need to interrupt the work, do something else (e.g., read something in another file, etc.), and then get back to your work on the comment. For occasions like this, you can set `settings.popup.temp_registers` to a list of writable registers (see |registers|) to which the contents of the popup window will be saved just before quitting. A possible setting is, e.g., `settings.popup.temp_registers = {'"', "+", "g"}` which saves to the so called unnamed register (see |quotequote|), the system clipboard register (see |quoteplus|), as well as to the "g" register. This lets you easily paste the text back in with |p| or |P| (from the unnamed register), or with `"gp` or `"gP` if the unnamed register gets overwritten with something else. Using the clipboard register lets you easily use the text outside of nvim. NOTE: The `temp_registers` are also filled with the contents of the popup when pressing the `keymaps.popup.perform_action` keybinding, even if the action that was supposed to be performed fails. If you don't want the popup contents to be saved to the `temp_registers`, quit the popup using the `keymaps.pupup.discard_changes` keybinding, which is `ZQ` by default (compare the builtin |ZQ| command). DISCUSSIONS AND NOTES *gitlab.nvim.discussions-and-notes* Gitlab groups threads of comments together into "discussions." To display all discussions for the current MR, use the `toggle_discussions` action, which will show the discussions in a split window: >lua require("gitlab").toggle_discussions() < You can jump to the comment’s location in the reviewer window by using the `keymaps.discussion_tree.jump_to_reviewer` keybinding, or to the actual file with the `keymaps.discussion_tree.jump_to_file` keybinding. Within the discussion tree, you can delete/edit/reply to comments with the `keymaps.discussion_tree.SOME_ACTION` keybindings. If you’d like to create a note in an MR (like a comment, but not linked to a specific line) use the `create_note` action. The same keybindings for delete/edit/reply are available on the note tree. >lua require("gitlab").create_note() < When the 'wrap' option is on, line wrapping can make the discussion tree harder to read. You can use the 'breakindent' option to visually indent tree nodes at the same level. If you don't want to set 'breakindent' globally, you can set this only for the `gitlab` file type (the file type of discussions and notes). One way of doing this is by creating a file called $XDG_CONFIG_HOME/nvim/after/ftplugin/gitlab.lua with the following contents: >lua vim.o.breakindent = true < LABELS *gitlab.nvim.labels* You can add or remove labels from the current MR. >lua require("gitlab").add_label() require("gitlab").delete_label() These labels will be visible in the summary panel, as long as you provide the "fields" string in your setup function under the `setting.info.fields` block. SIGNS AND DIAGNOSTICS *gitlab.nvim.signs-and-diagnostics* By default when reviewing files, you will see diagnostics for comments that have been added to a review. These are the default settings: >lua discussion_signs = { enabled = true, -- Show diagnostics for gitlab comments in the reviewer skip_resolved_discussion = false, -- Show diagnostics for resolved discussions severity = vim.diagnostic.severity.INFO, -- ERROR, WARN, INFO, or HINT virtual_text = false, -- Whether to show the comment text inline as floating virtual text use_diagnostic_signs = true, -- Show diagnostic sign (depending on the `severity` setting, e.g., I for INFO) along with the comment icon priority = 100, -- Higher will override LSP warnings, etc icons = { comment = "→|", range = " |", }, }, When the cursor is on a diagnostic line you can view the discussion thread by using `vim.diagnostic.show()`. You can also jump to the discussion tree for the given comment: >lua require("gitlab").move_to_discussion_tree_from_diagnostic() Since nvim 0.10 you can use these two function anywhere in the diagnostic range. In previous versions, you have to move the cursor to the first line of the diagnostic. You may skip resolved discussions by toggling `discussion_signs.skip_resolved_discussion` in your setup function to `true`. By default, discussions from this plugin are shown at the INFO severity level (see :h vim.diagnostic.severity). EMOJIS *gitlab.nvim.emojis* You can add or remove emojis from a note or comment in the discussion tree. To see who has reacted with an emoji, hover over the emoji. A popup will appear with anyone who has responded with that emoji. You can only delete emojis that you have responded with. UPLOADING FILES *gitlab.nvim.uploading-files* To attach a file to an MR description, reply, comment, and so forth use the `keymaps.popup.perform_linewise_action` keybinding when the popup is open. This will open a picker that will look for files in the directory you specify in the `settings.attachment_dir` folder (this must be an absolute path). When you have picked the file, it will be added to the current buffer at the current line. Use the `keymaps.popup.perform_action` to send the changes to Gitlab. MR APPROVALS *gitlab.nvim.mr-approvals* You can approve or revoke approval for an MR with the `approve` and `revoke` actions respectively: >lua require("gitlab").approve() require("gitlab").revoke() < MERGING AN MR *gitlab.nvim.merging-an-mr* The `merge` action will merge an MR. The MR must be in a "mergeable" state for this command to work. >lua require("gitlab").merge() require("gitlab").merge({ squash = false, delete_branch = false }) < See |gitlab.nvim.merge| for more help on this function. CREATING AN MR *gitlab.nvim.creating-an-mr* To create an MR for the current branch, make sure you have the branch checked out. Then, use the `create_mr` action. See |gitlab.nvim.create_mr| for more help on this function >lua require("gitlab").create_mr() require("gitlab").create_mr({ target = "main" }) require("gitlab").create_mr({ template_file = "my-template.md", title = "Fix bug XYZ" }) < PIPELINES *gitlab.nvim.pipelines* You can view the status of the pipeline for the current MR with the `pipeline` action. >lua require("gitlab").pipeline() < To re-trigger failed jobs in the pipeline manually, use the `keymaps.popup.perform_action` keybinding. To open the log trace of a job in a new Neovim buffer, use your `keymaps.popup.perform_linewise_action` keybinding. REVIEWERS AND ASSIGNEES *gitlab.nvim.reviewers-and-assignees* The `add_reviewer` and `delete_reviewer` actions, as well as the `add_assignee` and `delete_assignee` functions, will let you choose from a list of users who are available in the current project: >lua require("gitlab").add_reviewer() require("gitlab").delete_reviewer() require("gitlab").add_assignee() require("gitlab").delete_assignee() < These actions use Neovim’s built in picker, which is much nicer if you install `dressing.nvim`. If you use Dressing, please enable it: >lua require("dressing").setup({ input = { enabled = true } }) < RESTARTING THE GO SERVER *gitlab.nvim.restarting* The `gitlab.nvim` server will shut down automatically when you exit Neovim. You may restart the server at any time via the the `restart` command: >lua require("gitlab.server").restart() < KEYBINDINGS *gitlab.nvim.keybindings* The `gitlab.nvim` plugin sets up a number of default keybindings for the discussion tree, the popup windows and the reviewer windows, and also some global keybindings that are available in any buffer. You can find the defaults in the `keymaps` section of the configuration table (see |gitlab.nvim.configuring-the-plugin|) and you can see the current buffer-local mappings by pressing the `keymaps.help` keybinding (`g?` by default). The `help` mapping is not set in the reviewer windows which are managed by the Diffview plugin, see |diffview-config-keymaps|. You can set any of the mappings to whatever you want. You can also prevent the plugin from setting up any keybindings whatsoever, or any keybindings for individual buffers by setting `keymaps.disable_all`, `keymaps.global.disable_all`, `keymaps.popup.disable_all`, etc. to `true`. Alternatively, you can disable individual keybindings by setting the value of the field to `false`, e.g., `keymaps = {global {merge = false}}`, which will leave all the other keybindings in place. The global keymaps all use the `gl` prefix as it does not have a special meaning in normal mode. You can add your own global keybindings by calling something like this after the `gitlab.setup()` call: >lua local gitlab = require("gitlab") vim.keymap.set("n", "gl", gitlab.print_settings, { desc = "Print gitlab.nvim settings"}) < See |gitlab.nvim.api| for an overview of available API functions that you can use in your mappings. If you want to set up your own additional keybindings for the discussion tree, you can put them in the `$XDG_CONFIG_HOME/nvim/after/ftplugin/gitlab.lua` file. E.g., if you wanted to use the `j` and `k` keys to move to the next discussion node instead of the next line, you could add to the |ftplugin| file the following lines: >lua vim.keymap.set("n", "j", [[call search('[] @')]], { buffer = 0, desc = "Go to next node" }) vim.keymap.set("n", "k", [[call search('[] @', 'b')]], { buffer = 0, desc = "Go to previous node" }) < Reviewer keybindings ~ Most of the keybindings `gitlab.nvim` sets are normal mode mappings, with the exception of `keymaps.reviewer.create_comment` and `keymaps.reviewer.create_suggestion` which work in both normal and visual mode. In normal mode, these keybindings are |operator|s that must be followed by a |motion|. Either the operator or the motion can be preceded by a count, so that `3sj` is equivalent to `s3j`, and they both create a comment for the current line and three more lines downwards. Similarly, both `2s`|ap| and `s2`|ap| create a suggestion for two "outer" paragraphs. The operators force |linewise| visual selection, so they work correctly even if the motion itself works |characterwise| (e.g., |i(| for selecting the inner parentheses block). To create a comment or suggestion for the current line, just duplicate the keybinding: `cc` and `ss`. This also accepts a count, so you can use `2cc` or `c2c` to create a comment on two lines. The same logic applies also when you change these keybindings, e.g., to something like `c`. The keybindings also work in visual mode, e.g., if you first want to make sure you are commenting on the right text segment/object, you can do `v4j` to visually select the current and the next 4 lines, followed by either `c` for a normal comment or `s` for a suggestion. NOTE: Due to limitations of the Nvim API, unlike with builtin operators `d`, `c`, etc., the operator count and motion count are NOT |multiplied|, so that the key presses `3s2s` are not equivalent to `6ss`, but result in `s32s`. Delay in keybindings ~ You may experience a lag in some of the keybindings, because you have existing keybinding starting with they same key(s). You can force the `gitlab.nvim` mapping to use |nowait| and fire immediately (and lose your other mapping for this buffer) by adding a special field called `nowait` to your keymap. For example, if the name of the keybinding is `reviewer.create_comment`, then you add the following to your config: >lua keymaps = { reviewer = { create_comment_nowait = true }} < TROUBLESHOOTING *gitlab.nvim.troubleshooting* To check the health of the plugin and related dependencies, please run: >vim :checkhealth gitlab < To print your current settings: >lua require("gitlab").print_settings() < This plugin uses a Go server to reach out to Gitlab. It’s possible that something is going wrong when starting that server or connecting with Gitlab. The Go server runs outside of Neovim, and can be interacted with directly in order to troubleshoot. To start the server, check out your feature branch and run these commands: >lua require("gitlab.server").build(true) require("gitlab.server").start(function() print("Server started") end) < The easiest way to debug what’s going wrong is to turn on the `debug` options in your setup function. This will allow you to see requests leaving the Go server, and the responses coming back from Gitlab. Once the server is running, you can also interact with the Go server like any other process: > curl --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" localhost:21036/mr/info < ============================================================================== LUA API *gitlab.nvim.api* *gitlab.nvim.setup* gitlab.setup() ~ Call this first to initialize the plugin. With no arguments, it will use the default arguments outlined under "Configuring the Plugin". >lua require("gitlab").setup() require("gitlab").setup({ port = 8392 }) require("gitlab").setup({ discussion_tree = { blacklist = { "some_bot"} } }) < *gitlab.nvim.choose_merge_request* gitlab.choose_merge_request({opts}) ~ Choose a merge request from a list of those open in your current project to review. This command will automatically check out the feature branch locally and open the reviewer pane (this can be overridden with the `open_reviewer` parameter. You can also filter merge requests by specifying `label` and `notlabel` parameters, or any other parameter included in list MRs API. By default, the endpoint will return all open merge requests. >lua require("gitlab").choose_merge_request() require("gitlab").choose_merge_request({ open_reviewer = false }) require("gitlab").choose_merge_request({ labels = {"include_mrs_with_label"} }) require("gitlab").choose_merge_request({ ["[not]labels"] = {"exclude_mrs_with_label"} }) < Parameters: ~ • {opts}: (table|nil) • {open_reviewer}: (boolean) Whether to open the reviewer after switching branches. True by default. • {labels}: (table) Return merge requests with *including* matching labels • Etc, see: https://docs.gitlab.com/ee/api/merge_requests.html#list-merge-requests *gitlab.nvim.choose_merge_request_by_username* gitlab.choose_merge_request_by_username({opts}) ~ Choose a merge request based on the username provided. Like the `choose_merge_request` action, this will automatically check out the branch locally and open the the reviewer pane when the MR is chosen. >lua require("gitlab").choose_merge_request_by_username({ username = "hcramer" }) < Parameters: ~ • {opts}: (table|nil) • {username}: (string) The username of the Gitlab user, must be a member of the current project. • {state} [optional]: (string) The status of the MR, e.g. "opened" or "all" *gitlab.nvim.review* gitlab.review() ~ Opens the reviewer pane. Can be used from anywhere within Neovim after the plugin is loaded. If run twice, will open a second reviewer pane. >lua require("gitlab").review() < *gitlab.nvim.summary* gitlab.summary() ~ Opens the summary window with information about the current MR, such as the description, the author, and the title. Can be configured via the `info` field in the setup call. >lua require("gitlab").summary() The summary can be edited. Once you have made changes, send them to Gitlab via the `keymaps.popup.perform_action` keybinding. *gitlab.nvim.approve* gitlab.approve() ~ Approves the current MR. Will error if the current user does not have permission. >lua require("gitlab").approve() < *gitlab.nvim.revoke* gitlab.revoke() ~ Revokes approval for the current MR. Will error if the current user does not have permission or has not previously approved the MR. >lua require("gitlab").approve() < *gitlab.nvim.create_comment* gitlab.create_comment() ~ Opens a popup to create a comment on the current line. Must be called when focused on the reviewer pane (see the gitlab.nvim.review command), otherwise it will error. >lua require("gitlab").create_comment() After the comment is typed, submit it to Gitlab via the `keymaps.popup.perform_action` keybinding, by default `ZZ`. *gitlab.nvim.create_multiline_comment* gitlab.create_multiline_comment() ~ Opens a popup to create a multi-line comment. May only be called in visual mode, and will use the currently selected lines. >lua require("gitlab").create_multiline_comment() After the comment is typed, submit it to Gitlab via the `keymaps.popup.perform_linewise_action` keybinding, by default `ZA`. *gitlab.nvim.create_comment_suggestion* gitlab.create_comment_suggestion() ~ Opens a popup to create a comment suggestion (aka a comment that makes a committable change suggestion to the currently selected lines). >lua require("gitlab").create_multiline_comment() After the comment is typed, submit it to Gitlab via the `keymaps.popup.perform_linewise_action` keybinding, by default `ZA`. *gitlab.nvim.create_mr* gitlab.create_mr({opts}) ~ Starts the process of creating an MR for the currently checked out branch. >lua require("gitlab").create_mr() require("gitlab").create_mr({ target = "main" }) require("gitlab").create_mr({ target = "main", template_file = "my-template.md" }) require("gitlab").create_mr({ title = "Fix bug XYZ", description = "Closes #123" }) < Parameters: ~ • {opts}: (table|nil) Keyword arguments that can be used to skip certain steps in the MR creation process. `target` and `template_file` can also be configured via the `gitlab.setup()` function in the `settings.create_mr` field. If any field is missing, you will be prompted to select a value interactively: • {target}: (string) Name of the target branch. • {template_file}: (string) Name of file (relative to `.gitlab/merge_request_templates`) that will be used for the MR description. See also . • {description}: (string) String used for the MR description. Takes precedence over the {template_file}, if both options are used. • {title}: (string) MR title. • {delete_branch}: (bool) If true, the source branch will be marked for deletion. • {squash}: (bool) If true, the commits will be marked for squashing. After selecting all necessary details, you'll be presented with a confirmation window. You can cycle through the individual fields with the keymaps defined in `keymaps.popup.next_field` and `keymaps.popup.prev_field`. Both keymaps accept a count, i.g., 2 goes to the 2nd next field. In the "Delete source branch", "Squash commits", and "Target branch" fields, you can use the `keymaps.popup.perform_linewise_action` keymap to either toggle the Boolean value or to select a new target branch, respectively. Use the `keymaps.popup.perform_action` keymap to POST the MR to Gitlab. *gitlab.nvim.move_to_discussion_tree_from_diagnostic* gitlab.move_to_discussion_tree_from_diagnostic() ~ When hovering over a diagnostic in the reviewer pane, jumps to the relevant node in the discussion tree. >lua require("gitlab").move_to_discussion_tree_from_diagnostic() If there are no diagnostics for the current line, shows a warning message. *gitlab.nvim.create_note* gitlab.create_note() ~ Opens a popup to create a note. Notes are like comments except they are not tied to specific changes in an MR. >lua require("gitlab").create_note() After the comment is typed, submit it to Gitlab via the `keymaps.popup.perform_action` keybinding, by default `ZZ`. *gitlab.nvim.toggle_discussions* gitlab.toggle_discussions() ~ Toggles visibility of the discussion tree. >lua require("gitlab").toggle_discussions() Once the discussion tree is open, a number of different keybindings are available for interacting with different discussions. Please see the `keymaps.discussion_tree` section of the setup call for more information about different keybindings. *gitlab.nvim.publish_all_drafts* gitlab.publish_all_drafts() ~ Publishes all unpublished draft notes. Used to finish a review and make all notes and comments visible. >lua require("gitlab").publish_all_drafts() < *gitlab.nvim.toggle_draft_mode* gitlab.toggle_draft_mode() ~ Toggles between draft mode, where comments and notes are added to a review as drafts, and regular (or live) mode, where comments are posted immediately. *gitlab.nvim.toggle_sort_method* gitlab.toggle_sort_method() ~ Toggles whether the discussion tree is sorted by the "latest_reply", with threads with the most recent activity on top (the default), or by "original_comment", with the oldest threads on top. *gitlab.nvim.add_assignee* gitlab.add_assignee() ~ Opens up a select menu for choosing an assignee for the current merge request. >lua require("gitlab").add_assignee() < *gitlab.nvim.delete_assignee* gitlab.delete_assignee() ~ Opens up a select menu for removing an existing assignee for the current merge request. >lua require("gitlab").delete_assignee() < *gitlab.nvim.add_reviewer* gitlab.add_reviewer() ~ Opens up a select menu for adding a reviewer for the current merge request. >lua require("gitlab").add_reviewer() < *gitlab.nvim.add_label* gitlab.add_label() ~ Opens up a select menu for adding a label to the current merge request. >lua require("gitlab").add_label() < *gitlab.nvim.delete_label* gitlab.delete_label() ~ Opens up a select menu for removing an existing label from the current merge request. >lua require("gitlab").delete_label() < *gitlab.nvim.delete_reviewer* gitlab.delete_reviewer() ~ Opens up a select menu for removing an existing reviewer for the current merge request. >lua require("gitlab").delete_reviewer() < *gitlab.nvim.pipeline* gitlab.pipeline() ~ Opens up a popup with information about the pipeline for the current merge request. >lua require("gitlab").pipeline() < To re-trigger failed jobs in the pipeline manually, use the `keymaps.popup.perform_action` keybinding. To open the log trace of a job in a new Neovim buffer, use your `keymaps.popup.perform_linewise_action` keybinding. *gitlab.nvim.open_in_browser* gitlab.open_in_browser() ~ Opens the current MR in your default web browser. >lua require("gitlab").open_in_browser() < *gitlab.nvim.copy_mr_url* gitlab.copy_mr_url() ~ Copies the URL of the current MR to system clipboard. >lua require("gitlab").copy_mr_url() < *gitlab.nvim.merge* gitlab.merge({opts}) ~ Merges the merge request into the target branch. When run without any arguments, the `merge` action will respect the "Squash commits" and "Delete source branch" settings set by `require("gitlab").create_mr()` or set in Gitlab online. You can see the current settings in the Summary view, see |gitlab.nvim.the-summary-view|. >lua require("gitlab").merge() require("gitlab").merge({ squash = false, delete_branch = true }) < Parameters: ~ • {opts}: (table|nil) Keyword arguments that can be used to override default behavior. • {delete_branch}: (bool) If true, the source branch will be deleted. • {squash}: (bool) If true, the commits will be squashed. If you enable {squash} you will be prompted for a squash message. To use the default message, leave the popup empty. Use the `keymaps.popup.perform_action` to merge the MR with your message. *gitlab.nvim.data* gitlab.data({resources}, {cb}) ~ The data function can be used to integrate `gitlab.nvim` with other plugins and tooling, by fetching raw data about the current MR, including the summary information (title, description, etc); reviewers, assignees, pipeline status. >lua require("gitlab").data({ { type = "info", refresh = false }, { type = "user", refresh = false } }, function (data) vim.print("The info data is: ", data.info) vim.print("The user data is: ", data.user) end) If the resources have not yet been fetched from Gitlab, this function will perform API calls for them. Once the data has been fetched, the callback will execute and passed the data as an argument. Parameters: ~ • {resources}: (table) A list of {resource} blocks to fetch. • {resource}: (table) A resource to fetch, such as job information, etc. The resource is defined by its {type}: • {type}: (string) The type of resource, either: • "user": Information about the currently authenticated user. • "labels": The labels available in the current project. • "project_members": The list of current project members. • "revisions": Revision information about the MR. • "pipeline": Information about the current branch's pipeline. Returns and object with `latest_pipeline` and `jobs` as fields. • "draft_notes": The current user's unpublished notes • {refresh}: (bool) Whether to re-fetch the data from Gitlab or use the cached data locally, if available. • {cb}: (function) The callback function that runs after all of the resources have been fetched. Will be passed a table with the data, with each resource as a key-value pair, with the key being it's type. *gitlab.nvim.refresh_data* gitlab.refresh_data() ~ Fetches discussion tree data from Gitlab and refreshes the tree views. It can be used in an autocommand to refresh the data every time you enter the discussion tree. This exmaple shows how to easily limit the refresh rate to at least 10 seconds: >lua local last_updated = os.time() local gitlab = vim.api.nvim_create_augroup("Gitlab", {}) vim.api.nvim_create_autocmd("BufEnter", { group = gitlab, callback = function() if vim.bo.filetype == "gitlab" and os.time() - last_updated > 10 then require("gitlab").refresh_data() last_updated = os.time() end end }) < vim:tw=78:ts=4:sw=4:expandtab:ft=help:norl: