README.md 8.5 KB
Newer Older
C
Chris Wanstrath 已提交
1 2
hub: git + hub = github
=======================
C
readme  
Chris Wanstrath 已提交
3

C
Chris Wanstrath 已提交
4
`hub` is a command line utility which adds GitHub knowledge to `git`.
C
readme  
Chris Wanstrath 已提交
5

C
Chris Wanstrath 已提交
6
It can used on its own or as a `git` wrapper.
C
readme  
Chris Wanstrath 已提交
7

C
Chris Wanstrath 已提交
8
Normal:
C
Chris Wanstrath 已提交
9 10

    $ hub clone rtomayko/tilt
C
tweak  
Chris Wanstrath 已提交
11

12 13
    Expands to:
    $ git clone git://github.com/rtomayko/tilt.git
C
Chris Wanstrath 已提交
14

C
Chris Wanstrath 已提交
15
Wrapping `git`:
C
Chris Wanstrath 已提交
16 17 18

    $ git clone rack/rack

C
tweak  
Chris Wanstrath 已提交
19 20 21
    Expands to:
    $ git clone git://github.com/rack/rack.git

22
hub requires you have `git` installed and in your `$PATH`. It also
C
Chris Wanstrath 已提交
23
requires Ruby 1.8.6+ or Ruby 1.9.1+. No other libraries necessary.
C
tweaks  
Chris Wanstrath 已提交
24

C
readme  
Chris Wanstrath 已提交
25

C
Chris Wanstrath 已提交
26
Install
C
readme  
Chris Wanstrath 已提交
27 28
-------

C
Chris Wanstrath 已提交
29 30
### Standalone

C
tweaks  
Chris Wanstrath 已提交
31
`hub` is most easily installed as a standalone script:
C
Chris Wanstrath 已提交
32

33
    curl http://chriswanstrath.com/hub/standalone -sLo ~/bin/hub &&
C
Chris Wanstrath 已提交
34
    chmod 755 ~/bin/hub
C
Chris Wanstrath 已提交
35

36
Assuming `~/bin/` is in your `$PATH`, you're ready to roll:
C
Chris Wanstrath 已提交
37

C
Chris Wanstrath 已提交
38
    $ hub version
39 40
    git version 1.7.0.4
    hub version 1.1.0
C
Chris Wanstrath 已提交
41

42 43
### Homebrew

44 45 46 47 48
    $ brew install hub
    $ which hub
    /usr/local/bin/hub
    $ hub version
    ...
49

50
### RubyGems
C
Chris Wanstrath 已提交
51

52
Though not recommended, `hub` can also be installed as a RubyGem:
C
Chris Wanstrath 已提交
53

C
Chris Wanstrath 已提交
54
    $ gem install git-hub
C
Chris Wanstrath 已提交
55

56
Yes, the gem name is "git-hub".
C
Chris Wanstrath 已提交
57

58 59
(It's not recommended for casual use because of the RubyGems startup
time. See [this gist][speed] for information.)
60

61 62
### Standalone via RubyGems

63
Yes, the gem name is still "git-hub":
64 65 66

    $ gem install git-hub
    $ hub hub standalone > ~/bin/hub && chmod 755 ~/bin/hub
67 68 69

This installs a standalone version which doesn't require RubyGems to
run.
70

C
Chris Wanstrath 已提交
71 72
### Source

C
Chris Wanstrath 已提交
73
You can also install from source:
C
readme  
Chris Wanstrath 已提交
74 75 76

    $ git clone git://github.com/defunkt/hub.git
    $ cd hub
77
    $ rake install prefix=/usr/local
C
readme  
Chris Wanstrath 已提交
78

C
Chris Wanstrath 已提交
79 80 81 82 83 84 85
### Help! It's Slow!

Is your prompt slow? It may be hub.

1. Check that it's **not** installed using RubyGems.
2. Check that RUBYOPT isn't loading anything shady:

86
    `$ echo $RUBYOPT`
C
Chris Wanstrath 已提交
87 88 89

3. Check that your system Ruby is speedy:

90
    `$ time /usr/bin/env ruby -e0`
C
Chris Wanstrath 已提交
91 92 93

If #3 is slow, it may be your [GC settings][gc].

C
readme  
Chris Wanstrath 已提交
94

C
Chris Wanstrath 已提交
95 96
Aliasing
--------
C
readme  
Chris Wanstrath 已提交
97

98
`hub` works best when it wraps `git`. This is not dangerous - your
C
Chris Wanstrath 已提交
99
normal git commands should all work. hub merely adds some sugar.
C
readme  
Chris Wanstrath 已提交
100

