.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "GIST\-PASTE" "1" "August 2014" "" "Gist manual"
.
.SH "NAME"
\fBgist\-paste\fR \- upload code to https://gist\.github\.com
.
.SH "Synopsis"
The gist gem provides a \fBgist\-paste\fR command that you can use from your terminal to upload content to https://gist\.github\.com/\.
.
.SH "Installation"
.
.IP "\(bu" 4
If you have ruby installed:
.
.IP
gem install gist
.
.IP "\(bu" 4
If you\'re using Bundler:
.
.IP
source :rubygems gem \'gist\'
.
.IP "\(bu" 4
For OS X, gist lives in Homebrew
.
.IP
brew install gist
.
.IP "" 0
.
.SH "Command"
.
.IP "\(bu" 4
To upload the contents of \fBa\.rb\fR just:
.
.IP
gist\-paste a\.rb
.
.IP "\(bu" 4
Upload multiple files:
.
.IP
gist\-paste a b c gist\-paste *\.rb
.
.IP "\(bu" 4
By default it reads from STDIN, and you can set a filename with \fB\-f\fR\.
.
.IP
gist\-paste \-f test\.rb <a\.rb
.
.IP "\(bu" 4
Alternatively, you can just paste from the clipboard:
.
.IP
gist\-paste \-P
.
.IP "\(bu" 4
Use \fB\-p\fR to make the gist private:
.
.IP
gist\-paste \-p a\.rb
.
.IP "\(bu" 4
Use \fB\-d\fR to add a description:
.
.IP
gist\-paste \-d "Random rbx bug" a\.rb
.
.IP "\(bu" 4
You can update existing gists with \fB\-u\fR:
.
.IP
gist\-paste lib/gist\.rb bin/gist\-paste \-u 42f2c239d2eb57299408
.
.IP "\(bu" 4
If you\'d like to copy the resulting URL to your clipboard, use \fB\-c\fR\.
.
.IP
gist\-paste \-c <a\.rb
.
.IP "\(bu" 4
If you\'d like to copy the resulting embeddable URL to your clipboard, use \fB\-e\fR\.
.
.IP
gist\-paste \-e <a\.rb
.
.IP "\(bu" 4
And you can just ask gist to open a browser window directly with \fB\-o\fR\.
.
.IP
gist\-paste \-o <a\.rb
.
.IP "\(bu" 4
To list (public gists or all gists for authed user) gists for user
.
.IP
gist\-paste \-l : all gists for authed user gist\-paste \-l defunkt : list defunkt\'s public gists
.
.IP "\(bu" 4
See \fBgist\-paste \-\-help\fR for more detail\.
.
.IP "" 0
.
.SH "Login"
If you want to associate your gists with your GitHub account, you need to login with gist\-paste\. It doesn\'t store your username and password, it just uses them to get an OAuth2 token (with the "gist" permission)\.
.
.IP "" 4
.
.nf

gist\-paste \-\-login
Obtaining OAuth2 access_token from github\.
GitHub username: ConradIrwin
GitHub password:
2\-factor auth code:
Success! https://github\.com/settings/applications
.
.fi
.
.IP "" 0
.
.P
You can read the 2\-factor auth code from an sms or the authentification app, depending on how you set your account up \fIhttps://github\.com/settings/admin\fR\.
.
.P
Note: 2\-factor authentication just appeared recently \fIhttps://github\.com/blog/1614\-two\-factor\-authentication\fR, so if you run into errors, update the gist gem\.
.
.IP "" 4
.
.nf

gem update gist
.
.fi
.
.IP "" 0
.
.P
This token is stored in \fB~/\.gist\fR and used for all future gisting\. If you need to you can revoke it from https://github\.com/settings/applications, or just delete the file\. If you need to store tokens for both github\.com and a Github Enterprise instance you can save your Github Enterprise token in \fB~/\.gist\.github\.example\.com\fR where "github\.example\.com" is the URL for your Github Enterprise instance\.
.
.IP "\(bu" 4
After you\'ve done this, you can still upload gists anonymously with \fB\-a\fR\.
.
.IP
gist\-paste \-a a\.rb
.
.IP "" 0
.
.TP
You can also use Gist as a library from inside your ruby code:
.
.IP
Gist\.gist("Look\.at(:my => \'awesome\')\.code")
.
.P
If you need more advanced features you can also pass:
.
.IP "\(bu" 4
\fB:access_token\fR to authenticate using OAuth2 (default is `File\.read("~/\.gist"))\.
.
.IP "\(bu" 4
\fB:filename\fR to change the syntax highlighting (default is \fBa\.rb\fR)\.
.
.IP "\(bu" 4
\fB:public\fR if you want your gist to have a guessable url\.
.
.IP "\(bu" 4
\fB:description\fR to add a description to your gist\.
.
.IP "\(bu" 4
\fB:update\fR to update an existing gist (can be a URL or an id)\.
.
.IP "\(bu" 4
\fB:anonymous\fR to submit an anonymous gist (default is false)\.
.
.IP "\(bu" 4
\fB:copy\fR to copy the resulting URL to the clipboard (default is false)\.
.
.IP "\(bu" 4
\fB:open\fR to open the resulting URL in a browser (default is false)\.
.
.IP "" 0
.
.P
NOTE: The access_token must have the "gist" scope\.
.
.IP "\(bu" 4
If you want to upload multiple files in the same gist, you can:
.
.IP
Gist\.multi_gist("a\.rb" => "Foo\.bar", "a\.py" => "Foo\.bar")
.
.IP "\(bu" 4
If you\'d rather use gist\'s builtin access_token, then you can force the user to obtain one by calling:
.
.IP
Gist\.login!
.
.IP "\(bu" 4
This will take them through the process of obtaining an OAuth2 token, and storing it in \fB~/\.gist\fR, where it can later be read by \fBGist\.gist\fR
.
.IP "" 0
.
.SH "GitHub enterprise"
.
.IP "\(bu" 4
If you\'d like \fBgist\-paste\fR to use your locally installed GitHub Enterprise \fIhttps://enterprise\.github\.com/\fR, you need to export the \fBGITHUB_URL\fR environment variable in your \fB~/\.bashrc\fR\.
.
.IP
export GITHUB_URL=http://github\.internal\.example\.com/
.
.IP "\(bu" 4
Once you\'ve done this and restarted your terminal (or run \fBsource ~/\.bashrc\fR), gist\-paste will automatically use github enterprise instead of the public github\.com
.
.IP "" 0
.
.SH "Configuration"
.
.IP "\(bu" 4
If you\'d like \fB\-o\fR or \fB\-c\fR to be the default when you use the gist\-paste executable, add an alias to your \fB~/\.bashrc\fR (or equivalent)\. For example:
.
.IP
alias gist\-paste=\'gist\-paste \-c\'
.
.IP "\(bu" 4
If you\'d prefer gist\-paste to open a different browser, then you can export the BROWSER environment variable:
.
.IP
export BROWSER=google\-chrome
.
.IP "" 0
.
.P
If clipboard or browser integration don\'t work on your platform, please file a bug or (more ideally) a pull request\.
.
.P
If you need to use an HTTP proxy to access the internet, export the \fBHTTP_PROXY\fR or \fBhttp_proxy\fR environment variable and gist\-paste will use it\.
.
.SH "Meta\-fu"
Thanks to @defunkt and @indirect for writing and maintaining versions 1 through 3\. Thanks to @rking and @ConradIrwin for maintaining version 4\.
.
.P
Licensed under the MIT license\. Bug\-reports, and pull requests are welcome\.