1GIST(1)                           Gist manual                          GIST(1)
2
3
4

NAME

6       gist - upload code to https://gist.github.com
7

Synopsis

9       The  gist gem provides a gist command that you can use from your termi‐
10       nal to upload content to https://gist.github.com/.
11

Installation

13       ○   If you have ruby installed:
14
15           gem install gist
16
17       ○   If you´re using Bundler:
18
19           source :rubygems gem ´gist´
20
21       ○   For OS X, gist lives in Homebrew
22
23           brew install gist
24
25       ○   For FreeBSD, gist lives in ports
26
27           pkg install gist
28
29
30

Command

32       ○   To upload the contents of a.rb just:
33
34           gist a.rb
35
36       ○   Upload multiple files:
37
38           gist a b c gist *.rb
39
40       ○   By default it reads from STDIN, and you can set a filename with -f.
41
42           gist -f test.rb <a.rb
43
44       ○   Alternatively, you can just paste from the clipboard:
45
46           gist -P
47
48       ○   Use -p to make the gist private:
49
50           gist -p a.rb
51
52       ○   Use -d to add a description:
53
54           gist -d "Random rbx bug" a.rb
55
56       ○   You can update existing gists with -u:
57
58           gist -u GIST_ID FILE_NAME gist -u 42f2c239d2eb57299408 test.txt
59
60       ○   If you´d like to copy the resulting URL to your clipboard, use -c.
61
62           gist -c <a.rb
63
64       ○   If you´d like to copy the resulting embeddable URL  to  your  clip‐
65           board, use -e.
66
67           gist -e <a.rb
68
69       ○   And  you  can  just ask gist to open a browser window directly with
70           -o.
71
72           gist -o <a.rb
73
74       ○   To list (public gists or all gists for authed user) gists for user
75
76           gist -l : all gists for authed user gist  -l  defunkt  :  list  de‐
77           funkt´s public gists
78
79
80
81       To read a gist and print it to STDOUT
82
83
84           gist -r GIST_ID
85           gist -r 374130
86
87
88
89       ○   See gist --help for more detail.
90
91
92

Login

