Use GitHub in Vim/Neovim

skanehira — Sun, 14 Feb 2021 10:11:22 +0000

Currently I developing Vim plugin named gh.vim for GitHub.

This plugin can use some features of GitHub in Vim/Neovim.
For instance, you can see issue list, create new issue and see GitHub Actions status.

Today, I'll introduce how to use it and how it's convenience.

Why not browser?

I think everyone would thoughs "Why doesn't use browser?".
The answer is "Because I don't want go out of Vim".
I'm using Vim for coding, write articles and do others, I'd like to do as much other work in Vim as possible.
This reason is why I develop gh.vim.

Concept

Keep minimal dependencies, you just need curl.
Just provide virtual buffer and keymaps, no any commands.

The minimal is good thing because it would make things to be simple.
This is also my philosophy.

Features

Currently, gh.vim has features as bellow.

issues
- create/edit/close/open/list
issue comments
- create/edit/list
pull request
- diff/list
repository
- list/show README
project
- list/card list/move card
github actions
- list/open job logs
file tree
- open file
gist
- list/edit/create

How to use gh.vim

gh.vim just provides virtual buffers like gh://:owner/:repo/issues, no any commands.

:owner is user name or organization name, :repo is repository name.

If you want to see issue list, please open buffer like bellow.

:e gh://skanehira/gh.vim/issues

Next, I'll introduce main features and how to use it.

Issue list

If you want to see all issues in specified repository, you open buffer like bellow.

:e gh://skanehira/gh.vim/issues?state=all

Issue list will show in opend buffer like screenshot.

Issue list items is bellow.

  issue status                issue title                                                                    labels                          comments
       ↓                           ↓                                                                           ↓                                ↓
#102 closed @yoshio15  cannot create new issue when your repository doesn't have any issue template (bug, good first issue)                     2
  ↑             ↑
issue number  author

Issue prview

If you want to see issue body, you can show preview window with keymap gup.

You can Use <C-n>/<C-p> to scroll preview window when if issue body is long.

Issue edit

If you want to edit issue body, you can oepn edit buffer with keymap ghe in issue list.
Then, gh.vim would ask you how to open buffer as bellow. Please choise e/n/v/t to open new buffer.

[gh.vim] (e)dit, (n)ew, (v)new, (t)abnew:

The issue edit buffer name is gh://:owner/:repo/issues/:number, you also can open this buffer directly.

When your edit is finish, save buffer with :w and issue would be updated.

Issue select

You can Use <C-j>/<C-k> to select multiple issues.
If issue be selected, Then * would added the end of line.

Also, you can and use ghy can yank selected issue's URL.
And use <C-o> can open selected issues in browser.

ghy and <C-o> also can use to single issue when not issues selected

Issue comment list

You can use ghm to open issue comment list buffer, The buffer name is gh://:owner/:repo/issues/:number/comments.
Also you can open comment list buffer directly like as issue edit buffer.

commnet list buffer is same as issue list buffer.
You can open edit comment buffer with ghe, yank urls and open in browser.

Pull Request list

If you want to see all PRs in specified repository, you open buffer like bellow.

:e gh://skanehira/gh.vim/pulls?state=all

PR list will show in opend buffer like screenshot.

PR list items is same as issue list buffer.

In this buffer, you can use some features as bellow.

keymap	description
`<C-h>`	Show previous page
`<C-l>`	Show next page
`<C-o>`	Open selected PR in browser
`ghy`	Yank selected PR URLs.
`ghd`	Show PRs diff contents

Bellow screenshot is showing PR's diff contents.

Also you can open PR diff buffer directly.

gh://:owner/:repo/pulls/:number/diff

Projects

gh.vim providing Project buffer, you can see cards at project buffer. The buffer name is gh://projects/:id/columns, you can open that directly.

Also You can open from Project list buffer named gh://:repo/:owner/projects.
If you use project to manage tasks, you would like this feature.

In this buffer, you can do some things as bellow.

keymap	description
`<C-o>`	Open card in browser(currently only support issue)
`gho`	Open edit buffer(currently only support issue)
`ghm`	Move selected cards to current column
`ghy`	Yank selected cards URL

