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