github.com/trevoraustin/hub@v2.2.0-preview1.0.20141105230840-96d8bfc654cc+incompatible/README.md (about) 1 git + hub = github 2 ================== 3 4 hub is a command line tool that wraps `git` in order to extend it with extra 5 features and commands that make working with GitHub easier. 6 7 ~~~ sh 8 $ hub clone rtomayko/tilt 9 10 # expands to: 11 $ git clone git://github.com/rtomayko/tilt.git 12 ~~~ 13 14 hub is best aliased as `git`, so you can type `$ git <command>` in the shell and 15 get all the usual `hub` features. See "Aliasing" below. 16 17 18 Installation 19 ------------ 20 21 Dependencies: 22 23 * **git 1.7.3** or newer 24 25 ### 2.x 26 27 Starting from 2.2.0, `hub` is [powered by Go](https://github.com/github/hub/issues/475). 28 It should maintain a high backward compatibility with 1.x. Note that 2.x is in preview. 29 30 #### Homebrew 31 32 `hub` 2.x can be installed through Homebrew. Since it's in preview, you need to compile 33 from HEAD: 34 35 ~~~ sh 36 $ brew install --HEAD hub 37 ~~~ 38 39 #### Standalone 40 41 `hub` 2.x can be easily installed as an executable. Download the latest 42 [complied binaries](https://github.com/github/hub/releases) and put it anywhere in your executable path. 43 44 #### Source 45 46 To install `hub` 2.x from source, you need to have a [Go development environment](http://golang.org/doc/install), 47 version 1.1 or better: 48 49 ~~~ sh 50 $ git clone https://github.com/github/hub.git 51 $ cd hub 52 $ ./script/build 53 $ cp hub YOUR_BIN_PATH 54 ~~~ 55 56 ### 1.x 57 58 #### Homebrew 59 60 Installing on OS X is easiest with Homebrew: 61 62 ~~~ sh 63 $ brew install hub 64 ~~~ 65 66 Now you should be ready to roll: 67 68 ~~~ sh 69 $ hub version 70 git version 1.7.6 71 hub version 1.8.3 72 ~~~ 73 74 75 Aliasing 76 -------- 77 78 Using hub feels best when it's aliased as `git`. This is not dangerous; your 79 _normal git commands will all work_. hub merely adds some sugar. 80 81 `hub alias` displays instructions for the current shell. With the `-s` flag, it 82 outputs a script suitable for `eval`. 83 84 You should place this command in your `.bash_profile` or other startup script: 85 86 ~~~ sh 87 eval "$(hub alias -s)" 88 ~~~ 89 90 ### Shell tab-completion 91 92 hub repository contains tab-completion scripts for bash and zsh. These scripts 93 complement existing completion scripts that ship with git. 94 95 * [hub bash completion](https://github.com/github/hub/blob/master/etc/hub.bash_completion.sh) 96 * [hub zsh completion](https://github.com/github/hub/blob/master/etc/hub.zsh_completion) 97 98 99 Commands 100 -------- 101 102 Assuming you've aliased hub as `git`, the following commands now have 103 superpowers: 104 105 ### git clone 106 107 $ git clone schacon/ticgit 108 > git clone git://github.com/schacon/ticgit.git 109 110 $ git clone -p schacon/ticgit 111 > git clone git@github.com:schacon/ticgit.git 112 113 $ git clone resque 114 > git clone git@github.com/YOUR_USER/resque.git 115 116 ### git remote add 117 118 $ git remote add rtomayko 119 > git remote add rtomayko git://github.com/rtomayko/CURRENT_REPO.git 120 121 $ git remote add -p rtomayko 122 > git remote add rtomayko git@github.com:rtomayko/CURRENT_REPO.git 123 124 $ git remote add origin 125 > git remote add origin git://github.com/YOUR_USER/CURRENT_REPO.git 126 127 ### git fetch 128 129 $ git fetch mislav 130 > git remote add mislav git://github.com/mislav/REPO.git 131 > git fetch mislav 132 133 $ git fetch mislav,xoebus 134 > git remote add mislav ... 135 > git remote add xoebus ... 136 > git fetch --multiple mislav xoebus 137 138 ### git cherry-pick 139 140 $ git cherry-pick http://github.com/mislav/REPO/commit/SHA 141 > git remote add -f mislav git://github.com/mislav/REPO.git 142 > git cherry-pick SHA 143 144 $ git cherry-pick mislav@SHA 145 > git remote add -f mislav git://github.com/mislav/CURRENT_REPO.git 146 > git cherry-pick SHA 147 148 $ git cherry-pick mislav@SHA 149 > git fetch mislav 150 > git cherry-pick SHA 151 152 ### git am, git apply 153 154 $ git am https://github.com/defunkt/hub/pull/55 155 [ downloads patch via API ] 156 > git am /tmp/55.patch 157 158 $ git am --ignore-whitespace https://github.com/davidbalbert/hub/commit/fdb9921 159 [ downloads patch via API ] 160 > git am --ignore-whitespace /tmp/fdb9921.patch 161 162 $ git apply https://gist.github.com/8da7fb575debd88c54cf 163 [ downloads patch via API ] 164 > git apply /tmp/gist-8da7fb575debd88c54cf.txt 165 166 ### git fork 167 168 $ git fork 169 [ repo forked on GitHub ] 170 > git remote add -f YOUR_USER git@github.com:YOUR_USER/CURRENT_REPO.git 171 172 ### git pull-request 173 174 # while on a topic branch called "feature": 175 $ git pull-request 176 [ opens text editor to edit title & body for the request ] 177 [ opened pull request on GitHub for "YOUR_USER:feature" ] 178 179 # explicit title, pull base & head: 180 $ git pull-request -m "Implemented feature X" -b defunkt:master -h mislav:feature 181 182 ### git checkout 183 184 $ git checkout https://github.com/defunkt/hub/pull/73 185 > git remote add -f -t feature mislav git://github.com/mislav/hub.git 186 > git checkout --track -B mislav-feature mislav/feature 187 188 $ git checkout https://github.com/defunkt/hub/pull/73 custom-branch-name 189 190 ### git merge 191 192 $ git merge https://github.com/defunkt/hub/pull/73 193 > git fetch git://github.com/mislav/hub.git +refs/heads/feature:refs/remotes/mislav/feature 194 > git merge mislav/feature --no-ff -m 'Merge pull request #73 from mislav/feature...' 195 196 ### git create 197 198 $ git create 199 [ repo created on GitHub ] 200 > git remote add origin git@github.com:YOUR_USER/CURRENT_REPO.git 201 202 # with description: 203 $ git create -d 'It shall be mine, all mine!' 204 205 $ git create recipes 206 [ repo created on GitHub ] 207 > git remote add origin git@github.com:YOUR_USER/recipes.git 208 209 $ git create sinatra/recipes 210 [ repo created in GitHub organization ] 211 > git remote add origin git@github.com:sinatra/recipes.git 212 213 ### git init 214 215 $ git init -g 216 > git init 217 > git remote add origin git@github.com:YOUR_USER/REPO.git 218 219 ### git push 220 221 $ git push origin,staging,qa bert_timeout 222 > git push origin bert_timeout 223 > git push staging bert_timeout 224 > git push qa bert_timeout 225 226 ### git browse 227 228 $ git browse 229 > open https://github.com/YOUR_USER/CURRENT_REPO 230 231 $ git browse -- commit/SHA 232 > open https://github.com/YOUR_USER/CURRENT_REPO/commit/SHA 233 234 $ git browse -- issues 235 > open https://github.com/YOUR_USER/CURRENT_REPO/issues 236 237 $ git browse -- issues/10 238 > open https://github.com/YOUR_USER/CURRENT_REPO/issues/10 239 240 $ git browse schacon/ticgit 241 > open https://github.com/schacon/ticgit 242 243 $ git browse schacon/ticgit commit/SHA 244 > open https://github.com/schacon/ticgit/commit/SHA 245 246 $ git browse resque 247 > open https://github.com/YOUR_USER/resque 248 249 $ git browse resque network 250 > open https://github.com/YOUR_USER/resque/network 251 252 ### git compare 253 254 $ git compare refactor 255 > open https://github.com/CURRENT_REPO/compare/refactor 256 257 $ git compare 1.0..1.1 258 > open https://github.com/CURRENT_REPO/compare/1.0...1.1 259 260 $ git compare -u fix 261 > (https://github.com/CURRENT_REPO/compare/fix) 262 263 $ git compare other-user patch 264 > open https://github.com/other-user/REPO/compare/patch 265 266 ### git submodule 267 268 $ git submodule add wycats/bundler vendor/bundler 269 > git submodule add git://github.com/wycats/bundler.git vendor/bundler 270 271 $ git submodule add -p wycats/bundler vendor/bundler 272 > git submodule add git@github.com:wycats/bundler.git vendor/bundler 273 274 $ git submodule add -b ryppl --name pip ryppl/pip vendor/pip 275 > git submodule add -b ryppl --name pip git://github.com/ryppl/pip.git vendor/pip 276 277 ### git ci-status 278 279 $ git ci-status [commit] 280 > (prints CI state of commit and exits with appropriate code) 281 > One of: success (0), error (1), failure (1), pending (2), no status (3) 282 283 284 ### git help 285 286 $ git help 287 > (improved git help) 288 $ git help hub 289 > (hub man page) 290 291 292 Configuration 293 ------------- 294 295 ### GitHub OAuth authentication 296 297 Hub will prompt for GitHub username & password the first time it needs to access 298 the API and exchange it for an OAuth token, which it saves in "~/.config/hub". 299 300 To avoid being prompted, use **GITHUB_USER** and **GITHUB_PASSWORD** environment 301 variables. 302 303 ### HTTPS instead of git protocol 304 305 If you prefer the HTTPS protocol for GitHub repositories, you can set 306 "hub.protocol" to "https". This will affect `clone`, `fork`, `remote add` 307 and other operations that expand references to GitHub repositories as full 308 URLs that otherwise use git and ssh protocols. 309 310 "hub.protocol" only applies when the "OWNER/REPO" shorthand is used instead of 311 a full git URL. 312 313 # default behavior 314 $ git clone defunkt/repl 315 < git clone > 316 317 # opt into HTTPS: 318 $ git config --global hub.protocol https 319 $ git clone defunkt/repl 320 < https clone > 321 322 ### GitHub Enterprise 323 324 By default, hub will only work with repositories that have remotes which 325 point to github.com. GitHub Enterprise hosts need to be whitelisted to 326 configure hub to treat such remotes same as github.com: 327 328 $ git config --global --add hub.host my.git.org 329 330 The default host for commands like `init` and `clone` is still 331 github.com, but this can be affected with the <GITHUB_HOST> environment 332 variable: 333 334 $ GITHUB_HOST=my.git.org git clone myproject 335 336 Meta 337 ---- 338 339 * Home: <https://github.com/github/hub> 340 * Bugs: <https://github.com/github/hub/issues> 341 * Authors: <https://github.com/github/hub/contributors> 342 343 ### Prior art 344 345 These projects also aim to either improve git or make interacting with 346 GitHub simpler: 347 348 * [hub in Ruby](https://github.com/github/hub/tree/1.12-stable) (previous implementation) 349 * [eg](http://www.gnome.org/~newren/eg/) 350 * [github-gem](https://github.com/defunkt/github-gem)