Bellow screenshot is example that move card to current column.

GitHub Actions

If you using GitHub Actions to do someting, This features would help you.
gh.vim providing GitHub Actions buffer can see job status and logs.
The buffer name is gh://:owner/:repo/actions.

The buffer's UI is bellow.

- clipboard-image                                             <-- repository name
| - ✗ add github actions... @skanehira [add-github-actions]   <-- workflow
| | - ✗ Test (ubuntu-latest)                                  <-- job
| | | | ✓ #1 Set up job                                       <-+
| | | | ✓ #2 Run actions/checkout@v2                            |
| | | | ✓ #3 Run actions/setup-go@v2                            | job steps
| | | | ✓ #4 install xclip                                      |
| | | | ✗ #5 Test                                               |
| | | | ✓ #10 Post Run actions/checkout@v2                      |
| | | | ✓ #11 Complete job                                    <-+

Workflow line items is bellow.

result comment message   author       branch name
↓        ↓                 ↓              ↓
✓ add github actions... @skanehira [add-github-actions]
✗ add github actions... @skanehira [add-github-actions]

In this buffer, you can do some things as bellow.

keymap	description
`<C-o>`	Open selected workflows, jobs in browser
`ghy`	Yank selected workflows,jobs URL
`gho`	Open selected job logs

Bellow screenshot is example that checking status and logs.

Gist list

You can open gh://:owner/gists to see gist list.

In this buffer, you can do someting as bellow.

keymap	description
`<C-o>`	Open selected gists in browser
`ghy`	Yank selected gists URL
`ghe`	Oepn edit gist buffer
`ghf`	Get more gists
`ghp`	Open/Close preview window

If you want to create new gist, you can open buffer named gh://:owner/gists/new/:file, and edit in buffer.
If you open multiple new gist buffer, then those buffer will created as a same gist.

Buffers

Currently gh.vim providing buffer list is bellow.
You can refer help with :h gh-buffer.

buffer	description
`gh://:owner/:repo/issues[?state=open&..]`	issue list
`gh://:owner/:repo/issues/:number`	edit issue
`gh://:owner/:repo/issues/new`	new issue
`gh://:owner/:repo/issues/:number/comments[?page=1&..]`	issue comment list
`gh://:owner/:repo/issues/:number/comments/new`	new issue comment
`gh://:owner/:repo/issues/:number/comments/:id`	edit issue comment
`gh://:owner/repos`	repository list
`gh://user/repos`	authenticated user repository list
`gh://:owner/:repo/readme`	repository readme
`gh://:owner/:repo/pulls[?state=open&...]`	pull request list
`gh://:owner/:repo/pulls/:number/diff`	pull request list diff
`gh://:owner/:repo/projects`	project list
`gh://orgs/:org/projects`	organization project list
`gh://projects/:id/columns`	project column list
`gh://:owner/:repo/actions[?status=success&...]`	github action's workflows/steps
`gh://:owner/:repo/[:branch/:tree_sha]/files[?recache=1]`	repository file tree
`gh://bookmarks`	your bookmarks
`gh://:owner/gists[?privacy=public]`	gist list
`gh://:owner/gists/:id/:file`	edit gist file
`gh://gists/new/:filename`	new gist

Keymaps

gh.vim provides some default keymap to operate each buffers.
You can refre help with :h gh-default-key-mappings.

If you want to customize original keymap, pelease write settings to your vimrc like bellow.

function! s:gh_map_add() abort
  if !exists('g:loaded_gh')
    return
  endif
  call gh#map#add('gh-buffer-issue-list', 'nnoremap', 'x', ':bw!<CR>')
  call gh#map#add('gh-buffer-issue-list', 'map', 'h', '<Plug>(gh_issue_list_prev)')
  call gh#map#add('gh-buffer-issue-list', 'map', 'l', '<Plug>(gh_issue_list_next)')
endfunction

augroup gh-maps
  au!
  au VimEnter * call <SID>gh_map_add()
augroup END

Summary

How about gh.vim?
If you are interesting, please try this plugin.
I hope your Vim life be more convenience.

DEV Community: skanehira