-
Notifications
You must be signed in to change notification settings - Fork 42
/
Copy pathgitlab.nvim.txt
1078 lines (920 loc) · 48.9 KB
/
gitlab.nvim.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*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 = {
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 = "<Tab>", -- Cycle to the next field. Accepts |count|.
prev_field = "<S-Tab>", -- 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_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 = "<C-R>", -- Refresh the data in the view by hitting Gitlab's APIs again
print_node = "<leader>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 "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
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",
},
},
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
<https://docs.gitlab.com/ee/user/project/merge_requests/reviews/suggestions.html>
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<c-s>", 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", [[<Cmd>call search('[] @')<CR>]], { buffer = 0, desc = "Go to next node" })
vim.keymap.set("n", "k", [[<Cmd>call search('[] @', 'b')<CR>]], { 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 `<leader>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<string>) 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
<https://docs.gitlab.com/ee/user/project/description_templates.html>.
• {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<Tab> 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.