C
Chris Wanstrath 已提交
101 102
Typing `hub alias <shell>` will display alias instructions for
your shell. `hub alias` alone will show the known shells.
C
readme  
Chris Wanstrath 已提交
103

C
Chris Wanstrath 已提交
104 105 106 107 108 109 110
For example:

    $ hub alias bash
    Run this in your shell to start using `hub` as `git`:
      alias git=hub

You should place this command in your `.bash_profile` or other startup
C
Chris Wanstrath 已提交
111
script to ensure runs on login.
C
Chris Wanstrath 已提交
112 113 114 115

The alias command can also be eval'd directly using the `-s` flag:

    $ eval `hub alias -s bash`
C
tweaks  
Chris Wanstrath 已提交
116

C
readme  
Chris Wanstrath 已提交
117

C
Chris Wanstrath 已提交
118
Commands
C
readme  
Chris Wanstrath 已提交
119 120
--------

C
Chris Wanstrath 已提交
121
Assuming you've aliased `hub` to `git` the following commands now have
C
Chris Wanstrath 已提交
122 123
superpowers:

C
readme  
Chris Wanstrath 已提交
124 125 126
### git clone

    $ git clone schacon/ticgit
C
Chris Wanstrath 已提交
127 128
    > git clone git://github.com/schacon/ticgit.git

C
readme  
Chris Wanstrath 已提交
129
    $ git clone -p schacon/ticgit
C
Chris Wanstrath 已提交
130
    > git clone git@github.com:schacon/ticgit.git
C
readme  
Chris Wanstrath 已提交
131

132 133 134 135 136 137
    $ 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

C
readme  
Chris Wanstrath 已提交
138 139 140
### git remote add

    $ git remote add rtomayko
C
Chris Wanstrath 已提交
141 142
    > git remote add rtomayko git://github.com/rtomayko/CURRENT_REPO.git

K
Konstantin Haase 已提交
143
    $ git remote add -p rtomayko
C
Chris Wanstrath 已提交
144
    > git remote add rtomayko git@github.com:rtomayko/CURRENT_REPO.git
C
readme  
Chris Wanstrath 已提交
145

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

149 150 151 152 153 154 155 156 157 158 159
### 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

160 161 162 163 164 165 166 167 168 169 170 171 172 173
### 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

174 175 176 177
### git fork

    $ git fork
    ... hardcore forking action ...
C
Chris Wanstrath 已提交
178
    > git remote add -f YOUR_USER git@github.com:YOUR_USER/CURRENT_REPO.git
179

C
Chris Wanstrath 已提交
180 181 182
Forks the original repo on GitHub and adds the new remote under your
username. It requires your GitHub token to be present; see "GitHub
login" below for details.
183

184 185 186 187 188 189 190 191 192
### git create

    $ git create
    ... hardcore creating action ...
    > git remote add origin git@github.com:YOUR_USER/CURRENT_REPO.git

Creates a new public github repository and adds the remote `origin` at
"git@github.com:<USER>/<REPOSITORY>.git"

C
readme  
Chris Wanstrath 已提交
193 194
### git init

C
Chris Wanstrath 已提交
195
    $ git init -g
C
Chris Wanstrath 已提交
196
    > git init
197
    > git remote add origin git@github.com:YOUR_USER/REPO.git
C
Chris Wanstrath 已提交
198

199 200 201 202 203 204 205
### git push

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

206 207
### git browse

208
    $ git browse
209
    > open https://github.com/CURRENT_REPO
210

211
    $ git browse -- issues
212
    > open https://github.com/CURRENT_REPO/issues
213

214
    $ git browse schacon/ticgit
215
    > open https://github.com/schacon/ticgit
216 217

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

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

J
Joshua Roesslein 已提交
223 224 225
### git compare

    $ git compare refactor
226
    > open https://github.com/CURRENT_REPO/compare/refactor
J
Joshua Roesslein 已提交
227 228

    $ git compare 1.0...1.1
229
    > open https://github.com/CURRENT_REPO/compare/1.0...1.1
J
Joshua Roesslein 已提交
230 231

    $ git compare -u fix
