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.
Top comments (0)