# Easier GitHub interactions with Hub

Have you ever wished you could initialize a remote repository from the command
line? With Hub, it’s possible.

[Hub](https://hub.github.com/) is useful. Basically, it makes life easier by
letting you interact with GitHub more from the command line.

Here are some examples of what it can do for you:

- Create a GitHub repo.
- Open different GitHub pages.
- Easier repo inits.

## Install it

On a Mac, the easiest installation method is through Homebrew:

```shell
$ brew install --HEAD hub
```

[Here’s a tutorial](http://eoinoc.net/install-hub-github-linux-mint/) on how to
install it on Linux.

Then alias hub with git. Pop open `~/.aliases` and add the following to the
bottom of the file:

```bash
alias git=hub
```

Test if it works:

```shell
$ git --version
# If it returns the following, it works
git version 2.0.0
hub version 2.2.0
```

## Configure Hub

> Hub will prompt for GitHub username & password the first time it needs to
> access the API and exchange it for an OAuth token, which it saves in
> `~/.config/hub`.

Test it quickly by making a test repo:

```shell
$ mkdir git-test && cd git-test
$ touch README.md
$ git init
```

Now here’s the sauce:

```shell
$ git create
```

That command will prompt you for a password and a username. For whatever reason,
it returned the following error for me:

```
Post ssh://api.github.com/user/repos: unsupported protocol scheme "ssh"
```

I changed `protocol:` to `https` in `~/.config/hub`, and it worked. The config
file should look something like this:

```
github.com:
- user: bob
    oauth_token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    protocol: https
```

> **Note:** You should authenticate to GitHub with SSH keys.
> [more info in this GitHub tutorial](https://help.github.com/articles/generating-ssh-keys/).

**Note:** There’s a catch when setting the protocol to HTTPS. GitHub then
prompts you for a password every time you push or pull. That is the intended
behavior. Either live with it or cache your credentials. See the
[GitHub tutorial](https://help.github.com/articles/caching-your-github-password-in-git/)
how to do that.

## Usage examples

If you’re unsure what the command does, you can safely test them with the
`--noop` flag:

```shell
$ hub --noop create
git remote add -f origin https://github.com/hilja/git-test.git
echo created repository: hilja/git-test
```

It shows what the command would do without actually doing anything.

### Initiating git in a new directory

Here’s an example of how initialization differs when using Hub.

Normal init without hub:

```shell
$ init
$ git remote -v
# The git remote command returns nothing cause there is no remote
```

Then with Hub:

```shell
$ git init -g
Initialized empty Git repository in /Users/bob/code/git-test/.git/
$ git remote -v
origin  https://github.com/hilja/git-test.git (fetch)
origin  https://github.com/hilja/git-test.git (push)
```

Hub sets those remotes automatically.

### Creating repositories with Hub

The create syntax:

```
git create [NAME] [-p] [-d DESCRIPTION] [-h HOMEPAGE]
```

```shell
$ git create -d "This just a test repo, ignore"
origin  https://github.com/hilja/git-test.git (fetch)
origin  https://github.com/hilja/git-test.git (push)
created repository: hilja/git-test
```

That makes the remote repo.

### Browse with Hub

The `browse` command will open the project’s GitHub page into your default
browser:

```shell
$ git browse
```

Or open GitHub issues page:

```shell
$ git browse -- issues
```

Or the pull requests page:

```shell
$ git browse -- pull
```

### Clone a repo with Hub

If it’s your own repo, only a repo name is needed:

```shell
$ git clone test-repo
```

Not your own:

```shell
$ git clone someone-else/test-repo
```

[See the Hub website](https://hub.github.com/) for more examples, or the
[man page](https://hub.github.com/hub.1.html) for details.