/
github-complete.txt
417 lines (320 loc) · 16.4 KB
/
github-complete.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
*github-complete.vim* Completions for GitHub things.
Author : rhysd <lin90162@yahoo.co.jp>
Version : 0.2.0
CONTENTS *github-complete.vim-contents*
Introduction |github-complete.vim-introduction|
Install |github-complete.vim-install|
Usage |github-complete.vim-usage|
Emoji Completion |github-complete.vim-usage-eomji-completion|
Issue Completion |github-complete.vim-usage-issue-completion|
User Name Completion |github-complete.vim-usage-user-name-completion|
Repository Completion |github-complete.vim-usage-repository-completion|
Link URL Completion |github-complete.vim-usage-link-completion|
Variables |github-complete.vim-variables|
Mappings |github-complete.vim-mappings|
Neocomplete Sources |github-complete.vim-neocomplete-sources|
Recommended Plugin |github-complete.vim-recommended-plugin|
Repository |github-complete.vim-repository-page|
License |github-complete.vim-lisence|
==============================================================================
INTRODUCTION *github-complete.vim-introduction*
*github-complete* is a completion plugin to complete things related to GitHub.
It generates, caches and contextually shows candidates of completion via
GitHub API.
|github-complete| provides below completions.
- Emoji completion
- Issue completion
- User name completion
- Repository name completion
- Link URL completion
==============================================================================
INSTALL *github-complete.vim-install*
If you don't use any plugin manager, copy all files in autoload/, plugin/ and
ftplugin/ to your .vim directory.
If you use a plugin manager, please follow the instruction of it to install
|github-complete|.
In order to use asynchronous communication with GitHub API, please install
vimproc.vim in advance.
https://github.com/Shougo/vimproc.vim
Note: They are optional. Installing them is not mandatory to use
|github-complete| but I recommend it.
Below is an example for |neobundle.vim|.
>
NeoBundle 'Shougo/vimproc.vim'
NeoBundle 'rhysd/github-complete.vim'
<
|github-complete| uses "curl" or "wget" command to send requests to GitHub
API. Please make sure to install at least one of them in your system. (They
are usually pre-installed in *nix system.)
==============================================================================
USAGE *github-complete.vim-usage*
|github-complete| set 'omnifunc' when no other omnifunc is set on filetypes
"gitcommit" and "markdown". In the case, you need not to setup any
configuration. Otherwise, set "github_complete#complete" to 'omnifunc' in
your favorite filetypes in your |vimrc|.
Please make sure the proper 'omnifunc' is set with ":set omnifunc" in intended
filetypes.
For example, following code sets 'omnifunc' in "gitcommit" filetype
>
augroup config-github-complete
autocmd!
autocmd FileType gitcommit setl omnifunc=github_complete#complete
augroup END
<
Now you can use contextual completions with <C-X><C-O>. I'll show an example
use cases for each completion.
|i_CTRL-X_CTRL-O|
Note: "_" means the place of the cursor
------------------------------------------------------------------------------
EMOJI COMPLETION *github-complete.vim-usage-eomji-completion*
When the cursor is after ":", |github-complete| invokes emoji completion.
If your font can deal with unicode emojis, the items of completion show the
corresponding emojis.
>
I am a :do_
<
<C-X><C-O> here will show the list of emoji which starts with ":do". Possible
result of completion is below.
>
I am a :dog:_
<
------------------------------------------------------------------------------
ISSUE COMPLETION *github-complete.vim-usage-issue-completion*
When the cursor is after "#", |github-complete| invokes issue number completion.
You can select an issue with looking the issue titles in items of completion.
>
I fixed #_
<
<C-X><C-O> here will show the list of issues for current repository. Possible
result of completion is below.
>
I fixed #13_
<
------------------------------------------------------------------------------
USER NAME COMPLETION *github-complete.vim-usage-user-name-completion*
When the cursor is after "@" or "github.com/", |github-complete| invokes
GitHub user name completion.
>
Hi, @rh_
<
<C-X><C-O> here will show the list of user name which starts with "rh".
Possible result of completion is below.
>
Hi, @rhysd_
<
------------------------------------------------------------------------------
REPOSITORY COMPLETION *github-complete.vim-usage-repository-completion*
When the cursor is after the format {user name}/{some query}, |github_complete|
invokes GitHub repository completion. It shows repositories which {user name}
owns.
>
Please see github.com/rhysd/cle_
<
<C-X><C-O> here will show the list of repository which rhysd owns and which
starts with "cle". Possible result of completion is below.
>
Please see github.com/rhysd/clever-f.vim
<
------------------------------------------------------------------------------
LINK URL COMPLETION *github-complete.vim-usage-link-completion*
When writing link to GitHub repository in markdown, you can complete its URL
by the title of link.
On writing "[something](",
>
Please try [clever-f.vim](
<
<C-X><C-O> searches GitHub repositories by its
title "something" and shows the result. You can choose one to complete URL
of the link.
>
Please try [clever-f.vim](https://github.com/rhysd/clever-f.vim
<
==============================================================================
VARIABLES *github-complete.vim-variables*
|github-complete| provides many variables to customize the behavior of
completions.
g:github_complete_overwrite_omnifunc_filetypes
*g:github_complete_overwrite_omnifunc_filetypes*
|filetype|s can be set to the variable as a |List| of |string|. When you
open the buffer whose filetype is included in the variable, 'omnifunc'
would be overwritten by "github_complete#complete" automatically even if
other omni function is already set.
Default value is [].
e.g.
>
let g:github_complete_overwrite_omnifunc_filetypes = ["gitcommit"]
<
g:github_complete_enable_neocomplete *g:github_complete_enable_neocomplete*
Setting 1 to the variable enables all neocomplete sources by default.
See |github-complete.vim-neocomplete-sources| for more detail.
Default value is 0.
g:github_complete_enable_emoji_completion
*g:github_complete_enable_emoji_completion*
Setting 1 to the variable enables emoji completion.
Default value is 1.
g:github_complete_enable_issue_completion
*g:github_complete_enable_issue_completion*
Setting 1 to the variable enables issue number completion.
Default value is 1.
g:github_complete_enable_user_completion
*g:github_complete_enable_user_completion*
Setting 1 to the variable enables GitHub user completion.
Default value is 1.
g:github_complete_enable_repo_completion
*g:github_complete_enable_repo_completion*
Setting 1 to the variable enables GitHub repository name completion.
Default value is 1.
g:github_complete_include_issue_title *g:github_complete_include_issue_title*
When 1 is set to the variable, item of issue number completion includes
the title of issue. If you want to include the title of issue in your
writing text, it may be helpful.
Default value is 0.
g:github_complete_max_issue_candidates
*g:github_complete_max_issue_candidates*
When the repository is very big, issue number completion takes much time
because of many issues. This variable limits the number of candidates of
issue number completion. When non-positive number is set, it means no
limit.
Default value is 100.
g:github_complete_issue_request_params
*g:github_complete_issue_request_params*
This is a dictionary of parameters used to request the github issue api. It
allows to have more control on what issue to show. For example, show only
the opened, assigned to you, labeled as bug issue:
{'state' : 'open', 'assignee' : 'your-username', 'label' : 'bug' }
Default value is {'state' : 'all'}.
g:github_complete_git_cmd *g:github_complete_git_cmd*
The command name of git. It is used to look up the information of current
repository.
Default value is "git".
g:github_complete_fetch_issue_api_filetypes
*g:github_complete_fetch_issue_api_filetypes*
The list of filetypes to fetch GitHub issue API call. When the filetype
is set, |github-complete| instantly sends issue API call in the background.
After you consider your nice commit message, the API call might already be
done and you can use issue number completion instantly.
However, it takes a bit at setting the filetype because it sends API call
every time the filetype is set.
Default value is [ "gitcommit" ].
g:github_complete_emoji_japanese_workaround
*g:github_complete_emoji_japanese_workaround*
Some environments can't show emoji in item of emoji completion. When this
variable is set to 1, |github-complete| provides the workaround for the
description of items of emoji completion. It shows a description of
the corrensponding item of completion in Japanese.
For example, when you input ":do", items are shown such as ":dog2: -> 犬".
Default value is 0.
g:github_complete_fallback_omnifunc *g:github_complete_fallback_omnifunc*
If a name of some function is set to the variable, |github-complete| uses
the function when no completion is available. If an empty string is set,
|github-complete| invokes emoji completion and issue completion at the
same time.
If you already use omni function foo_bar#complete() and also want to use
|github-complete| at the same time, set "foo_bar#complete" to the variable
might help you.
Default value is "".
e.g.
>
let g:github_complete_fallback_omnifunc = "some#other#complete"
<
g:github_complete_enable_api_cache *g:github_complete_enable_api_cache*
If this variable is set to 1, |github-complete| caches the result of
GitHub API call. Otherwise, it doesn't.
Default value is 1.
g:github_complete_enable_omni_completion
*g:github_complete_enable_omni_completion*
If this variable is set to 1, github-complete.vim automatically defines
'omnifunc' on "gitcommit", "markdown" and "magit" filetypes.
Default value is 1.
g:github_complete_github_api_token *g:github_complete_github_api_token*
You can specify a token for GitHub API as string. If you obtain a token
with properly scopes, github-complete.vim will have the ability to access
to private repositories. And API rate limit is increased to 5000 from 60
per hour.
This value is set to environmental variable $GITHUB_API_TOKEN. If it is
empty, simply empty string is set. When empty string is set,
github-complete.vim won't use a token to call GitHub API.
To obtain GitHub API token, please access GitHub page as below:
1. Access to https://github.com
2. Click your icon and select 'Settings' in pull-down menu.
3. Select 'Personal access tokens' tab.
4. Click 'Generate new token' button.
5. Specify properly scopes. (If you don't want to access private
repository, select nothing.)
6. Click 'Genrate token' button and copy the displayed token.
Note: Please do not expose your token. It's secret.
g:github_complete_ghe_host *g:github_complete_ghe_host*
If you're a user of Github Enterprise, set this variable to your host.
Default value is "".
e.g.
>
let g:github_complete_ghe_host = 'github.mycompany.io'
<
==============================================================================
MAPPINGS *github-complete.vim-mappings*
<Plug>(github-complete-manual-completion)
*<Plug>(github-complete-manual-completion)*
This mapping starts completion manually. You can define custom mapping to
use completions of github-complete.vim rather than omni completion. This
mapping is defined only in insert mode. >
" Disable overwriting 'omnifunc'
let g:github_complete_enable_omni_completion = 0
" <C-x><C-x> invokes completions of github-complete.vim
autocmd FileType markdown,gitcommit
\ imap <C-x><C-x> <Plug>(github-complete-manual-completion)
<
==============================================================================
NEOCOMPLETE SOURCES *github-complete.vim-neocomplete-sources*
|github-complete| includes the sources of |neocomplete|.
https://github.com/Shougo/neocomplete.vim
You can use below sources via neocomplete's automatic completion.
- "github_emoji" ... Emoji completion after ":"
- "github_issue" ... Issue number completion after "#"
- "github_user" ... User completion after "@" or "github.com/"
- "github_repo" ... Repository completion after "{user name}/"
You can enable all sources by setting |g:github_complete_enable_neocomplete|
to 1. When it is set to 1, sources would be enabled in "gitcommit" and
"markdown" filetypes. If you want to control enabling individual sources,
please see documentation of neocomplete and use neocomplete's way.
Note: Above neocomplete sources are not tested yet because I don't know how to
do that. They may be buggy.
Note: |neocomplete| invoke completion automatically. Sometimes too many API
calls are sent to GitHub API and some requests may be denied. (Their response
will be 403.)
==============================================================================
RECOMMENDED PLUGIN *github-complete.vim-recommended-plugin*
* github-issues.vim
https://github.com/jaxbot/github-issues.vim
This plugin treats GitHub issues in Vim. Note that github-issues.vim provides
its own omni completion. You should set g:github_issues_no_omni and set
'omnifunc' to "github_complete#complete" in issue buffers to use
|github-complete|.
==============================================================================
REPOSITORY PAGE *github-complete.vim-repository-page*
The repository of |github-completion| is hosted in GitHub.
https://github.com/rhysd/github-complete.vim
If you've found a bug or have some questions, do not hesitate to open an
issue.
And pull requests are always welcome. No pull request is too small!
==============================================================================
LICENSE *github-complete.vim-license*
|github-complete| is distributed under The MIT license.
Copyright (c) 2015 rhysd
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
==============================================================================
vim:tw=78:colorcolumn=78:ts=8:ft=help:norl:et:fen:fdl=0: