File: magithub.texi

package info (click to toggle)
magithub 0.1.7-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 1,920 kB
  • sloc: lisp: 3,684; makefile: 82
file content (1011 lines) | stat: -rw-r--r-- 30,715 bytes parent folder | download | duplicates (2)
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
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
\input texinfo    @c -*- texinfo -*-
@c %**start of header
@setfilename magithub.info
@settitle Magithub -- Magit interfaces for GitHub
@documentencoding UTF-8
@documentlanguage en
@c %**end of header

@copying
@quotation
Copyright (C) 2017-2018 Sean Allred <code@@seanallred.com>

You can redistribute this document and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any
later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
@end quotation
@end copying

@dircategory Emacs
@direntry
* Magithub: (magithub). Magit interfaces for GitHub.
@end direntry

@finalout
@titlepage
@title Magithub -- Magit interfaces for GitHub
@subtitle for version 0.1.5 (0.1.5-106-ge4a004c+1)
@author Sean Allred
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Magithub -- Magit interfaces for GitHub

You may also be interested in @uref{https://github.com/vermiculus/magithub/tree/master/RelNotes, the most current release notes}.

Magithub provides an integrated GitHub experience through Magit's familiar
interface.  Just as Magit hopes to 'outsmart git', Magithub hopes to add
smarts to GitHub for performing common tasks.

Happy hacking!

@noindent
This manual is for Magithub version 0.1.5 (0.1.5-106-ge4a004c+1).

@quotation
Copyright (C) 2017-2018 Sean Allred <code@@seanallred.com>

You can redistribute this document and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any
later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
@end quotation
@end ifnottex

@menu
* Installation::
* Introduction::
* Status Buffer Integration::
* Dispatch Popup::
* 'Features'::
* Cloning::
* Dashboard::
* Creating Content::
* Caching::
* Proxies::
* Unfiled::

@detailmenu
--- The Detailed Node Listing ---

Installation

* Authentication::
* Enterprise Support::

Introduction

* Note::
* Brief Tutorial::

Brief Tutorial

* Clone a repository::
* Viewing project status::
* Viewing and replying to an issue::
* Creating an issue::
* Creating a pull request::


Status Buffer Integration

* Project Status::
* Open Issues and Pull Requests::

Open Issues and Pull Requests

* Manipulating the Cache::
* Offline Mode::
* Controlling Sections::


Dispatch Popup

* Configuration::
* Meta::

Unfiled

* Content::
* 'Tricks'::

Content

* Working with Repositories::
* Your Dashboard::


@end detailmenu
@end menu

@node Installation
@chapter Installation

Magithub can be installed from @uref{http://melpa.milkbox.net/#/magithub, MELPA} using @samp{M-x list-packages} or by
evaluating the following:

@lisp
(package-install 'magithub)
@end lisp

Here is the basic recommended @uref{https://github.com/jwiegley/use-package, @samp{use-package}} configuration:

@lisp
(use-package magithub
  :after magit
  :ensure t
  :config (magithub-feature-autoinject t))
@end lisp

If you prefer to install the package manually, this can of course be done
via the usual means.

For more information, see @ref{Packages,,,emacs,}.

@menu
* Authentication::
* Enterprise Support::
@end menu

@node Authentication
@section Authentication

Given GitHub's rate-limiting policy, Magithub is unlikely to ever support
running without authenticating.  As such, you @emph{must} authenticate before you
use Magithub.  (As of #107, Magithub will not even attempt go online until
you're properly authenticated.)

To authenticate, you can simply start using Magithub; Ghub should walk you
through the authentication process unless you use two-factor authentication.
(Your token is stored in one of your @code{auth-sources}; see @uref{https://magit.vc/manual/ghub/How-Ghub-uses-Auth_002dSource.html#How-Ghub-uses-Auth_002dSource, Ghub's manual} for
details.)

If you do use two-factor authentication, you must

@itemize
@item
Manually create a GitHub token (from @uref{https://github.com/settings/tokens})
for scopes `repo`, `notifications` and `user` (see variable
@code{magithub-github-token-scopes})

@item
Store it for Magithub per user in one of your @code{auth-sources}
(e.g. @samp{~/.authinfo}).  Write a line like this:

@example
machine api.github.com login YOUR_GITHUB_USERNAME^magithub password YOUR_GITHUB_TOKEN
@end example
@end itemize

Beware that writing the token in plaintext in @samp{~/.authinfo} (or elsewhere) is
not secure against attackers with access to that file.  For details and
better alternatives (like using GPG), see Ghub's manual on @uref{https://magit.vc/manual/ghub/Manually-Creating-and-Storing-a-Token.html#Manually-Creating-and-Storing-a-Token, Manually Creating
and Storing a Token} and @uref{https://magit.vc/manual/ghub/How-Ghub-uses-Auth_002dSource.html#How-Ghub-uses-Auth_002dSource, How Ghub uses Auth-Source}.

If you want to authenticate Ghub without using Magithub, you can simply
evaluate the following:

@lisp
(require 'magithub)
(ghub-get "/user" nil :auth 'magithub)
@end lisp

After Ghub walks you through the authentication process during evaluation,
the @code{ghub-get} form should return familiar information (your login, email,
etc.).

If you're having trouble @emph{authenticating}, @uref{https://github.com/magit/ghub/issues/new, open a Ghub issue} or drop by
@uref{https://gitter.im/vermiculus/magithub, Magithub's} or @uref{https://gitter.im/magit/magit, Magit's} Gitter channel.

@node Enterprise Support
@section Enterprise Support

For GitHub Enterprise support, you'll need to add your enterprise domain to
@code{magithub-github-hosts} so that Magithub can detect when it's in a GitHub
repository.  You will also need to configure your @samp{~/.authinfo} file
appropriately to authenticate to your domain; see Ghub's manual for details.

@node Introduction
@chapter Introduction

Magithub tries to follow closely Magit's lead in general interface.  Most of
its functionality is developed to tightly integrate with its section/
framework.  See @uref{https://magit.vc/manual/magit/Sections.html#Sections, Magit's documentation} for information on how to navigate
using this framework.

Magithub's functionality uses section-specific keymaps to expose
functionality.  Where it makes sense, the following keys will map to
functions that 'do the right thing':

@table @asis
@kindex w
@cindex magithub-browse-thing
@item @kbd{w} @tie{}@tie{}@tie{}@tie{}(@code{magithub-browse-thing})

Open a browser to the thing at point.  For instance, when point is on
issue 42 in your-favorite/github-repo, we'll open
@samp{http://github.com/your-favorite/github-repo/issue/42}.

@kindex a
@cindex magithub-add-thing
@item @kbd{a} @tie{}@tie{}@tie{}@tie{}(@code{magithub-add-thing})

Add something to the thing at point.  For instance, on a list of labels,
you can add more labels.

@kindex e
@cindex magithub-edit-thing
@item @kbd{e} @tie{}@tie{}@tie{}@tie{}(@code{magithub-edit-thing})

Edit the thing at point, such as an issue.

@kindex r
@cindex magithub-reply-thing
@item @kbd{r} @tie{}@tie{}@tie{}@tie{}(@code{magithub-reply-thing})

Reply to the thing at point, such as a comment.
@end table

Magithub also considers the similar placeholder commands introduced by Magit
which you may already be familiar with:

@table @asis
@kindex k
@cindex magit-delete-thing
@item @kbd{k} @tie{}@tie{}@tie{}@tie{}(@code{magit-delete-thing})
@kindex RET
@cindex magit-visit-thing
@item @kbd{RET} @tie{}@tie{}@tie{}@tie{}(@code{magit-visit-thing})
@end table

These concepts are intended to provide a more consistent experience
throughout Magithub within Magit by categorizing your broader interactions
with all GitHub content.  As with Magit, more commands are added as the
situation calls for it.

@menu
* Note::
* Brief Tutorial::
@end menu

@node Note
@section Note

By default, Magithub enables itself in all repositories where @samp{origin} points
to GitHub.

@defopt magithub-enabled-by-default

When non-nil, Magithub is enabled by default.  This is the fallback value
of git variable @samp{magithub.enabled} is not set in this repository.
@end defopt

@defopt magithub-github-hosts

A list of top-level domains that should be recognized as GitHub hosts.
@end defopt

@node Brief Tutorial
@section Brief Tutorial

Here's a script that will guide you through the major features of Magithub.
This is not a replacement for the documentation, but rather an example
workflow to whet your appetite.

@menu
* Clone a repository::
* Viewing project status::
* Viewing and replying to an issue::
* Creating an issue::
* Creating a pull request::
@end menu

@node Clone a repository
@subsection Clone a repository

@example
M-x magithub-clone RET vermiculus/my-new-repository
@end example
Cloning a repository this way gets the clone URL from GitHub and forwards
that on to @code{magit-clone}.  If the repository is a fork, you're prompted to add
the parent is added under the @samp{upstream} remote.

Fork behavior may change in the future.  It may be more appropriate to
actually/ clone the source repository and add your remote as a fork.  This
will cover the 90% case (the 10% case being active forks of unmaintained
projects).

@node Viewing project status
@subsection Viewing project status

You are dropped into a status buffer for @samp{vermiculus/my-new-repository}.  You
see some open issues and pull requests.  You move your cursor to an issue of
interest and @samp{TAB} to expand it, seeing the author, when it was
created/updated, any labels, and a preview of the issue contents.

If @samp{vermiculus/my-new-repository} used any status checks, you would see those
statuses as a header in this buffer.

@node Viewing and replying to an issue
@subsection Viewing and replying to an issue

You @samp{RET} on the issue and are taken to a dedicated buffer for that issue.
You can now see its full contents as well as all comments.  You'd like to
leave a comment -- a suggestion for a fix or an additional use-case to
consider -- you press @samp{r} to open a new buffer to @emph{reply} to this issue.  You
write your comment and @samp{C-c C-c} to submit.  But, oh no!  You didn't turn on
@samp{flyspell-mode} in markdown buffers, so you submitted a spelling error.  A
simple @samp{e} on the comment will @emph{edit} it.  After submitting again with @samp{C-c C-c},
everything is well.

Right now, other activity on the issue is not inserted into this buffer.
Press @samp{w} to open the issue in your browser.

@node Creating an issue
@subsection Creating an issue

You notice a small issue in how some feature is implemented, so back in the
status buffer, you use @samp{H i} to create a new issue.  (While inside the GitHub
repository, you could've used any key bound to @code{magithub-issue-new}.)  The
first line is the title of the new issue; everything else is the body.  You
submit the issue with @samp{C-c C-c}.

You come back a little while later to leave additional details -- you reply
to your own issue in a comment, but realize you should just edit your
original issue to avoid confusion.  You @samp{k} to @emph{kill} / delete the comment.

@node Creating a pull request
@subsection Creating a pull request

Since you care about this project and want to help it succeed, you decide to
fix this issue yourself.  You checkout a new branch (@samp{b c my-feature RET}) and
get to work.

Because you're so @emph{awesome}, you're ready to push your commit to fix your
issue.  After realizing you don't have push permissions to this repository,
you create a fork using @samp{H f}.  You push your branch to your new remote (named
after your username) and create a pull request with @samp{H p}.  You select the
head branch as @samp{my-feature} and the base branch as @samp{master} (or whatever the
production/staging branch is for the project).  You fill out the pull
request template provided by the project (and inserted into your PR) and off
you go!

@node Status Buffer Integration
@chapter Status Buffer Integration

The part of Magithub you're likely to interact with the most is
embedded right into Magit's status buffer.

@table @asis
@kindex H
@cindex magithub-dispatch-popup
@item @kbd{H} @tie{}@tie{}@tie{}@tie{}(@code{magithub-dispatch-popup})

Access many Magithub entry-points.  See @ref{Dispatch Popup} for more details.

@kindex H e
@cindex FIXME
@item @kbd{H e} @tie{}@tie{}@tie{}@tie{}(@code{FIXME})

Toggle status buffer integration in this repository.
@end table

There are two integrations turned on by default:

@menu
* Project Status::
* Open Issues and Pull Requests::
@end menu

@node Project Status
@section Project Status

Many services (such as Travis CI and CircleCI) will post statuses to
commits.  A summary of these statuses are visible in the status buffer
headers.

@table @asis
@kindex RET
@cindex magithub-ci-visit
@item @kbd{RET} @tie{}@tie{}@tie{}@tie{}(@code{magithub-ci-visit})
@kindex w
@cindex magithub-ci-visit
@item @kbd{w} @tie{}@tie{}@tie{}@tie{}(@code{magithub-ci-visit})

Visit the service's summary of this status.  For example, a status posted
by Travis CI will open that build on Travis.

@kindex g
@cindex magithub-ci-refresh
@item @kbd{g} @tie{}@tie{}@tie{}@tie{}(@code{magithub-ci-refresh})

Refresh statuses from GitHub and then refresh the current buffer.

@kindex H s
@cindex FIXME
@item @kbd{H s} @tie{}@tie{}@tie{}@tie{}(@code{FIXME})

Enable/disable status checks in this repository.
@end table

@node Open Issues and Pull Requests
@section Open Issues and Pull Requests

These will also display in the status buffer.  There's a lot of
functionality available right from an issue section.

@table @asis
@kindex g
@cindex magithub-issue-refresh
@item @kbd{g} @tie{}@tie{}@tie{}@tie{}(@code{magithub-issue-refresh})

Refresh issues and pull requests from GitHub and then refresh the current
buffer.

@kindex RET
@cindex magithub-issue-visit
@item @kbd{RET} @tie{}@tie{}@tie{}@tie{}(@code{magithub-issue-visit})

Open a new buffer to view an issue and its comments.

@kindex w
@cindex magithub-issue-browse
@item @kbd{w} @tie{}@tie{}@tie{}@tie{}(@code{magithub-issue-browse})
@kindex w
@cindex magithub-pull-browse
@item @kbd{w} @tie{}@tie{}@tie{}@tie{}(@code{magithub-pull-browse})

Browse this issue / pull request on GitHub.

@kindex N
@cindex magithub-issue-personal-note
@item @kbd{N} @tie{}@tie{}@tie{}@tie{}(@code{magithub-issue-personal-note})

Opens a buffer for offline note-taking.

@kindex L
@cindex magithub-issue-add-labels
@item @kbd{L} @tie{}@tie{}@tie{}@tie{}(@code{magithub-issue-add-labels})

Add labels to the issue.

@kindex a
@cindex magithub-label-add
@item @kbd{a} @tie{}@tie{}@tie{}@tie{}(@code{magithub-label-add})
@kindex k
@cindex magithub-label-remove
@item @kbd{k} @tie{}@tie{}@tie{}@tie{}(@code{magithub-label-remove})

When point is on a label section, you can add/remove labels (provided you
have permission to do so).

@end table

@cindex magithub-label-color-replace
@deffn Command magithub-label-color-replace

Labels are colored as they would be on GitHub.  In some themes, this
produces an illegible or otherwise undesirable color.  This command can
help you find a substitute for labels of this color.
@end deffn

@defvar magithub-issue-details-hook

Control which issue details display in the status buffer.  Functions
intended for this variable use the @samp{magithub-issue-detail-insert-*} prefix.

Performance note: judicious use of this variable can improve your overall
Magit experience in large buffers.
@end defvar

@defopt magithub-issue-issue-filter-functions
@end defopt
@defopt magithub-issue-pull-request-filter-functions

These are lists of functions which must all return non-nil for an issue/PR
to be displayed in the status buffer.  They all receive the issue/PR
object as their sole argument.  For example, you might want to filter out
issues labels @samp{enhancement} from your list:

@lisp
(setq magithub-issue-issue-filter-functions
      (list (lambda (issue)          ; don't show enhancement requests
              (not
               (member "enhancement"
                       (let-alist issue
                         (ghubp-get-in-all '(name) .labels)))))))
@end lisp
@end defopt

@menu
* Manipulating the Cache::
* Offline Mode::
* Controlling Sections::
@end menu

@node Manipulating the Cache
@subsection Manipulating the Cache

When point is on a Magithub-controlled section (like the status header):
@multitable {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Default Key
@tab Description
@item @samp{g}
@tab Refresh only this section's GitHub content
@item @samp{C-u g}
@tab Like @samp{g}, but works on the whole buffer
@end multitable

@node Offline Mode
@subsection Offline Mode

@multitable {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaa}
@headitem Default Key
@tab Description
@item @samp{H C c}
@tab Toggle offline mode
@end multitable

Offline mode was introduced for those times when you're on the go, but you'd
still like to have an overview of GitHub data in your status buffer.  It's
also useful for folks who want to explicitly control when Emacs communicates
with GitHub -- for this purpose, you can use @samp{C-u g} (discussed above) to pull
data from GitHub while in offline mode.

To start into offline mode everywhere, use
@example
git config --global magithub.cache always
@end example

See the documentation for function @code{magithub-settings--set-magithub.cache}
for details on appropriate values.

@node Controlling Sections
@subsection Controlling Sections

Sections like the issue list and the status header can be toggled with the
interactive functions of the form @samp{magithub-toggle-*}.  These functions have
no default keybinding.

Since status checks can be API-hungry and not all projects use them, you can
disable the status header at the repository-level with @samp{H ~}; see the Status
Checks section for more information.

@node Dispatch Popup
@chapter Dispatch Popup

Much of Magithub's functionality, including configuration options, is behind
this popup.  In Magit status buffers, it's bound to @samp{H}.

@table @asis
@kindex d
@cindex magithub-dashboard
@item @kbd{d} @tie{}@tie{}@tie{}@tie{}(@code{magithub-dashboard})

See @ref{Dashboard}.

@kindex c
@cindex magithub-create
@item @kbd{c} @tie{}@tie{}@tie{}@tie{}(@code{magithub-create})

Push a local repository up to GitHub.

@kindex H
@cindex magithub-browse
@item @kbd{H} @tie{}@tie{}@tie{}@tie{}(@code{magithub-browse})

Open the current repository in your browser.

@kindex f
@cindex magithub-fork
@item @kbd{f} @tie{}@tie{}@tie{}@tie{}(@code{magithub-fork})

Fork this repository on GitHub.  This will add your fork as a remote under
your username.  For example, if user @samp{octocat} forked Magit, we would see a
new remote called @samp{octocat} pointing to @samp{octocat/magit}.

@kindex i
@cindex magithub-issue-new
@item @kbd{i} @tie{}@tie{}@tie{}@tie{}(@code{magithub-issue-new})
@kindex p
@cindex magithub-pull-request-new
@item @kbd{p} @tie{}@tie{}@tie{}@tie{}(@code{magithub-pull-request-new})

Open a new buffer to create an issue or open a pull request.  See
@ref{Creating Content}.
@end table

@menu
* Configuration::
* Meta::
@end menu

@node Configuration
@section Configuration

Per-repository configuration is controlled via git variables reachable from
the dispatch popup via @samp{H C}.  Use @samp{? <key>} to get online help for each
variable in that popup.

@table @asis
@kindex C e
@cindex FIXME
@item @kbd{C e} @tie{}@tie{}@tie{}@tie{}(@code{FIXME})

Turn Magithub on/off (completely).

@kindex C s
@cindex FIXME
@item @kbd{C s} @tie{}@tie{}@tie{}@tie{}(@code{FIXME})

Turn the project status header on/off.

@kindex C c
@cindex FIXME
@item @kbd{C c} @tie{}@tie{}@tie{}@tie{}(@code{FIXME})

Control whether Magithub is considered 'online'.  This controls the
behavior of the the cache.  This may go away in the future.  See
Controlling the Cache for more details.  FIXME there is no such node.

@kindex C i
@cindex FIXME
@item @kbd{C i} @tie{}@tie{}@tie{}@tie{}(@code{FIXME})

Toggle the issues section.

@kindex C p
@cindex FIXME
@item @kbd{C p} @tie{}@tie{}@tie{}@tie{}(@code{FIXME})

Toggle the pull requests section.

@kindex C x
@cindex FIXME
@item @kbd{C x} @tie{}@tie{}@tie{}@tie{}(@code{FIXME})

Set the 'proxy' used for this repository.  See @ref{Proxies}.
@end table

@node Meta
@section Meta

Since Magithub is so integrated with Magit, there's often confusion about
whom to ask for support (especially for users of preconfigured Emacsen like
Spacemacs and Prelude).  Hopefully, these functions can direct you to the
appropriate spot.

@table @asis
@kindex &
@cindex magithub--meta-new-issue
@item @kbd{&} @tie{}@tie{}@tie{}@tie{}(@code{magithub--meta-new-issue})

Open the browser to create a new issue for Magithub functionality
described in this document.

@kindex h
@cindex magithub--meta-help
@item @kbd{h} @tie{}@tie{}@tie{}@tie{}(@code{magithub--meta-help})

Open the browser to ask for help on Gitter, a GitHub-focused chatroom.
@end table

@node 'Features'
@chapter 'Features'

Given that some features of Magithub are not desired by or appropriate for
every type of user, there are features that are not turned on by default.
These are features that are injected into standard Magit popups.

The list of available features is available in constant
@code{magithub-feature-list}.  Despite its name, this is an alist of symbols (i.e.,
'features') to functions that install the feature.  While the documentation
for each feature lives in that symbol, you would normally not otherwise
interact with it.

@defun magithub-feature-autoinject

This function is the expected interface to install features.  You will
normally use
@lisp
(magithub-feature-autoinject t)
@end lisp
in your configuration to install all features, but you have the option of
installing them one at a time using the symbols from constant
@code{magithub-feature-list} or as a list of those symbols:
@lisp
(magithub-feature-autoinject 'commit-browse)
(magithub-feature-autoinject '(commit-browse pull-request-merge))
@end lisp
@end defun

@node Cloning
@chapter Cloning

@cindex magithub-clone
@deffn Command magithub-clone

Clone a repository from GitHub.
@end deffn

@defopt magithub-clone-default-directory

The default destination directory to use for cloning.
@end defopt

@defopt magithub-preferred-remote-method

This option is a symbol indicating the preferred cloning method (between
HTTPS, SSH, and the @samp{git://} protocol).
@end defopt

@node Dashboard
@chapter Dashboard

The dashboard shows you information pertaining to @emph{you}:
@itemize
@item
notifications

@item
issues and pull requests you're assigned per repository
@end itemize
as well as contextual information like the logged-in user and @uref{https://developer.github.com/v3/#rate-limiting, rate-limiting}
information.

@cindex magithub-dashboard
@deffn Command magithub-dashboard

View your dashboard.
@end deffn

@table @asis
@kindex ;
@cindex magithub-dashboard-popup
@item @kbd{;} @tie{}@tie{}@tie{}@tie{}(@code{magithub-dashboard-popup})

Configure your global dashboard settings.

@end table

@defopt magithub-dashboard-show-read-notifications

When non-nil, we'll show read notifications in the dashboard.
@end defopt

@node Creating Content
@chapter Creating Content

It's great to read about what's been happening, but it's even better to
contribute your own thoughts and activity!

@table @asis
@kindex H i
@cindex magithub-issue-new
@item @kbd{H i} @tie{}@tie{}@tie{}@tie{}(@code{magithub-issue-new})
@kindex H p
@cindex magithub-pull-request-new
@item @kbd{H p} @tie{}@tie{}@tie{}@tie{}(@code{magithub-pull-request-new})

Create issues and pull requests.  If you have push access to the
repository, you'll have the opportunity to add labels before you submit
the issue.

Creating a pull request requires a HEAD branch, a BASE branch, and to know
which remote points to your fork.

@kindex r
@cindex magithub-comment-new
@item @kbd{r} @tie{}@tie{}@tie{}@tie{}(@code{magithub-comment-new})
@kindex r
@cindex magithub-comment-reply
@item @kbd{r} @tie{}@tie{}@tie{}@tie{}(@code{magithub-comment-reply})

On an issue or pull request section, @code{magithub-comment-new} will allow you
to post a comment to that issue/PR.  If point is already on a comment,
@code{magithub-comment-reply} will quote the comment at point for you.
@end table

@node Caching
@chapter Caching

Caching is a complicated topic with a long Magithub history of, well,
failure.  As of today, all data retrieved from the API is cached by
default.  Using @samp{g} on Magithub sections will usually refresh the information
in the buffer pertaining to that section.  Otherwise, @samp{C-u g} in any Magit
buffer will refresh all GitHub data in that buffer.

This behavior may change in the future, but for now, it's the most stable
option.  See

@node Proxies
@chapter Proxies

It's not uncommon to have repositories where the bug-tracker is in a
separate repository.  For these cases, you can use the idea of 'proxies'.  A
proxy is a remote (with a GitHub-associated URL) that you choose to use for
all GitHub API requests concerning the @emph{actual} current repository.  This is
manifest in the git variable @samp{magithub.proxy}.

@defun magithub-proxy-set-default

If you consistently use a specific remote name for the bug tracker, you
can set it globally.
@end defun

All GitHub requests specific to the current repository context are routed
through @code{magithub-repo} which respects this proxy.

@node Unfiled
@chapter Unfiled

@menu
* Content::
* 'Tricks'::
@end menu

@node Content
@section Content

@menu
* Working with Repositories::
* Your Dashboard::
@end menu

@node Working with Repositories
@subsection Working with Repositories

@menu
* General::
* Issues::
* Forking and Pull Requests::
* Labels::
* Status Checks::
@end menu

@node General
@subsubsection @strong{DONE} General

@multitable {aaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Default Key
@tab Description
@item @samp{H H}
@tab Opens the current repository in the browser
@item @samp{H c}
@tab Creates the current local repository on GitHub
@item @samp{M-x magithub-clone}
@tab Clone a repository
@end multitable

@samp{magithub-clone} may appear to be a thin wrapper over @samp{magit-clone}, but it's
quite a bit smarter than that.  We'll of course respect
@samp{magithub-preferred-remote-method} when cloning the repository, but we can
also detect when the repository is a fork and can create and set an upstream
remote accordingly (similar to @samp{M-x magithub-fork}).

@node Issues
@subsubsection @strong{DONE} Issues

@multitable {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Default Key
@tab Description
@item @samp{H i}
@tab Create a new issue
@item @samp{RET}
@tab Open the issue in GitHub
@end multitable

You can filter issues with @samp{magithub-issue-issue-filter-functions}:
@lisp
(setq magithub-issue-issue-filter-functions
      (list (lambda (issue) ; don't show enhancement requests
              (not
               (member "enhancement"
                       (let-alist issue
                         (ghubp-get-in-all '(name) .labels)))))))
@end lisp
Each function in the @samp{*-functions} list must return non-nil for the issue to
appear in the issue list.  See also the documentation for that variable.

@node Forking and Pull Requests
@subsubsection @strong{DONE} Forking and Pull Requests

@multitable {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Default Key
@tab Description
@item @samp{H f}
@tab Fork the current repository
@item @samp{H p}
@tab Submit pull requests upstream
@end multitable

You can also filter pull requests with
@samp{magithub-issue-pull-request-filter-functions}.  See the section on
issue-filtering for an example.

@node Labels
@subsubsection @strong{TODO} Labels

@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Default Key
@tab Description
@item @samp{M-x magithub-label-color-replace}
@tab Choose a new color for the label at point
@end multitable

By default, Magithub will adopt the color used by GitHub when showing
labels.  In some themes, this doesn't provide enough contrast.  Use @samp{M-x
magithub-label-color-replace} to replace the current label's color with
another one.  (This will apply to all labels in all repositories, but will
of course not apply to all @emph{shades} of the original color.)

@node Status Checks
@subsubsection @strong{TODO} Status Checks

@multitable {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Default Key
@tab Description
@item @samp{RET}
@tab Visit the status's dashboard in your browser
@item @samp{TAB}
@tab On the status header, show individual CI details
@item @samp{H ~}
@tab Toggle status integration for this repository
@end multitable

When the status buffer first opens, the status header is inserted at the top
and probably looks something like this:
@example
Status:   Success
@end example

You can get a breakdown of which checks succeeded and which failed by using
@samp{TAB}:
@example
Status:   Success
          Checks for ref: develop
          Success The Travis CI build passed continuous-integration/travis-ci/push
@end example

Pressing @samp{RET} on the header will take you to the dashboard associated with
that status check.  If there's more than one status check here, you'll be
prompted to choose a check (e.g., Travis, Circle, CLA, @dots{}).  Of course, if
you expand the header to show the individual checks, @samp{RET} on those will take
you straight to that check.

@node Your Dashboard
@subsection @strong{TODO} Your Dashboard

Check out @samp{M-x magithub-dashboard} to view your notifications and issues
assigned to you

@node 'Tricks'
@section @strong{TODO} 'Tricks'

Most of Magithub is implemented in pure Elisp now, but there are a few
lingering goodies that haven't been ported (since their real logic is
non-trivial).  These definitions are relegated to @samp{magithub-issue-tricks.el}.

Make sure to install @uref{https://hub.github.com, @samp{hub}} and add it to your @code{exec-path} if you intend to use
these functions.  After installation, use @samp{hub browse} from a directory with a
GitHub repository to force the program to authenticate -- this avoids some
weirdness on the Emacs side of things.

@bye