=======
git-hub
=======
------------------------------------
Git command line interface to GitHub
------------------------------------
:Author: Leandro Lucarella <leandro.lucarella@sociomantic.com>
:Copyright: 2013 Sociomantic Labs GmbH
:Version: devel
:Date: |date|
:Manual section: 1
:Manual group: Git Manual
.. |date| date::
SYNOPSIS
========
git hub [global options] <command> [options] [arguments]
DESCRIPTION
===========
`git hub` is a simple command line interface to github, enabling most useful
GitHub tasks (like creating and listing pull request or issues) to be accessed
directly through the git command line.
To use this command you'll probably need to make an initial configuration to
get authorization from GitHub. To do this you can use the `setup` command.
See the CONFIGURATION_ section for more configuration options.
GLOBAL OPTIONS
==============
\-h, --help
Show this help and exit.
\--version
Show program's version number and exit.
\-v, --verbose
Be more verbose (can be specified multiple times to get extra verbosity)
\-s, --silent
Be less verbose (can be specified multiple times to get less verbosity)
COMMANDS
========
`setup`
This command performs an initial setup to connect to GitHub. It basically
asks GitHub for an authorization token and stores it in the Git configuration
variable `hub.oauthtoken` for future use so you don't need to type your
password each time (or store it in the config). The username is also stored
for future use in the `hub.username` variable. If the base URL is specified,
it is stored in `hub.baseurl` too. By default configuration is stored in the
repository's ``.git/config`` file (using ``git config``). If you want your
configuration to be global to your user or system-wide, use the ``--global``
or ``--system`` option respectively. These options are passed straight to
``git config``.
\-u USERNAME, --username=USERNAME
GitHub's username (login name), will be stored in the configuration
variable `hub.username`. If an e-mail is provided, then a username matching
that e-mail will be searched and used instead, if found (for this to work
the e-mail must be part of the public profile).
\-p PASSWORD, --password=PASSWORD
GitHub's password (will not be stored).
\-b URL, --baseurl=URL
GitHub's base URL to use to access the API. Set this when you GitHub API is
in another location other than the default (Enterprise servers usually use
https://host/api/v3).
\--global
Store settings in the global configuration (see --global option in `git
config(1)` for details).
\--system
Store settings in the system configuration (see --system option in `git
config(1)` for details).
`clone` REPO [DEST]
This command is used to clone **REPO**, a GitHub repository, to a **DEST**
directory (defaults to the name of the project being cloned). If the
repository is specified in *<owner>/<project>* form, the **REPO** will be
used as upstream and a personal fork will be looked up. If none is found,
a new fork will be created. In both cases, the fork will be cloned instead of
the upstream repository. The **REPO** can be specified as a regular *clone*
URL too (http, ssh, git), in that case the URL will be inspected and the
`hub.urltype` will be set as appropriate.
If only *<project>* is specified as **REPO**, then the configuration
`hub.username` is used as *<owner>*, and the parent repository is looked up
at GitHub to determine the real upstream repository.
The upstream repository is also added as a remote by the name `upstream`
(unless **--triangular** is used, in which case the remote is called `fork`
by default) and the `hub.upstream` configuration variable is set (see
CONFIGURATION_), unless only *<project>* was used and the resulting
repository is not really a fork, in which case is impossible to automatically
determine the upstream repository.
\-r NAME, --remote=NAME
Use `NAME` as the upstream remote repository name instead of the default
('fork' if **--triangular** is used, 'upstream' otherwise).
\-t, --triangular
Use Git's *triangular workflow* configuration. This option clones from the
parent/upstream repository instead of cloning the fork, and adds the fork
as a remote repository. Then sets the `remote.pushdefault` Git option and
`hub.forkremote` git-hub option to the fork.
The effect of this having the upstream repository used by default
when you pull but using your fork when you push, which is typically what
you want when using GitHub's pull requests.
Git version 1.8.3 or newer is needed to use this option (and 1.8.4 or newer
is recommended due to some issues in 1.8.3 related to this).
This option might become the default in the future. To make it the default
you can set the option `hub.triangular`. See CONFIGURATION_ for details.
GIT CLONE OPTIONS
Any standard **git clone** option can be passed. Not all of them might make
sense when cloning a GitHub repo to be used with this tool though.
`issue`
This command is used to manage GitHub issues through a set of subcommands.
`list`
Show a list of open issues.
\-c, --closed
Show closed issues instead.
\-C, --created-by-me
Show only issues created by me
\-A, --assigned-to-me
Show only issues assigned to me
`show` ISSUE [ISSUE ...]
Show issues identified by **ISSUE**.
`new`
Create a new issue.
\-m MSG, --message=MSG
Issue title (and description). The first line is used as the issue title
and any text after an empty line is used as the optional body. If this
option is not used, the default `GIT_EDITOR` is opened to write one.
\-l LABEL, --label=LABEL
Attach `LABEL` to the issue (can be specified multiple times to set
multiple labels).
\-a USER, --assign=USER
Assign a user to the issue. `USER` must be a valid GitHub login name.
\-M ID, --milestone=ID
Assign the milestone identified by the number ID to the issue.
`update` ISSUE
Similar to `new` but update an existing issue identified by **ISSUE**.
A convenient shortcut to close an issue is provided by the `close`
subcommand.
\-m MSG, --message=MSG
New issue title (and description). The first line is used as the issue
title and any text after an empty line is used as the optional body.
\-e, --edit-message
Open the default `GIT_EDITOR` to edit the current title (and description)
of the issue.
\-o, --open
Reopen the issue.
\-c, --close
Close the issue.
\-l LABEL, --label=LABEL
If one or more labels are specified, they will replace the current issue
labels. Otherwise the labels are unchanged. If one of the labels is
empty, the labels will be cleared (so you can use **-l''** to clear the
labels of an issue.
\-a USER, --assign=USER
Assign a user to the issue. `USER` must be a valid GitHub login name.
\-M ID, --milestone=ID
Assign the milestone identified by the number ID to the issue.
`comment` ISSUE
Add a new comment to an existing issue identified by **ISSUE**.
\-m MSG, --message=MSG
Comment to be added to the issue. If this option is not used, the default
`GIT_EDITOR` is opened to write the comment.
`close` ISSUE
Alias for `update --close`. (+ `comment` if **--message** or
**--edit-message** is specified). Closes issue identified by **ISSUE**.
\-m MSG, --message=MSG
Add a comment to the issue before closing it.
\-e, --edit-message
Open the default `GIT_EDITOR` to write a comment to be added to the issue
before closing it.
`pull`
This command is used to manage GitHub pull requests. Since pull requests in
GitHub are also issues, most of the subcommands are repeated from the
`issue` command for convenience. Only the `list` and `new` commands are
really different, and `attach` and `rebase` are added.
`list`
Show a list of open pull requests.
\--closed
Show closed pull requests instead.
`show` PULL [PULL ...]
Alias for `issue show`.
`checkout` PULL ...
Checkout the remote branch (head) of the pull request. This command first
fetches the *head* reference from the pull request and then calls the
standard `git checkout` command and any extra argument will be passed
to `git checkout` as-is, after the reference that was just fetched.
Remember this creates a detached checkout by default, use `-b` if you
want to create a new branch based on the pull request. Please take a
look at `git checkout` help for more details.
`new` [HEAD]
Create a new pull request. If **HEAD** is specified, it will be used as the
branch (or git ref) where your changes are implemented. Otherwise the
current branch is used. If the branch used as head is not pushed to your
fork remote, a push will be automatically done before creating the pull
request.
The repository to issue the pull request from is taken from the
`hub.forkrepo` configuration, which defaults to
*hub.username/<hub.upstream project part>*.
\-m MSG, --message=MSG
Pull request title (and description). The first line is used as the pull
request title and any text after an empty line is used as the optional
body. If this option is not used, the default `GIT_EDITOR` is opened.
If the HEAD branch have a proper description (see `git branch
--edit-description`), that description will be used as the default
message in the editor and if not, the message of the last commit will be
used instead.
\-b BASE, --base=BASE
Branch (or git ref) you want your changes pulled into. By default the
tracking branch (`branch.<ref>.merge` configuration variable) is used or
the configuration `hub.pullbase` if not tracking a remote branch. If none
is present, it defaults to **master**. The repository to use as the base
is taken from the `hub.upstream` configuration.
\-c NAME, --create-branch=NAME
Create a new remote branch with (with name **NAME**) as the real head for
the pull request instead of using the HEAD name passed as **HEAD**. This
is useful to create a pull request for a hot-fix you committed to your
regular HEAD without creating a branch first.
\-f, --force-push
Force the push operations. Use with care!
`attach` ISSUE [HEAD]
Convert the issue identified by **ISSUE** to a pull request by attaching
commits to it. The branch (or git ref) where your changes are
implemented can be optionally specified with **HEAD** (otherwise the
current branch is used). This subcommand is very similar to the `new`
subcommand, please refer to it for more details.
Please note you can only attach commits to issues if you have commit access
to the repository or if you are assigned to the issue.
\-m MSG, --message=MSG
Add a comment to the issue/new pull request.
\-e, --edit-message
Open the default `GIT_EDITOR` to write a comment to be added to the
issue/new pull request. The default message is taken from the
**--message** option if present, otherwise the branch description or the
first commit message is used as with the `new` subcommand.
\-b BASE, --base=BASE
Base branch to which issue the pull request. If this option is not
present, then the base branch is taken from the configuration
`hub.pullbase` (or just **master** if that configuration is not present
either). The repository to use as the base is taken from the
`hub.upstream` configuration.
\-c NAME, --create-branch=NAME
Create a new remote branch with (with name **NAME**) as the real head for
the pull request instead of using the HEAD name passed as **HEAD**. This
is useful to create a pull request for a hot-fix you committed to your
regular HEAD without creating a branch first.
\-f, --force-push
Force the push operations. Use with care!
`rebase` PULL
Close a pull request identified by **PULL** by rebasing its base branch
(specified in the pull request) instead of merging as GitHub's *Merge
Button™* would do.
If the operation is successful, a comment will be posted informing the new
HEAD commit of the branch that has been rebased and the pull request will
be closed.
The type of URL used to fetch and push can be specified through the
`hub.pullurltype` configuration variable (see CONFIGURATION_ for more
details). Your working copy should stay the same ideally, if everything
went OK.
The operations performed by this subcommand are roughly these:
1. git stash
2. git fetch `pullhead`
3. git checkout -b `tmp` FETCH_HEAD
4. git pull --rebase `pullbase`
5. git push `pullbase`
6. git checkout `oldhead`
7. git branch -D `tmp`
8. git stash pop
If `hub.forcerebase` is set to "true" (the default), ``--force`` will be
passed to rebase (not to be confused with this command option
``--force-push`` which will force the push), otherwise (if is "false")
a regular rebase is performed. When the rebase is forced, all the commits
in the pull request are re-committed, so the Committer and CommitterDate
metadata is updated in the commits, showing the person that performed the
rebase and the time of the rebase instead of the original values, so
providing more useful information. As a side effect, the hashes of the
commits will change.
If conflicts are found, the command is interrupted, similarly to how `git
rebase` would do. The user should either **--abort** the rebasing,
**--skip** the conflicting commit or resolve the conflict and
**--continue**. When using one of these actions, you have to omit the
**PULL** argument.
\-m MSG, --message=MSG
Use this message for the comment instead of the default. Specify an empty
message (**-m''**) to completely omit the comment.
\-e, --edit-message
Open the default `GIT_EDITOR` to write the comment.
\--force-push
Force the push operations. Use with care!
\-p, --pause
Pause the rebase just before the results are pushed and the issue is
merged. To resume the pull request rebasing (push the changes upstream
and close the issue), just use the **--continue** action. This is
particularly useful for testing.
\-u, --stash-include-untracked
Passes the **--include-untracked** option to stash. If used all untracked
files are also stashed and then cleaned up with git clean, leaving the
working directory in a very clean state, which avoid conflicts when
checking out the pull request to rebase.
\-a, --stash-all
Passes the **--all** option to stash. Is like
**--stash-include-untracked** but the ignored files are stashed and
cleaned in addition to the untracked files, which completely removes the
possibility of conflicts when checking out the pull request to rebase.
\-D, --delete-branch
Delete the pull request branch if the rebase was successful. This is
similar to press the "Delete Branch" Button (TM) in the web interface
after merging.
Actions:
\--continue
Continue an ongoing rebase.
\--abort
Abort an ongoing rebase.
\--skip
Skip current patch in an ongoing rebase and continue.
`update` PULL
Alias for `issue update`.
`comment` PULL
Alias for `issue comment`.
`close` PULL
Alias for `issue close`.
CONFIGURATION
=============
This program use the git configuration facilities to get its configuration
from. These are the git config keys used:
`hub.username`
Your GitHub username. [default: *current OS username*]
`hub.oauthtoken` required
This is the authorization token obtained via the `setup` command. Even when
required, you shouldn't need to set this variable manually. Use the `setup`
command instead.
`hub.upstream` required
Blessed repository used to get the issues from and make the pull requests to.
The format is *<owner>/<project>*. This option can be automatically set by
the `clone` command and is not really required by it or the `setup` command.
`hub.forkrepo`
Your blessed repository fork. The format is *<owner>/<project>*. Used to set
the head for your pull requests. [default: *<username>/(upstream <project>
part)*]
`hub.forkremote`
Remote name for accessing your fork. Used to push branches before creating
a pull request. [default: *origin*]
`hub.pullbase`
Default remote branch (or git reference) you want your changes pulled into
when creating a pull request. [default: *master*]
`hub.urltype`
Type of URL to use when an URL from a GitHub API is needed (for example,
when 'pull rebase' is used). At the time of writing it could be *ssh_url*
or *clone_url* for HTTP). See GitHub's API documentation[1] for more
details or options. [default: *ssh_url*]
`hub.baseurl`
GitHub's base URL to use to access the API. Set this when you GitHub API is
in another location other than the default (Enterprise servers usually use
https://host/api/v3). This will be prepended to all GitHub API calls and it
has to be a full URL, not just something like "www.example.com/api/v3/".
`hub.forcerebase`
If is set to "true", ``--force`` will be passed to rebase. If is set to
"false" a regular rebase is performed. See the `pull` `rebase` command for
details. [default: *true*]
`hub.triangular`
Makes **--triangular** for `clone` if set to "true" (boolean value). See
`clone` documentation for details.
[1] https://developer.github.com/v3/pulls/#get-a-single-pull-request
FILES
=====
This program creates some temporary files in the '.git' directory during its
operation. The contents of these files can be used for debugging/recovery
purposes if necessary.
`HUB_EDITMSG`
This file is used to take input from the user, e.g. issue comments, pull
request title & description etc. If, after accepting user input, the command
given by the user fails for some reason, then the entered text can still be
retrieved from this file.
`HUB_PULL_REBASING`
This file is used to store various metadata information related to a rebase
operation (with the primary aim of being able to rollback the repository to
its original state if the rebase fails or is interrupted due to conflicts).
The sole presence of this file indicates that a rebase is in progress.
VIM SYNTAX HIGHLIGHT
====================
A VIM ftdetect plugin is provided, to enable it you have to follow some steps
though. All you need to do is copy (or preferably make a symbolic link) the
script to `~/.vim/ftdetect/githubmsg.vim`::
mkdir -p ~/.vim/ftdetect
ln -s /usr/share/vim/addons/githubmsg.vim ~/.vim/ftdetect/
# or if you are copying from the sources:
# ln -s ftdetect.vim ~/.vim/ftdetect/githubmsg.vim
.. vim: set et sw=2 :