232
    > (https://github.com/CURRENT_REPO/compare/fix)
J
Joshua Roesslein 已提交
233

234
    $ git compare other-user patch
235
    > open https://github.com/other-user/REPO/compare/patch
J
Joshua Roesslein 已提交
236

J
Justin Ridgewell 已提交
237
### git submodule
238

J
Justin Ridgewell 已提交
239 240 241 242 243 244
    $ hub submodule add wycats/bundler vendor/bundler
    > git submodule add git://github.com/wycats/bundler.git vendor/bundler

    $ hub submodule add -p wycats/bundler vendor/bundler
    > git submodule add git@github.com:wycats/bundler.git vendor/bundler

245
    $ hub submodule add -b ryppl ryppl/pip vendor/pip
J
Justin Ridgewell 已提交
246 247 248
    > git submodule add -b ryppl git://github.com/ryppl/pip.git vendor/pip


C
Chris Wanstrath 已提交
249 250 251 252
### git help

    $ git help
    > (improved git help)
C
Chris Wanstrath 已提交
253 254
    $ git help hub
    > (hub man page)
C
readme  
Chris Wanstrath 已提交
255 256


C
Chris Wanstrath 已提交
257 258 259 260
GitHub Login
------------

To get the most out of `hub`, you'll want to ensure your GitHub login
261
is stored locally in your Git config or environment variables.
C
Chris Wanstrath 已提交
262 263 264 265 266 267 268

To test it run this:

    $ git config --global github.user

If you see nothing, you need to set the config setting:

C
Chris Wanstrath 已提交
269
    $ git config --global github.user YOUR_USER
C
Chris Wanstrath 已提交
270

271 272
For commands that require write access to GitHub (such as `fork`), you'll want to
setup "github.token" as well. See [local GitHub config guide][2] for more information.
C
Chris Wanstrath 已提交
273

274 275 276 277 278 279
Want to use environment variables instead of a local gitconfig?

* `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.
C
Chris Wanstrath 已提交
280

C
Chris Wanstrath 已提交
281 282 283 284
Configuration
-------------

If you prefer `http://` clones to `git://` clones, you can set the
285
`hub.http-clone` option to true using `git-config`.
C
Chris Wanstrath 已提交
286 287 288 289 290

For example:

    $ git clone defunkt/repl
    < git clone >
291
    $ git config --global --bool hub.http-clone true
C
Chris Wanstrath 已提交
292 293 294 295 296 297 298 299 300 301
    $ git clone defunkt/repl
    < http clone >

Or you can enter this manually into your `~/.gitconfig` file:

    $ cat ~/.gitconfig
    [hub]
      http-clone = yes


C
Chris Wanstrath 已提交
302
Prior Art
C
readme  
Chris Wanstrath 已提交
303 304 305 306 307 308 309 310 311 312
---------

These projects also aim to either improve git or make interacting with
GitHub simpler:

* [eg](http://www.gnome.org/~newren/eg/)
* [github-gem](http://github.com/defunkt/github-gem)
* [gh](http://github.com/visionmedia/gh)


C
Chris Wanstrath 已提交
313 314 315 316 317 318 319 320 321 322 323
Contributing
------------

Once you've made your great commits:

1. [Fork][0] hub
2. Create a topic branch - `git checkout -b my_branch`
3. Push to your branch - `git push origin my_branch`
4. Create an [Issue][1] with a link to your branch
5. That's it!

324 325 326 327 328 329 330 331 332
### Development Gems
You will need the following gems (and their dependencies) to
contribute to `hub`:

* `rake` (`gem install rake`)
* `kicker` (`gem install kicker`)
* `turn` (`gem install turn`)
* `mg` (`gem install mg`)
* `ronn` (`gem install ronn`)
C
Chris Wanstrath 已提交
333
* `webmock` (`gem install webmock`)
C
Chris Wanstrath 已提交
334

C
Chris Wanstrath 已提交
335 336
Meta
----
C
readme  
Chris Wanstrath 已提交
337

C
Chris Wanstrath 已提交
338 339 340 341
* Code: `git clone git://github.com/defunkt/hub.git`
* Home: <http://github.com/defunkt/hub>
* Bugs: <http://github.com/defunkt/hub/issues>
* List: <http://groups.google.com/group/github>
C
Chris Wanstrath 已提交
342 343
* Test: <http://runcoderun.com/defunkt/hub>
* Gems: <http://gemcutter.org/gems/git-hub>
C
Chris Wanstrath 已提交
344 345


C
Chris Wanstrath 已提交
346 347
Authors
-------
C
Chris Wanstrath 已提交
348

C
Chris Wanstrath 已提交
349
<https://github.com/defunkt/hub/contributors>
C
Chris Wanstrath 已提交
350 351 352

[0]: http://help.github.com/forking/
[1]: http://github.com/defunkt/hub/issues
353
[speed]: http://gist.github.com/284823
354
[2]: http://github.com/guides/local-github-config
C
Chris Wanstrath 已提交
355
[gc]: https://twitter.com/brynary/status/49560668994674688