94       Before  you  use gist for the first time you will need to log in. There
95       are two supported login flows:
96
97       1.  The Github device-code Oauth flow. This is the default for  authen‐
98           ticating to github.com, and can be enabled for Github Enterprise by
99           creating an Oauth  app,  and  exporting  the  environment  variable
100           GIST_CLIENT_ID with the client id of the Oauth app.
101
102       2.  The (deprecated) username and password token exchange flow. This is
103           the default for GitHub Enterprise, and can  be  used  to  log  into
104           github.com  by  exporting  the  environment variable GIST_USE_USER‐
105           NAME_AND_PASSWORD.
106
107
108
109   The device-code flow
110       This flow allows you to obtain a token by logging into  GitHub  in  the
111       browser  and  typing  a verification code. This is the preferred mecha‐
112       nism.
113
114
115           gist --login
116           Requesting login parameters...
117           Please sign in at https://github.com/login/device
118             and enter code: XXXX-XXXX
119           Success! https://github.com/settings/connections/applications/4f7ec0d4eab38e74384e
120
121
122
123       The returned access_token is stored in ~/.gist and used for all  future
124       gisting.    If    you    need   to   you   can   revoke   access   from
125       https://github.com/settings/connections/applica
126       tions/4f7ec0d4eab38e74384e.
127
128   The username-password flow
129       This  flow  asks  for your GitHub username and password (and 2FA code),
130       and exchanges them for a token with the "gist" permission  (your  user‐
131       name  and  password  are  not  stored). This mechanism is deprecated by
132       GitHub, but may still work with GitHub Enterprise.
133
134
135           gist --login
136           Obtaining OAuth2 access_token from GitHub.
137           GitHub username: ConradIrwin
138           GitHub password:
139           2-factor auth code:
140           Success! https://github.com/settings/tokens
141
142
143
144       This token is stored in ~/.gist and used for all future gisting. If you
145       need  to  you can revoke it from https://github.com/settings/tokens, or
146       just delete the file.
147
148       If you have a complicated authorization requirement  you  can  manually
149       create  a  token  file  by  pasting a GitHub token with gist scope (and
150       maybe the user:email for GitHub Enterprise) into a file called ~/.gist.
151       You can create one from https://github.com/settings/tokens
152
153       This  file  should  contain only the token (~40 hex characters), and to
154       make it easier to edit, can optionally have  a  final  newline  (\n  or
155       \r\n).
156
157       For example, one way to create this file would be to run:
158
159
160           (umask 0077 && echo MY_SECRET_TOKEN > ~/.gist)
161
162
163
164       The  umask  ensures that the file is only accessible from your user ac‐
165       count.
166
167   GitHub Enterprise
168       If you´d like gist to use  your  locally  installed  GitHub  Enterprise
169       https://enterprise.github.com/, you need to export the GITHUB_URL envi‐
170       ronment variable (usually done in your ~/.bashrc).
171
172
173           export GITHUB_URL=http://github.internal.example.com/
174
175
176
177       Once you´ve done this  and  restarted  your  terminal  (or  run  source
178       ~/.bashrc),  gist  will  automatically use GitHub Enterprise instead of
179       the public github.com
180
181       Your token for  GitHub  Enterprise  will  be  stored  in  .gist.<proto‐
182       col>.<server.name>[.<port>]   (e.g.  ~/.gist.http.github.internal.exam‐
183       ple.com for the GITHUB_URL example above) instead of ~/.gist.
184
185       If you have multiple servers or use Enterprise and public GitHub often,
186       you  can  work around this by creating scripts that set the env var and
187       then run gist. Keep in mind that to use the public GitHub you must  un‐
188       set  the  env var. Just setting it to the public URL will not work. Use
189       unset GITHUB_URL
190
191   Token file format
192       If you cannot use passwords, as most Enterprise installations  do,  you
193       can  generate  the token via the web interface and then simply save the
194       string in the correct file. Avoid line breaks or you might see: $  gist
195       -l Error: Bad credentials
196
197       You can also use Gist as a library from inside your ruby code:
198
199
200       If you need more advanced features you can also pass:
201
202:access_token    to   authenticate   using   OAuth2   (default   is
203           `File.read("~/.gist")).
204
205:filename to change the syntax highlighting (default is a.rb).
206
207:public if you want your gist to have a guessable url.
208
209:description to add a description to your gist.
210
211:update to update an existing gist (can be a URL or an id).
212
213:copy to copy the  resulting  URL  to  the  clipboard  (default  is
214           false).
215
216:open to open the resulting URL in a browser (default is false).
217
218
219
220       NOTE:  The  access_token  must have the gist scope and may also require
221       the user:email scope.
222
223       ○   If you want to upload multiple files in the same gist, you can:
224
225           Gist.multi_gist("a.rb" => "Foo.bar", "a.py" => "Foo.bar")
226
227       ○   If you´d rather use gist´s builtin access_token, then you can force
228           the user to obtain one by calling:
229
230           Gist.login!
231
232       ○   This  will take them through the process of obtaining an OAuth2 to‐
233           ken, and storing it in ~/.gist, where  it  can  later  be  read  by
234           Gist.gist
235
236
237

Configuration

239       ○   If you´d like -o or -c to be the default when you use the gist exe‐
240           cutable, add an alias to your ~/.bashrc (or equivalent). For  exam‐
241           ple:
242
243           alias gist=´gist -c´
244
245       ○   If  you´d prefer gist to open a different browser, then you can ex‐
246           port the BROWSER environment variable:
247
248           export BROWSER=google-chrome
249
250
251
252       If clipboard or browser integration don´t work on your platform, please
253       file a bug or (more ideally) a pull request.
254
255       If  you  need  to  use an HTTP proxy to access the internet, export the
256       HTTP_PROXY or http_proxy environment variable and gist will use it.
257

Meta-fu

259       Thanks to @defunkt and @indirect for writing and maintaining versions 1
260       through 3. Thanks to @rking and @ConradIrwin for maintaining version 4.
261
262       Licensed under the MIT license. Bug-reports, and pull requests are wel‐
263       come.
264
265
266
267                                 January 2023                          GIST(1)
Impressum