hub.1.ronn

hub(1) -- git + hub = github
============================

## SYNOPSIS

`hub` <COMMAND> <OPTIONS>  
`hub alias` [`-s`] <SHELL>

`git init -g` <OPTIONS>  
`git create` [<NAME>] [`-p`] [`-d` <DESCRIPTION>] [`-h` <HOMEPAGE>]  
`git clone` [`-p`] <OPTIONS> [<USER>/]<REPOSITORY> <DIRECTORY>  
`git remote add` [`-p`] <OPTIONS> <USER>[/<REPOSITORY>]  
`git remote set-url` [`-p`] <OPTIONS> <REMOTE-NAME> <USER>[/<REPOSITORY>]  
`git fetch` <USER-1>,[<USER-2>,...]  
`git cherry-pick` <GITHUB-REF>  
`git am` <GITHUB-URL>  
`git push` <REMOTE-1>,<REMOTE-2>,...,<REMOTE-N> [<REF>]  
`git browse` [`-u`] [[<USER>`/`]<REPOSITORY>] [SUBPAGE]  
`git compare` [`-u`] [<USER>] [<START>...]<END>  
`git submodule add` [`-p`] <OPTIONS> [<USER>/]<REPOSITORY> <DIRECTORY>  
`git fork` [`--no-remote`]  

## DESCRIPTION

`hub` enhances various `git` commands with GitHub remote expansion. The
alias command displays information on configuring your environment:

  * `hub alias` [`-s`] <SHELL>:
    Writes shell aliasing code for <SHELL> (`bash`, `sh`, `zsh`,
    `csh`) to standard output. With the `-s` option, the output of
    this command can be evaluated directly within the shell:  
    `eval $(hub alias -s bash)`

  * `git init` `-g` <OPTIONS>:
    Create a git repository as with git-init(1) and add remote `origin` at
    "git@github.com:<USER>/<REPOSITORY>.git"; <USER> is your GitHub username and
    <REPOSITORY> is the current working directory's basename.

  * `git create` [<NAME>] [`-p`] [`-d` <DESCRIPTION>] [`-h` <HOMEPAGE>]:  
    Create a new public GitHub repository from the current git
    repository and add remote `origin` at
    "git@github.com:<USER>/<REPOSITORY>.git"; <USER> is your GitHub
    username and <REPOSITORY> is the current working directory name.
    To explicitly name the new repository, pass in <NAME>, optionally in
    <ORGANIZATION>/<NAME> form to create under an organization you're a
    member of. With `-p`, create a private repository, and with `-d` and `-h`
    set the repository's description and homepage URL, respectively.

  * `git clone` [`-p`] <OPTIONS> [<USER>`/`]<REPOSITORY> <DIRECTORY>:  
    Clone repository "git://github.com/<USER>/<REPOSITORY>.git" into
    <DIRECTORY> as with git-clone(1). When <USER>/ is omitted, assumes
    your GitHub login. With `-p`, use private remote
    "git@github.com:<USER>/<REPOSITORY>.git".

  * `git remote add` [`-p`] <OPTIONS> <USER>[`/`<REPOSITORY>]:  
    Add remote "git://github.com/<USER>/<REPOSITORY>.git" as with
    git-remote(1). When /<REPOSITORY> is omitted, the basename of the
    current working directory is used. With `-p`, use private remote
    "git@github.com:<USER>/<REPOSITORY>.git". If <USER> is "origin"
    then uses your GitHub login.

  * `git remote set-url` [`-p`] <OPTIONS> <REMOTE-NAME> <USER>[/<REPOSITORY>]  
    Sets the url of remote <REMOTE-NAME> using the same rules as 
    `git remote add`.

  * `git fetch` <USER-1>,[<USER-2>,...]:
    Adds missing remote(s) with `git remote add` prior to fetching. New
    remotes are only added if they correspond to valid forks on GitHub.

  * `git cherry-pick` <GITHUB-REF>:
    Cherry-pick a commit from a fork using either full URL to the commit
    or GitHub-flavored Markdown notation, which is `user@sha`. If the remote
    doesn't yet exist, it will be added. A `git fetch <user>` is issued
    prior to the cherry-pick attempt.

  * `git am` <GITHUB-URL>:
    Downloads the patch file for the pull request or commit at the URL and
    applies that patch from disk with `git am`. Similar to `cherry-pick`, but
    doesn't add new remotes.

  * `git push` <REMOTE-1>,<REMOTE-2>,...,<REMOTE-N> [<REF>]:
    Push <REF> to each of <REMOTE-1> through <REMOTE-N> by executing
    multiple `git push` commands.

  * `git browse` [`-u`] [[<USER>`/`]<REPOSITORY>] [SUBPAGE]:
    Open repository's GitHub page in the system's default web browser using
    `open(1)` or the `BROWSER` env variable. If the repository isn't
    specified, `browse` opens the page of the repository found in the current
    directory. If SUBPAGE is specified, the browser will open on the specified
    subpage: one of "wiki", "commits", "issues" or other (the default is
    "tree").

  * `git compare` [`-u`] [<USER>] [<START>...]<END>:
    Open a GitHub compare view page in the system's default web browser.
    <START> to <END> are branch names, tag names, or commit SHA1s specifying
    the range of history to compare. If a range with two dots (`a..b`) is given,
    it will be transformed into one with three dots. If <START> is omitted,
    GitHub will compare against the base branch (the default is "master").

  * `git submodule add` [`-p`] <OPTIONS> [<USER>/]<REPOSITORY> <DIRECTORY>:  
    Submodule repository "git://github.com/<USER>/<REPOSITORY>.git" into
    <DIRECTORY> as with git-submodule(1). When <USER>/ is omitted, assumes
    your GitHub login. With `-p`, use private remote
    "git@github.com:<USER>/<REPOSITORY>.git".

  * `git fork` [`--no-remote`]:
    Forks the original project (referenced by "origin" remote) on GitHub and
    adds a new remote for it under your username. Requires `github.token` to
    be set (see CONFIGURATION).

  * `git help`:
    Display enhanced git-help(1).

