GitHub in NeoVim.
- β¨ Features
- β‘οΈ Requirements
- π¦ Installation
- βοΈ Configuration
- π Usage
- π€ Commands
- π₯ Examples
- π PR reviews
- π Completion
- π¨ Colors
- π·οΈ Status Column
- π FAQ
- β Contributing
- π License
- Edit GitHub issues and PRs
- Add/Modify/Delete comments
- Add/Remove label, reactions, assignees, project cards, reviewers, etc.
- Add Review PRs
- Install GitHub CLI
- Install plenary.nvim
- Install telescope.nvim
- Install nvim-web-devicons
Use your favourite plugin manager to install it. eg:
use {
'pwntester/octo.nvim',
requires = {
'nvim-lua/plenary.nvim',
'nvim-telescope/telescope.nvim',
'kyazdani42/nvim-web-devicons',
},
config = function ()
require"octo".setup()
end
}
require"octo".setup({
default_remote = {"upstream", "origin"}; -- order to try remotes
ssh_aliases = {}, -- SSH aliases. e.g. `ssh_aliases = {["github.com-work"] = "github.com"}`
reaction_viewer_hint_icon = "ο"; -- marker for user reactions
user_icon = "ο½ "; -- user icon
timeline_marker = "ο "; -- timeline marker
timeline_indent = "2"; -- timeline indentation
right_bubble_delimiter = "ξ΄"; -- bubble delimiter
left_bubble_delimiter = "ξΆ"; -- bubble delimiter
github_hostname = ""; -- GitHub Enterprise host
snippet_context_lines = 4; -- number or lines around commented lines
gh_env = {}, -- extra environment variables to pass on to GitHub CLI, can be a table or function returning a table
timeout = 5000, -- timeout for requests between the remote server
ui = {
use_signcolumn = true, -- show "modified" marks on the sign column
},
issues = {
order_by = { -- criteria to sort results of `Octo issue list`
field = "CREATED_AT", -- either COMMENTS, CREATED_AT or UPDATED_AT (https://docs.github.com/en/graphql/reference/enums#issueorderfield)
direction = "DESC" -- either DESC or ASC (https://docs.github.com/en/graphql/reference/enums#orderdirection)
}
},
pull_requests = {
order_by = { -- criteria to sort the results of `Octo pr list`
field = "CREATED_AT", -- either COMMENTS, CREATED_AT or UPDATED_AT (https://docs.github.com/en/graphql/reference/enums#issueorderfield)
direction = "DESC" -- either DESC or ASC (https://docs.github.com/en/graphql/reference/enums#orderdirection)
},
always_select_remote_on_create = "false" -- always give prompt to select base remote repo when creating PRs
},
file_panel = {
size = 10, -- changed files panel rows
use_icons = true -- use web-devicons in file panel (if false, nvim-web-devicons does not need to be installed)
},
mappings = {
issue = {
close_issue = { lhs = "<space>ic", desc = "close issue" },
reopen_issue = { lhs = "<space>io", desc = "reopen issue" },
list_issues = { lhs = "<space>il", desc = "list open issues on same repo" },
reload = { lhs = "<C-r>", desc = "reload issue" },
open_in_browser = { lhs = "<C-b>", desc = "open issue in browser" },
copy_url = { lhs = "<C-y>", desc = "copy url to system clipboard" },
add_assignee = { lhs = "<space>aa", desc = "add assignee" },
remove_assignee = { lhs = "<space>ad", desc = "remove assignee" },
create_label = { lhs = "<space>lc", desc = "create label" },
add_label = { lhs = "<space>la", desc = "add label" },
remove_label = { lhs = "<space>ld", desc = "remove label" },
goto_issue = { lhs = "<space>gi", desc = "navigate to a local repo issue" },
add_comment = { lhs = "<space>ca", desc = "add comment" },
delete_comment = { lhs = "<space>cd", desc = "delete comment" },
next_comment = { lhs = "]c", desc = "go to next comment" },
prev_comment = { lhs = "[c", desc = "go to previous comment" },
react_hooray = { lhs = "<space>rp", desc = "add/remove π reaction" },
react_heart = { lhs = "<space>rh", desc = "add/remove β€οΈ reaction" },
react_eyes = { lhs = "<space>re", desc = "add/remove π reaction" },
react_thumbs_up = { lhs = "<space>r+", desc = "add/remove π reaction" },
react_thumbs_down = { lhs = "<space>r-", desc = "add/remove π reaction" },
react_rocket = { lhs = "<space>rr", desc = "add/remove π reaction" },
react_laugh = { lhs = "<space>rl", desc = "add/remove π reaction" },
react_confused = { lhs = "<space>rc", desc = "add/remove π reaction" },
},
pull_request = {
checkout_pr = { lhs = "<space>po", desc = "checkout PR" },
merge_pr = { lhs = "<space>pm", desc = "merge commit PR" },
squash_and_merge_pr = { lhs = "<space>psm", desc = "squash and merge PR" },
list_commits = { lhs = "<space>pc", desc = "list PR commits" },
list_changed_files = { lhs = "<space>pf", desc = "list PR changed files" },
show_pr_diff = { lhs = "<space>pd", desc = "show PR diff" },
add_reviewer = { lhs = "<space>va", desc = "add reviewer" },
remove_reviewer = { lhs = "<space>vd", desc = "remove reviewer request" },
close_issue = { lhs = "<space>ic", desc = "close PR" },
reopen_issue = { lhs = "<space>io", desc = "reopen PR" },
list_issues = { lhs = "<space>il", desc = "list open issues on same repo" },
reload = { lhs = "<C-r>", desc = "reload PR" },
open_in_browser = { lhs = "<C-b>", desc = "open PR in browser" },
copy_url = { lhs = "<C-y>", desc = "copy url to system clipboard" },
goto_file = { lhs = "gf", desc = "go to file" },
add_assignee = { lhs = "<space>aa", desc = "add assignee" },
remove_assignee = { lhs = "<space>ad", desc = "remove assignee" },
create_label = { lhs = "<space>lc", desc = "create label" },
add_label = { lhs = "<space>la", desc = "add label" },
remove_label = { lhs = "<space>ld", desc = "remove label" },
goto_issue = { lhs = "<space>gi", desc = "navigate to a local repo issue" },
add_comment = { lhs = "<space>ca", desc = "add comment" },
delete_comment = { lhs = "<space>cd", desc = "delete comment" },
next_comment = { lhs = "]c", desc = "go to next comment" },
prev_comment = { lhs = "[c", desc = "go to previous comment" },
react_hooray = { lhs = "<space>rp", desc = "add/remove π reaction" },
react_heart = { lhs = "<space>rh", desc = "add/remove β€οΈ reaction" },
react_eyes = { lhs = "<space>re", desc = "add/remove π reaction" },
react_thumbs_up = { lhs = "<space>r+", desc = "add/remove π reaction" },
react_thumbs_down = { lhs = "<space>r-", desc = "add/remove π reaction" },
react_rocket = { lhs = "<space>rr", desc = "add/remove π reaction" },
react_laugh = { lhs = "<space>rl", desc = "add/remove π reaction" },
react_confused = { lhs = "<space>rc", desc = "add/remove π reaction" },
},
review_thread = {
goto_issue = { lhs = "<space>gi", desc = "navigate to a local repo issue" },
add_comment = { lhs = "<space>ca", desc = "add comment" },
add_suggestion = { lhs = "<space>sa", desc = "add suggestion" },
delete_comment = { lhs = "<space>cd", desc = "delete comment" },
next_comment = { lhs = "]c", desc = "go to next comment" },
prev_comment = { lhs = "[c", desc = "go to previous comment" },
select_next_entry = { lhs = "]q", desc = "move to previous changed file" },
select_prev_entry = { lhs = "[q", desc = "move to next changed file" },
close_review_tab = { lhs = "<C-c>", desc = "close review tab" },
react_hooray = { lhs = "<space>rp", desc = "add/remove π reaction" },
react_heart = { lhs = "<space>rh", desc = "add/remove β€οΈ reaction" },
react_eyes = { lhs = "<space>re", desc = "add/remove π reaction" },
react_thumbs_up = { lhs = "<space>r+", desc = "add/remove π reaction" },
react_thumbs_down = { lhs = "<space>r-", desc = "add/remove π reaction" },
react_rocket = { lhs = "<space>rr", desc = "add/remove π reaction" },
react_laugh = { lhs = "<space>rl", desc = "add/remove π reaction" },
react_confused = { lhs = "<space>rc", desc = "add/remove π reaction" },
},
submit_win = {
approve_review = { lhs = "<C-a>", desc = "approve review" },
comment_review = { lhs = "<C-m>", desc = "comment review" },
request_changes = { lhs = "<C-r>", desc = "request changes review" },
close_review_tab = { lhs = "<C-c>", desc = "close review tab" },
},
review_diff = {
add_review_comment = { lhs = "<space>ca", desc = "add a new review comment" },
add_review_suggestion = { lhs = "<space>sa", desc = "add a new review suggestion" },
focus_files = { lhs = "<leader>e", desc = "move focus to changed file panel" },
toggle_files = { lhs = "<leader>b", desc = "hide/show changed files panel" },
next_thread = { lhs = "]t", desc = "move to next thread" },
prev_thread = { lhs = "[t", desc = "move to previous thread" },
select_next_entry = { lhs = "]q", desc = "move to previous changed file" },
select_prev_entry = { lhs = "[q", desc = "move to next changed file" },
close_review_tab = { lhs = "<C-c>", desc = "close review tab" },
toggle_viewed = { lhs = "<leader><space>", desc = "toggle viewer viewed state" },
},
file_panel = {
next_entry = { lhs = "j", desc = "move to next changed file" },
prev_entry = { lhs = "k", desc = "move to previous changed file" },
select_entry = { lhs = "<cr>", desc = "show selected changed file diffs" },
refresh_files = { lhs = "R", desc = "refresh changed files panel" },
focus_files = { lhs = "<leader>e", desc = "move focus to changed file panel" },
toggle_files = { lhs = "<leader>b", desc = "hide/show changed files panel" },
select_next_entry = { lhs = "]q", desc = "move to previous changed file" },
select_prev_entry = { lhs = "[q", desc = "move to next changed file" },
close_review_tab = { lhs = "<C-c>", desc = "close review tab" },
toggle_viewed = { lhs = "<leader><space>", desc = "toggle viewer viewed state" },
}
}
})
Just edit the issue title, body or comments as a regular buffer and use :w(rite)
to sync the issue with GitHub.
There is only an Octo <object> <action> [arguments]
command:
If no command is passed, the argument to Octo
is treated as a URL from where an issue or pr repo and number are extracted
Object | Action | Arguments |
---|---|---|
issue | close | Close the current issue |
reopen | Reopen the current issue | |
create [repo] | Creates a new issue in the current or specified repo | |
edit [repo] | Edit issue <number> in current or specified repo |
|
list [repo] [key=value] (1) | List all issues satisfying given filter | |
search | Live issue search | |
reload | Reload issue. Same as doing e! |
|
browser | Open current issue in the browser | |
url | Copies the URL of the current issue to the system clipboard | |
pr | list [repo] [key=value] (2) | List all PRs satisfying given filter |
search | Live issue search | |
edit [repo] | Edit PR <number> in current or specified repo |
|
reopen | Reopen the current PR | |
create | Creates a new PR for the current branch | |
close | Close the current PR | |
checkout | Checkout PR | |
commits | List all PR commits | |
changes | Show all PR changes (diff hunks) | |
diff | Show PR diff | |
merge [commit|rebase|squash] [delete] | Merge current PR using the specified method | |
ready | Mark a draft PR as ready for review | |
checks | Show the status of all checks run on the PR | |
reload | Reload PR. Same as doing e! |
|
browser | Open current PR in the browser | |
url | Copies the URL of the current PR to the system clipboard | |
repo | list (3) | List repos user owns, contributes or belong to |
fork | Fork repo | |
browser | Open current repo in the browser | |
url | Copies the URL of the current repo to the system clipboard | |
view | Open a repo by path ({organization}/{name}) | |
gist | list [repo] [key=value] (4) | List user gists |
comment | add | Add a new comment |
delete | Delete a comment | |
thread | resolve | Mark a review thread as resolved |
unresolve | Mark a review thread as unresolved | |
label | add [label] | Add a label from available label menu |
remove [label] | Remove a label | |
create [label] | Create a new label | |
assignee | add [login] | Assign a user |
remove [login] | Unassign a user | |
reviewer | add [login] | Assign a PR reviewer |
reaction | thumbs_up | +1 |
Add π reaction |
thumbs_down | -1 |
Add π reaction | |
eyes |
Add π reaction | |
laugh |
Add π reaction | |
confused |
Add π reaction | |
rocket |
Add π reaction | |
heart |
Add β€οΈ reaction | |
hooray | party | tada |
Add π reaction | |
card | add | Assign issue/PR to a project new card |
remove | Delete project card | |
move | Move project card to different project/column | |
review | start | Start a new review |
submit | Submit the review | |
resume | Edit a pending review for current PR | |
discard | Deletes a pending review for current PR if any | |
comments | View pending review comments | |
commit | Pick a specific commit to review | |
close | Close the review window and return to the PR | |
actions | Lists all available Octo actions | |
search | Search GitHub for issues and PRs matching the query |
-
[repo]
: If repo is not provided, it will be derived from<cwd>/.git/config
. -
In-menu mappings:
<CR>
: Edit Issue<C-b>
: Opens issue in the browser<C-y>
: Copies URL to system clipboard
- since
- createdBy
- assignee
- mentioned
- labels
- milestone
- states
- In-menu mappings:
<CR>
: Edit PR<C-b>
: Opens PR in the browser<C-o>
: Checkout PR<C-y>
: Copies URL to system clipboard
- baseRefName
- headRefName
- labels
- states
- In-menu mappings:
<CR>
: View repo<C-b>
: Opens repo in the browser<C-y>
: Copies URL to system clipboard
- In-menu mappings:
<CR>
: Append Gist to buffer Available keys:repo
|public
|secret
Octo https://github.com/pwntester/octo.nvim/issues/12
Octo issue create
Octo issue create pwntester/octo.nvim
Octo comment add
Octo reaction add hooray
Octo issue edit pwntester/octo.nvim 1
Octo issue edit 1
Octo issue list createdBy=pwntester
Octo issue list neovim/neovim labels=bug,help\ wanted states=OPEN
Octo search assignee:pwntester is:pr
- Open the PR (eg:
Octo <PR url>
orOcto pr list
orOcto pr edit <PR number>
) - Start a review with
Octo review start
or resume a pending review withOcto review resume
- A new tab will show a panel with changed files and two windows showing the diff on any of them.
- Change panel entries with
]q
and[q
or by selecting an entry in the window - Add comments with
<space>ca
or suggestions with<space>sa
on single or multiple visual-selected lines- A new buffer will appear in the alternate diff window. The cursor will be positioned in the new buffer
- When ready, save the buffer to commit changes to GitHub
- Move back to the diff window and move the cursor, the thread buffer will hide
- Hold the cursor on a line with a comment to show a thread buffer with all the thread comments
- To modify, delete, react or reply to a comment, move to the window containing the thread buffer
- Perform any operations as if you were in a regular issue buffer
- Review pending comments with
Octo review comments
- Use to jump to the selected pending comment
- If you want to review a specific commit, use
Octo review commit
to pick a commit. The file panel will get filtered to show only files changed by that commit. Any comments placed on these files will be applied at that specific commit level and will be added to the pending review. - When ready, submit the review with
Octo review submit
- A new float window will pop up. Enter the top level review comment and exit to normal mode. Then press
<C-m>
to submit a comment,<C-a>
to approve it or<C-r>
to request changes
Octo provides a built-in omnifunc completion for issues, PRs and users that you can trigger using <C-x><C-o>
. Alternately, if you use nvim-cmp
for completion, you can use the cmp-git
source to provide issues, PRs, commits and users completion.
Highlight Group | Defaults to |
---|---|
OctoDirty | ErrorMsg |
OctoIssueTitle | PreProc |
OctoIssueId | Question |
OctoEmpty | Comment |
OctoFloat | NormalNC |
OctoDate | Comment |
OctoSymbol | Comment |
OctoTimelineItemHeading | Comment |
OctoDetailsLabel | Title |
OctoMissingDetails | Comment |
OctoDetailsValue | Identifier |
OctoDiffHunkPosition | NormalFloat |
OctoCommentLine | TabLineSel |
OctoEditable | NormalFloat bg |
OctoViewer | GitHub color |
OctoBubble | NormalFloat |
OctoBubbleGreen | GitHub color |
OctoBubbleRed | GitHub color |
OctoUser | OctoBubble |
OctoUserViewer | OctoViewer |
OctoReaction | OctoBubble |
OctoReactionViewer | OctoViewer |
OctoPassingTest | GitHub color |
OctoFailingTest | GitHub color |
OctoPullAdditions | GitHub color |
OctoPullDeletions | GitHub color |
OctoPullModifications | GitHub color |
OctoStateOpen | GitHub color |
OctoStateClosed | GitHub color |
OctoStateMerge | GitHub color |
OctoStatePending | GitHub color |
OctoStateApproved | OctoStateOpen |
OctoStateChangesRequested | OctoStateClosed |
OctoStateCommented | Normal |
OctoStateDismissed | OctoStateClosed |
The term GitHub color
refers to the colors used in the WebUI.
The (addition) viewer
means the user of the plugin or more precisely the user authenticated via the gh
CLI tool used to retrieve the data from GitHub.
If you are using the vim.opt.statuscolumn
feature, you can disable Octo's comment marks in the signcolumn
and replace them with any customizations on the statuscolumn
.
Disable the signcolumn
with:
ui = {
use_signcolumn = false
}
Then, provide a statuscolumn
replacement such as:
local function mk_hl(group, sym)
return table.concat({ "%#", group, "#", sym, "%*" })
end
_G.get_statuscol_octo = function(bufnum, lnum)
if vim.api.nvim_buf_get_option(bufnum, "filetype") == "octo" then
if type(octo_buffers) == "table" then
local buffer = octo_buffers[bufnum]
if buffer then
buffer:update_metadata()
local hl = "OctoSignColumn"
local metadatas = {buffer.titleMetadata, buffer.bodyMetadata}
for _, comment_metadata in ipairs(buffer.commentsMetadata) do
table.insert(metadatas, comment_metadata)
end
for _, metadata in ipairs(metadatas) do
if metadata and metadata.startLine and metadata.endLine then
if metadata.dirty then
hl = "OctoDirty"
else
hl = "OctoSignColumn"
end
if lnum - 1 == metadata.startLine and lnum - 1 == metadata.endLine then
return mk_hl(hl, "[ ")
elseif lnum - 1 == metadata.startLine then
return mk_hl(hl, "β ")
elseif lnum - 1 == metadata.endLine then
return mk_hl(hl, "β ")
elseif metadata.startLine < lnum - 1 and lnum - 1 < metadata.endLine then
return mk_hl(hl, "β ")
end
end
end
end
end
end
return " "
end
vim.opt.statuscolumn = "%{%v:lua.get_statuscol_octo(bufnr(), v:lnum)%}"
How can I disable bubbles for XYZ?
Each text-object that makes use of a bubble (except labels) do use their own highlight group that linkes per default to the main bubble highlight group. To disable most bubbles at once you can simply link OctoBubble
to Normal
. To only disable them for a certain plain do the same for the specific sub-group (e.g. OctoUser
).
Why do my issue titles or markdown syntax do not get highlighted properly?
The title, body and comments of an issue or PR are special as they get special highlighting applied and is an editable section. Due to the latter property it gets the OctoEditable
highlighting via a special signs linehl
setting. This takes precedence over the buffer internal highlights. To only get the background highlighted by the editable section, set OctoEditable
to a highlight with a background color definition only.
Why am I getting authentication error from gh?
This means that are either using a GITHUB_TOKEN to authenticate or gh
is not authenticated.
In case of the former, run:
GITHUB_TOKEN= gh auth login
... and choose a method to authorise access for gh
.
gh
must store the creds so it can work in a subshell.
Can I use treesitter markdown parser with octo buffers?
Just add the following lines to your TreeSitter config:
local ft_to_parser = require "nvim-treesitter.parsers".filetype_to_parsername
ft_to_parser.octo = "markdown"
If you are using nvim 0.9 (nightly) use the following instead:
vim.treesitter.language.register('markdown', 'octo')
How can I filter PRs by filter keys that aren't available?
You can use the search command :Octo search [query]
.
The search syntax
and available search terms are available in GitHub documentation.
For example to search for PRs with author you can use this command:
:Octo search is:pr author:pwntester repo:github/codeql
Note: You need to provide the repo
, otherwise it will search for every PR by that user.
How to enable autocompletion for issues/prs (#
) and users (@
)?
Add the following mappings for octo
file type:
vim.api.nvim_buf_set_keymap(0, "i", "@", "@<C-x><C-o>", { silent = true, noremap = true })
vim.api.nvim_buf_set_keymap(0, "i", "#", "#<C-x><C-o>", { silent = true, noremap = true })
Contributions are always welcome!
See CONTRIBUTING
for ways to get started.
Please adhere to this project's CODE_OF_CONDUCT
.
The PR review panel is heavily inspired in diffview.nvim