*gissues.txt* github-issues.vim =============================================================================== Contents ~ 1. Introduction |gissues-introduction| 1. Omnicomplete |gissues-omnicomplete| 2. Lookup menu |gissues-lookup-menu| 3. Handling issues |gissues-handling-issues| 4. Creating issues |gissues-creating-issues| 5. Milestones |gissues-milestones| 6. Fugitive integration |gissues-fugitive-integration| 7. Requirements and Installation |gissues-requirements-installation| 8. Configuration |gissues-configuration| 9. Contributing |gissues-contributing| 2. Shameless plug |gissues-shameless-plug| 3. References |gissues-references| =============================================================================== *gissues-introduction* Introduction ~ Github issue integration in Vim. It's kind of awesome. ------------------------------------------------------------------------------- *gissues-omnicomplete* Omnicomplete ~ If you use Fugitive or edit gitcommit files in Vim, github-issues will automatically populate the omnicomplete menu with issues on Github. This is useful when you want to reference commits, close issues, etc., through Github's commit message parsing. Here's how it works with Neocomplete: Image: (see reference [1]) If you use pure omnicomplete, use 'C-x C-o' to pull up the menu. No need to run commands, no need to configure. It just works. ;) (And if it doesn't, it should, so submit an issue) Not bad, huh? ------------------------------------------------------------------------------- *gissues-lookup-menu* Lookup menu ~ To show Github issues for the current repository: > :Gissues < Press enter to view more details. Image: (see reference [2]) ------------------------------------------------------------------------------- *gissues-handling-issues* Handling issues ~ You can open and close issues using 'co' and 'cc' in the issue view. Image: (see reference [3]) They're also totally editable buffers, and saving the file will sync with Github's servers. You can use this to write comments, too: Image: (see reference [4]) ------------------------------------------------------------------------------- *gissues-creating-issues* Creating issues ~ You can even use ':Giadd' to create a blank issue. Saving the buffer will generate a new issue and update the buffer with an issue number and the ability to add comments. Image: (see reference [5]) While creating or editing issues it is possible to add multiple space separated assignees. How awesome is that!? ------------------------------------------------------------------------------- *gissues-milestones* Milestones ~ New feature: Use ':Gmiles' to open a menu of milestones. Press return on one to select it and filter ':Gissues' by that milestone from then on. ------------------------------------------------------------------------------- *gissues-fugitive-integration* Fugitive integration ~ Github will show any commits that reference the issue. That's what the omnicomplete helps with. But to make things even more awesome, github- issues.vim integrates with Fugitive.vim to make commit hashes clickable with the return key. Image: (see reference [6]) ------------------------------------------------------------------------------- *gissues-requirements-installation* Requirements and Installation ~ Vim with Python 2.7, Python 2.7 installed and working with Vim. I recommend using Pathogen [7] and Git cloning into ~/.vim/bundle. You can also just download the plugin and paste it into your plugin directory. Then **read below about adding an access token**. ------------------------------------------------------------------------------- *gissues-configuration* Configuration ~ The omnicomplete and lookup features will work out of the box for public repos. If you have private repos, or would like the ability to comment, open, close, and add issues, you will need to set an access token. Don't worry, this is super easy. > g:github_access_token < Grab an access token from here [8], then set this variable, preferably in a local vim file not included in any public repositories: 'let g:github_access_token = "9jb19c1189f083d7013i24367lol"' **Remember**, you should treat your access token like a password! Other options include: > g:github_issues_no_omni < When this is set to any value, github-issues will not set Neocomplete and Omnicomplete hooks. > g:github_upstream_issues < When this is set to 1, github-issues will use upstream issues (if repo is fork). This will require extra requests for the Github API, however. > g:github_api_url = "https://api.github.com/" < If you use Github Enterprise, where the Github server is hosted somewhere other than Github.com, set this parameter to your API path. This is specifically for Github Enterprise and will not work for Bitbucket, Gitlab, etc. > g:github_same_window = 1 < When this is set to 1, github-issues will use the current window instead of splitting the screen via the ':new' command. > g:gissues_issue_vsplit = 0 When this set to one the issue details buffer will open in vertical buffer instead of horizontal. Works only if `g:github_same_window` is not set > g:gissues_list_vsplit = 0 Same as above but for the list of issues. > g:gissues_split_expand = 0 Setting to 1 will expand the buffer to full width for horizontal split and full height for vertical split instead of nesting inside parent split. > g:gissues_split_height = 0 Set the height of horizontal split, default 50% of parent. > g:issues_vsplit_width = 0 Same as above but for vertical split. > g:gissues_lazy_load = 0 < When this is set to 1, omnicomplete will not be populated until it is triggered. This eliminates potential lag when opening 'gitcommit' files. > g:gissues_async_omni = 0 < **Experimental**: When set to 1, omnicomplete will be populated asynchronously, on another thread. This removes almost all lag from the UI when using Gissues, and can be combined with g:gissues_lazy_load to reduce network traffic while still receiving the same speed boost. However, this uses threads and needs a lot more testing to ensure it is stable. ------------------------------------------------------------------------------- *gissues-contributing* Contributing ~ Pull requests, feature requests, and issues are always welcome! =============================================================================== *gissues-shameless-plug* Shameless plug ~ I hack around with Vim plugins, so follow me [9] if you're into that kind of stuff (or just want to make my day) ;) =============================================================================== *gissues-references* References ~ [1] https://jaxbot.me/pics/vim/vim_gissues2.gif [2] https://jaxbot.me/pics/vim/vim-github-issues-1.gif [3] https://jaxbot.me/pics/vim/vim-github-issues-2.gif [4] https://jaxbot.me/pics/vim/vim-github-issues-4.gif [5] https://jaxbot.me/pics/vim/vim-github-issues-6.gif [6] https://jaxbot.me/pics/vim/vim-github-issues-3.gif [7] https://github.com/tpope/vim-pathogen [8] https://github.com/settings/tokens/new [9] https://github.com/jaxbot vim: ft=help