## CONFIGURATION

Use git-config(1) to display the currently configured GitHub username:

    $ git config --global github.user

Or, set the GitHub username and token with:

    $ git config --global github.user <username>
    $ git config --global github.token <token>

See <http://github.com/guides/local-github-config> for more
information.

You can also tell `hub` to use `http://` rather than `git://` when
cloning:

    $ git config --global --bool hub.http-clone true

Want to use environment variables instead of a local gitconfig for
authentication?

* `GITHUB_USER`  - If set, this will be used instead of the `github.user` config
                   value to determine your GitHub username.
* `GITHUB_TOKEN` - If set, this will be used instead of the `github.token`
                   config value to determine your GitHub API token.

## EXAMPLES

### git clone

    $ git clone schacon/ticgit
    > git clone git://github.com/schacon/ticgit.git

    $ git clone -p schacon/ticgit
    > git clone git@github.com:schacon/ticgit.git

    $ git clone resque
    > git clone git://github.com/YOUR_USER/resque.git

    $ git clone -p resque
    > git clone git@github.com:YOUR_USER/resque.git

### git remote add

    $ git remote add rtomayko
    > git remote add rtomayko git://github.com/rtomayko/CURRENT_REPO.git

    $ git remote add -p rtomayko
    > git remote add rtomayko git@github.com:rtomayko/CURRENT_REPO.git

    $ git remote add origin
    > git remote add origin git://github.com/YOUR_USER/CURRENT_REPO.git

### git fetch

    $ git fetch mislav
    > git remote add mislav git://github.com/mislav/REPO.git
    > git fetch mislav

    $ git fetch mislav,xoebus
    > git remote add mislav ...
    > git remote add xoebus ...
    > git fetch --multiple mislav xoebus

### git cherry-pick

    $ git cherry-pick http://github.com/mislav/REPO/commit/SHA
    > git remote add -f mislav git://github.com/mislav/REPO.git
    > git cherry-pick SHA

    $ git cherry-pick mislav@SHA
    > git remote add -f mislav git://github.com/mislav/CURRENT_REPO.git
    > git cherry-pick SHA

    $ git cherry-pick mislav@SHA
    > git fetch mislav
    > git cherry-pick SHA

### git am

    $ git am https://github.com/defunkt/hub/pull/55
    > curl https://github.com/defunkt/hub/pull/55.patch -o /tmp/55.patch
    > git am /tmp/55.patch

    $ git am --ignore-whitespace https://github.com/davidbalbert/hub/commit/fdb9921
    > curl https://github.com/davidbalbert/hub/commit/fdb9921.patch -o /tmp/fdb9921.patch
    > git am --ignore-whitespace /tmp/fdb9921.patch

### git fork

    $ git fork
    [ repo forked on GitHub ]
    > git remote add YOUR_USER git@github.com:YOUR_USER/CURRENT_REPO.git

### git init

    $ git init -g
    > git init
    > git remote add origin git@github.com:YOUR_USER/REPO.git

### git create

    $ git create
    [ repo created on GitHub ]
    > git remote add origin git@github.com:YOUR_USER/CURRENT_REPO.git

    # with description:
    $ git create -d 'It shall be mine, all mine!'

    $ git create recipes
    [ repo created on GitHub ]
    > git remote add origin git@github.com:YOUR_USER/recipes.git

    $ git create sinatra/recipes
    [ repo created in GitHub organization ]
    > git remote add origin git@github.com:sinatra/recipes.git

### git push

    $ git push origin,staging,qa bert_timeout
    > git push origin bert_timeout
    > git push staging bert_timeout
    > git push qa bert_timeout

### git browse

    $ git browse
    > open https://github.com/YOUR_USER/CURRENT_REPO

    $ git browse -- commit/SHA
    > open https://github.com/YOUR_USER/CURRENT_REPO/commit/SHA

    $ git browse -- issues
    > open https://github.com/YOUR_USER/CURRENT_REPO/issues

    $ git browse schacon/ticgit
    > open https://github.com/schacon/ticgit

    $ git browse schacon/ticgit commit/SHA
    > open https://github.com/schacon/ticgit/commit/SHA

    $ git browse resque
    > open https://github.com/YOUR_USER/resque

    $ git browse resque network
    > open https://github.com/YOUR_USER/resque/network

### git compare

    $ git compare refactor
    > open https://github.com/CURRENT_REPO/compare/refactor

    $ git compare 1.0..1.1
    > open https://github.com/CURRENT_REPO/compare/1.0...1.1

    $ git compare -u fix
    > (https://github.com/CURRENT_REPO/compare/fix)

    $ git compare other-user patch
    > open https://github.com/other-user/REPO/compare/patch

### git help

    $ git help
    > (improved git help)
    $ git help hub
    > (hub man page)

## BUGS

<http://github.com/defunkt/hub/issues>

## AUTHORS

<https://github.com/defunkt/hub/contributors>

## SEE ALSO

git(1), git-clone(1), git-remote(1), git-init(1),
<http://github.com>,
<http://github.com/defunkt/hub>