Use GitHub in Vim/Neovim
Tags: vim, neovim, github
Published: 2021-02-14 10:11:22

Currently I developing Vim plugin named [gh.vim](https://github.com/skanehira/gh.vim) for GitHub.

![](https://i.gyazo.com/503dfe0eba487449f19d1c93e248902c.png)

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.

![](https://i.gyazo.com/26211bc3a5db16e49c72cf3729fcfb6e.png)

Issue list items is bellow.

```none
  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`.

![](https://i.gyazo.com/2278bb5248a412bfa2a21375fa0bd11b.png)

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.

![](https://i.gyazo.com/814ffa91320db7d2cc6d81695a47d120.png)

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

![](https://i.gyazo.com/3fad9b29d5c85650eedc7009d5f8bcb6.png)

### 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.

![](https://i.gyazo.com/c74973d9a4fb553d663709a427d2777d.png)

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.

![](https://i.gyazo.com/ba4aa068fdaeebcf8168c8994ac73db4.gif)

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.

![](https://i.gyazo.com/ac165822eb21086a410747e0e6e35743.png)

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.

![](https://i.gyazo.com/9a7b998917d1ba969bb814c89cc156e8.png)

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.

![](https://i.gyazo.com/e1dfc9d4880ca68f8ca84dfe025bd160.gif)

## 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`.

![](https://i.gyazo.com/9f5a8f46750bf6f3f4130907d9f9a149.png)

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.

![](https://i.gyazo.com/bb920d9694c126b571e4f90fa7cc9a9a.gif)

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

![](https://i.gyazo.com/c636400b133ed5d302d2c09ac5935335.png)

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.

```vim
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.