view release on metacpan or  search on metacpan

share/man/man1/git-hub.1  view on Meta::CPAN

.PP
Once Git completion is enabled (whether you needed to do that manually or not), you can turn on \f(CW\*(C`git\-hub\*(C'\fR completion with a command like this:
.PP
.Vb 1
\&    source /path/to/git\-hub/share/completion.bash
.Ve
.SS "In zsh"
.IX Subsection "In zsh"
In the Z shell (zsh), you can manually enable \f(CW\*(C`git\-hub\*(C'\fR completion by adding the following line to your \f(CW\*(C`~/.zshrc\*(C'\fR, \fBbefore\fR the \f(CW\*(C`compinit\*(C'\fR function is called:
.PP
.Vb 1
\&    fpath=(\*(Aq/path/to/git\-hub/share/zsh\-completion\*(Aq $fpath)
.Ve
.SH "Plugins"
.IX Header "Plugins"
The \f(CW\*(C`git\-hub\*(C'\fR command supports plugins. All you need to do to install a plugin, is to clone the plugin repo into the \f(CW\*(C`plugin/\*(C'\fR subdirectory of the \f(CW\*(C`git\-hub\*(C'\fR repository. There are example plugins alrea...
.SH "Faster"
.IX Header "Faster"
The \f(CW\*(C`git\-hub\*(C'\fR command is written in pure Bash, including a complete \s-1JSON\s0 parser written in Bash. Unfortunately, this parser is a bit slow. It is \fBreally\fR slow for large \s-1API\s0 payloads.
.PP
To make the \f(CW\*(C`git\-hub\*(C'\fR command perform much faster, just run this command:
.PP
.Vb 1
\&    git hub config json\-lib json\-perl.bash
.Ve
.PP
That will enable a Perl replacement, which requires Perl (of course) and the \s-1JSON\s0.pm Perl module. If the \s-1JSON::XS\s0 Perl module is also installed, it will be even faster.
.SH "Pipe and Each"
.IX Header "Pipe and Each"
You can pipe the output of one \f(CW\*(C`git hub\*(C'\fR into another and multiply your power. The command being piped into should use the \s-1EACH\s0 option which is a single dash ('\-'). It will cause the command to be run once for each line of inp...
.PP
This command:
.PP
.Vb 1
\&    git hub followers \-\-raw
.Ve
.PP
will list lines containing only user ids. You can pipe it into commands needing a user id, like:
.PP
.Vb 1
\&    git hub followers \-\-raw | git hub user \- \-\-json
.Ve
.PP
Thus printing the \s-1JSON\s0 user info for each follower. Same as:
.PP
.Vb 3
\&    for _ in \`git hub followers \-\-raw\`; do
\&      git hub user $_ \-\-json
\&    done
.Ve
.PP
For '=' you can do things like:
.PP
.Vb 1
\&    echo alice bob chelsea | git hub trust =
.Ve
.PP
to trust a list of users in one go.
.SH "Token Authentication and Scopes"
.IX Header "Token Authentication and Scopes"
Many endpoints of the GitHub v3 \s-1API\s0 require a Personal \s-1API\s0 Access Token. You can list your current tokens with this command:
.PP
.Vb 1
\&    git hub tokens
.Ve
.PP
If you don't have any tokens or want a new one for the \f(CW\*(C`git\-hub\*(C'\fR command, run these commands (the \f(CW\*(C`git hub setup\*(C'\fR command automates this):
.PP
.Vb 4
\&    git hub token\-new "my git\-hub command token"
\&    git hub scope\-add <token\-id> user repo
\&    git hub scopes <token\-id>
\&    git hub config api\-token <token\-value>
.Ve
.PP
You can also see all your tokens on the web at this page <https://github.com/settings/applications>.
.PP
You can specify your \s-1API\s0 token to \f(CW\*(C`git hub\*(C'\fR on the commandline with \f(CW\*(C`\-\-token=...\*(C'\fR or in the \f(CW\*(C`GIT_HUB_API_TOKEN\*(C'\fR environment variable, but the easiest thing to do is just set it in the git-hub c...
.PP
Certain token \fBscopes\fR are required for various GitHub \s-1API\s0 operations. Make sure your token has the scopes turned on for the things you want to do. See the \f(CW\*(C`scopes\*(C'\fR, \f(CW\*(C`scope\-add\*(C'\fR and \f(CW\*(C`scope\-remove\...
.PP
\&\s-1NOTE:\s0 All the \f(CW\*(C`git hub\*(C'\fR commands dealing with tokens and scopes require you to enter your GitHub password. If you need to issue a bunch of these commands and you don't want to retype your password each time, you can put your ...
.SH "Rate Limits"
.IX Header "Rate Limits"
GitHub limits unauthenticated \s-1API\s0 calls to 60 per hour, and authenticated \s-1API\s0 calls to 5000 per hour. For this reason you may wish to use authentication even for calls that don't need it. You can use the \f(CW\*(C`\-A/\-\-use\-auth\*(C'...
.PP
.Vb 1
\&    git hub config use\-auth true
.Ve
.PP
Another option is to set the \s-1GIT_HUB_USE_AUTH\s0 environment variable:
.PP
.Vb 1
\&    export GIT_HUB_USE_AUTH=true
.Ve
.SH "ETAG Caching"
.IX Header "ETAG Caching"
GitHub provides ETag headers in the \s-1API\s0 responses, and \f(CW\*(C`git\-hub\*(C'\fR uses them to cache responses, by default. When you use this feature, your rate-limit usage is not affected for cached responses.
.PP
GitHub has had caching bugs in their \s-1API\s0 in the past. If you suspect the cache is stale, you may want to try these options:
.IP "\(bu" 4
Use the \f(CW\*(C`\-C\*(C'\fR (\f(CW\*(C`\-\-no\-cache\*(C'\fR) flag on a request to bypass the cache.
.IP "\(bu" 4
Set \f(CW\*(C`GIT_HUB_NO_CACHE=true\*(C'\fR to bypass the cache.
.IP "\(bu" 4
Run \f(CW\*(C`git hub config no\-cache true\*(C'\fR to never use the cache.
.IP "\(bu" 4
Run \f(CW\*(C`git hub cache\-clear\*(C'\fR to erase all the cached values.
.SH "Examples"
.IX Header "Examples"
The following sections show lots of interesting ways to use \f(CW\*(C`git hub\*(C'\fR. Let your imagination be your guide.
.SS "Example 1. Create a new repo and GitHub origin"
.IX Subsection "Example 1. Create a new repo and GitHub origin"
Do everything from the command line:
.PP
.Vb 10
\&    $ mkdir foo
\&    $ cd foo
\&    $ echo \*(AqThe new foo\*(Aq > README
\&    $ git init
\&    $ git add README