Here are just a few of the things you can do on GitHub with a simple command:
git hub # Show the `git hub` cheat sheet
git hub help # Show this awesome documentation
git hub setup # Config dialog. Do this first!
git hub user <user> # Get info about a user
git hub repos <owner> # List recent repositories
git hub repo-new <repo> # Create a new repository
git hub fork <owner>/<repo> # Fork a repository
git hub clone <owner>/<repo> # Clone a GitHub repository
# Set/Change your repo description
git hub repo-edit <repo> description 'Just another GitHub repo'
git hub repo-delete <owner>/<repo> # Delete a repository
git hub followers <user> # List a user's followers
git hub star ingydotnet/git-hub # Star this repository
git hub watch ingydotnet/git-hub # Watch this repository
git hub follow ingydotnet # Follow this author
git hub trust ingydotnet # Add collaborators to repo
# Stalk all your followers
git hub followers -ra | git hub user -
git hub gists <user> # List gists for a user
=head1 Description
The B subcommand for git, allows you to perform many of the operations
made available by GitHub's v3 REST API, from the C commandline command.
You can fork, create, delete and modify repositories. You can get information
about users, repositories and issues. You can B, B and B
things, and find out who else is doing the same. The API is quite extensive.
With this command you can do many of your day to day GitHub actions without
needing a web browser.
You can also chain commands together using the output of one as the input of
another. For example you could use this technique to clone all the repos of a
GitHub user or organization, with one command. See PIPE AND EACH below.
=head1 Installation
There are currently 3 ways to install C. For all of them you need to
get the source code from GitHub:
The first installation method is preferred: C the C<.rc> file. Just
add a line like this one to your shell startup script:
source /path/to/git-hub/.rc
That will modify your C and C, and also enable command
completion.
The second method is to do these things by hand. This might afford you more
control of your shell environment. Simply add the C and C
directories to your C and C:
See below for info on how to turn on Command Completion.
The third method is a standard system install, which puts C next to
your other git commands, do this instead:
make install # Possibly with 'sudo'
To install to a place of your choice:
DESTDIR=/place/of/your/choice make install
The C method does not account for upgrading and command
completion yet.
See "Upgrading" and "Command Completion" below.
=head1 Command Options
Commandline options start with a dash and can appear in any order in the
command. Long form commands that require an argument can use '=' or not:
--count=5
--count 5
=over
=item C<< -c >>, C<< count= >>
This option is for commands that return a list of things. Specify the number
of items you want the command to return. Each list command has a reasonable
default value.
=item C<-a>, C<--all>
Show all elements for list commands. Also applies to a few other commands as
documented.
=item C<-r>, C<--raw>
For commands that produce lists, just list the raw data. For commands that
produce reports, show the raw storage keys, rather than the human friendly
ones. You will need the raw keys to edit/change values.
=item C<-j>, C<--json>
For some commands, you can get the raw data in JSON.
=item C<->
This option, just a single '-', is small but very powerful. It means to read
the next line from stdin, and put the content into the command at that point.
See PIPE and EACH below.
=item C<=>
Like the '-' command above, but reads each B from stdin.
=item C<-h>
Show the brief command usage.
=item C<--help>
Show the full documentation.
=item C<-q>, C<--quiet>
Show minimal output.
=item C<-v>, C<--verbose>
Show detailed output. Notably, show the raw command that is used for the
GitHub API calls.
=item C<< --token= >>
Set or override the api-token required by the command. This value can also
come from the C environment variable. Usually this value
comes from your C<~/.git-hub/config> file.
=item C<-d> C<--dryrun>
Don't actually make the API call. This option turns on verbose mode.
=item C<-T>
Show the API token in the verbose output. Hidden by default. This option turns
on verbose mode.
=item C<-A>, C<--use-auth>
Use authentication whether or not it is needed for a certain command. This is
useful if you have exceeded your hourly GitHub API rate limit, which is 60
calls unauthenticated, and 5000 calls authenticated.
=item C<-C> C<--no-cache>
There are currently known bugs in GitHub's cache headers. If the content seems
stale, use this option.
=back
=head2 Debug Options
There are a number of debug options that will give you lots of extra
information (albeit in a less pretty format).
=over
=item C<-O>
Show the API reponse output. Always in JSON format. JSON is pretty-printed.
=item C<-H>
Show the API response headers.
=item C<-J>
Show the API response JSON, in decoded form.
=item C<-R>
Repeat the last command, using the previous API server response. Useful for
development and debugging. (Beware, only caches the most recent API call, so
not really good for commands that make multiple calls).
=item C<-x>
Turn on Bash C<-x> debugging. This will show every bash command executed in
the program. This is extremely useful to track down nasty bugs.
=back
=head1 Arguments
The C command gets its input values from these sources (in
this order):
=over
=item * Commandline B (see specific command, below).
=item * Environment variables of the form C.
=item * The C<./.git/config> file. (The repo you are issuing commands from)
=item * The C<~/.git-hub/config> file.
=back
Most of the commands described below have arguments. This section defines each
of the argument types. Note that argument values that are strings containing
whitespace need to be quoted.
Argument variable names are always indicated by angle brackets, like: C<< >>. Arguments listed in square brackets are optional and arguments
followed by C<...> indicate that more than one is allowed.
=over
=item C<< >>
A GitHub user name. Sometimes an organization name can be used instead. If
this argument is optional, it defaults to the GitHub owner of the repo you are
currently in. If you are not in a GitHub repo, it defaults to your login.
B: C environment variable.
=item C<< >>
A GitHub user or organization that owns the repository being specified. This
value defaults much like the C<< >> argument (above). B:
C environment variable.
=item C<< >>
A GitHub organization name. B: C
environment variable.
=item C<< >>
A GitHub repository name. If this argument is optional, it defaults to the
GitHub repo name of the repo you are currently in. B:
C environment variable.
=item C<< / >>
Many commands need both an owner and repo separated by a slash. If the owner
is you (your GitHub login) you can omit it (but you still need the leading
slash). Like C, instead of C<me/myrepo>. If this argument is
optional, it defaults the the owner and repo of the GitHub repo you are in.
=item C<< >>
Two strings separated by whitespace. Values with embedded whitespace should be
quoted. The documentation of each command that needs these pairs, will list
the valid keys.
=item C<< >>
The integer number B of a token (not the 40 hex-character value).
=item C<< >>
One of the GitHub scopes that you can apply to a token. The C
command will tell you all of these, and what they mean.
=back
=head1 Commands
These are the commands you can use to perform most of your daily GitHub
interactions from the command line. They are installed by default.
=over
=item C
Show this manpage.
=item C
Print version info for C.
=item C
Show detailed version and environment info about your C installation.
This can be useful for figuring out things about how C is operating
in a given situation. Also good for reporting bugs / issues in C.
=item C
Before you can use the commands described below, you need to perform some
setup/configuration steps.
This "wizard" style dialog, will walk you through the configuration process
quickly and painlessly, with lots of explanation. You should run this command
right away. You can also re-run it, and it will allow you to change your
config, while defaulting to your existing settings.
If you would rather do the steps by hand, see L<#Configuration-Commands> below.
=item C
Upgrade the C installation to the latest version. Note: you need to
be running 'git-hub' from the source repo, and be on the main branch for
this to work.
=item C<< user [] >>
Show basic information about a specific user. User defaults to the owner of
the current repo, or your login if you are not inside a repo directory. The
C<--raw> and C<--json> options show the data in different formats than
normal output.
=item C<< user-get >>
Get a specific data value for a particular user.
=item C<< user-edit ... >>
Set specific fields of your user info to new values. You list the parameters
as key/value pairs.
You can edit the following user keys: C, C, C, C,
C, C.
=item C<< orgs [] >>
List the organizations that a user is a member of.
=item C<< org >>
Show basic information about a GitHub organization. The C<--raw> and C<--json>
options show the data in different formats than normal output.
=item C<< org-repos >>
Show all the repos for an organization, both public and private.
=item C<< org-members >>
List members of an organization.
=item C<< org-get >>
Get a specific data value for a particular organization.
=item C<< org-edit ... >>
Set specific meta-data fields of an organization to new values. You list the
parameters as key/value pairs.
You can edit the following organization keys: C, C,
C, C, C, C.
=item C<< teams >>
List the teams in an organization.
=item C<< team >>
Get information about a team.
=item C<< team-members >>
List members of a team.
=item C<< team-repos >>
List repos of a team.
=item C<< team-repo-add >>
Add repo to a team. Repo name must not include org name.
=item C<< team-new >>
Add a new team (name) to an organization. The 'perm' arg must be pull,
push or admin.
=item C<< team-delete >>
Delete a team.
=item C<< members | >>
List the members of an organization or team. If numeric argument, show team
members, else organization members.
=item C<< member-get >>
Show whether a user is a member of a specified team.
=item C<< member-add >>
Add a user to a team.
=item C<< member-remove >>
Remove a user from a team.
=item C<< followers [] >>
List the people who are followers of a user.
=item C<< follows [] >>
Check if C<< >> follows C<< >>. The default target
user is you.
=item C<< following [] >>
List the people that a user is following.
=item C<< follow ... >>
Follow one or more users.
=item C<< unfollow ... >>
Stop following one or more users.
=item C<< clone ([/] [])... >>
Clone a GitHub repo. Always uses C<--recursive> so you get submodules too. You
can specifiy a list of repos. If you specify a directory for a repo, it should
be an absolute path name or else begin with '.I<' or '..>' so that it can be
distinguished from another repo name.
=item C<< repos [] >>
List the repos for a user or organization. List is returned in order of
recent activity.
=item C<< repo [] >>
Show basic information about a specific repository. The C<--raw> and C<--json>
options show the data in different formats than normal output.
=item C<< repo-get / >>
Get a specific data value for a particular repository.
=item C<< repo-edit [/]... >>
Set specific meta-data fields of a repository to new values. You list the
parameters as key/value pairs.
You can edit the following repo keys: C, C.
=item C<< repo-new [/] >>
Create a new GitHub repository.
=item C<< repo-init [] >>
This command is useful for setting up new repos. Just mkdir a new dir, cd into
it and issue the command. It will 'git init', make the GitHub repo and add it
as the origin remote. It will only do the things that have not yet been done.
=item C<< repo-delete / >>
Delete a GitHub repository.
=item C<< forks [/] >>
List the forks of a repository.
=item C<< fork / [--org=] [--remote=] >>
Fork a repository to your account or to an organization. Optionally, you can
specify the name of a remote to add, pointing to your fork.
=item C<< stars [/] >>
Show what users have starred a repository.
=item C<< star [/] >>
Add your B to a repository.
=item C<< unstar [/] >>
Remove your B from a repository.
=item C<< starred [] >>
List repositories that a user has starred.
=item C<< watch [/] >>
Start watching a repo.
=item C<< unwatch [/] >>
Stop watching a repo.
=item C<< watching [] >>
Show which repos a user is watching.
=item C<< watchers [/] >>
Show the users who are watching a repo.
=item C<< collabs [/] >>
List current collaborators for a repository.
=item C<< trust [/] ... >>
Add one or more collaborators to a repository.
=item C<< untrust [/] ... >>
Remove one or more collaborators from a repository.
=item C<< issues [/] [--all] >>
List the open issues for a repo. Use the C<--all> flag to see both open and
closed issues.
=item C<< issue [/] >>
Show info (including any comments) for a specific issue. If no issue number is
given, this command will call C instead.
=item C<< issue-new [/] >>
Create a new issue for a repository.
=item C<< issue-edit [/] >>
Add a comment. Change values of 'title', 'state', 'assignee' and 'milestone'.
Changing state to 'closed' will close the issue.
=item C<< comment [/] >>
Add a comment to an issue. You can also use C to just add a
comment.
=item C<< issue-close [/] >>
Close an issue. You can also use C to close an issue.
=item C<< issue-resolve [/] >>
Add a comment to an issue and then close it.
=item C<< pr-list [/] >>
List the pull requests for a repo.
=item C<< pr-new [] [] >>
Create a new pull request for a repository based on the current branch. If an
issue ID number is given, this command will attach the pull request to the
issue instead of creating a new one.
If the default remote is a fork, the pull request will target the default
branch of the parent repository. Otherwise the pull request will target the
default branch of the default remote itself. Use C<--remote>, C<--branch>, C<--parent>, and C<--base> options to change the default source remote, source
branch, target remote and target branch (respectively).
This command will open an editor like C does. To avoid that you
can pipe text into the command.
=item C<< pr-diff [/] >>
Show the diff for a pull request.
=item C<< pr-fetch [/] >>
Fetches a pull request to a local C<review/$number> branch
=item C<< pr-merge [/] >>
Merge and close a pull request.
It supports the following options:
=over
=item * C<--sha>
=item * C<--merge-method>
=item * C<--commit-title>
=item * C<--commit-message>
=back
=item C<< pr-queue [] [--all] >>
Show a user's Pull Request queue, for all repos. Shows the open PRs for any
repo that has them. The C<--all> option says to show closed as well as open
PRs. Results are sorted by date of creation.
=item C<< pr-created [] [--all] >>
Show a list of Pull Requests the user created, for all repos. Shows the open
PRs for any repo that has them. The C<--all> option says to show closed as
well as open PRs. Results are sorted by date of creation.
=item C<< pr-involves [] [--all] >>
Show a list of Pull Requests the user is involved in. ie Pull Requests that
were created by, assigned to, mention, or were commented on by that user.
Shows the open PRs for any repo that has them. The C<--all> option says to
show closed as well as open PRs. Results are sorted by date of creation.
=item C<notify-list [--all]>
List your recent I user notifications. To list your I
notifications as well, use the C<--all> option.
