github.com/pengwynn/gh@v1.0.1-0.20140118055701-14327ca3942e/README.md (about) 1 g + h = github [](https://travis-ci.org/jingweno/gh) 2 ============== 3 4  5 6 Fast GitHub command line client implemented in Go. Current version is [v1.0.0](https://github.com/jingweno/gh/releases/tag/v1.0.0). 7 8 Overview 9 -------- 10 11 gh is a command line client to GitHub. It's designed to run as fast as possible with easy installation across operating systems. 12 If you like gh, please also take a look at [hub](https://github.com/github/hub). Hub is a reference implementation to gh. 13 14 Motivation 15 ---------- 16 17 **Fast** 18 19 $ time hub version > /dev/null 20 hub version > /dev/null 0.03s user 0.01s system 93% cpu 0.047 total 21 22 $ time gh version > /dev/null 23 gh version > /dev/null 0.01s user 0.01s system 85% cpu 0.022 total 24 25 $ time hub browse > /dev/null 26 hub browse > /dev/null 0.07s user 0.04s system 87% cpu 0.130 total 27 28 $ time gh browse > /dev/null 29 gh browse > /dev/null 0.03s user 0.02s system 87% cpu 0.059 total 30 31 **Muti-platforms** 32 33 gh is fully implemented in the Go language and is designed to run across operating systems. 34 35 **Easy installation** 36 37 There're no pre-requirements to install gh. Download the [binary](https://github.com/jingweno/gh/releases) and go! 38 39 Installation 40 ------------ 41 42 ### Homebrew 43 44 The easiest way to install `gh` on OSX is through [Homebrew](https://github.com/mxcl/homebrew). 45 You can add the [gh Homebrew repository](https://github.com/jingweno/homebrew-gh) with [`brew tap`](https://github.com/mxcl/homebrew/wiki/brew-tap): 46 47 $ brew tap jingweno/gh 48 $ brew install gh 49 $ brew install --build-from-source gh # build gh from source 50 $ brew install --build-from-source --HEAD gh # build gh HEAD from source 51 52 ### Standalone 53 54 `gh` can be easily installed as an executable. 55 Download the latest [compiled binary forms of gh](https://github.com/jingweno/gh/releases) for Darwin, Linux and Windows. 56 57 ### Boxen 58 59 If you're using [boxen](http://boxen.github.com/), there's a [puppet-gh](https://github.com/boxen/puppet-gh) module to install and set up `gh`. 60 61 ### Source 62 63 To compile gh from source, you need to have a [Go development environment](http://golang.org/doc/install), version 1.1 or better, and run: 64 65 $ git clone https://github.com/jingweno/gh.git 66 $ cd gh 67 $ script/install 68 69 Note that `go get` will pull down sources from various VCS. 70 Please make sure you have git and hg installed. 71 72 Update 73 ------ 74 75 `gh` comes with a command to self update: 76 77 $ gh update 78 79 ### Autoupdate 80 81 `gh` checks every two weeks for newer versions and prompts you for update if there's one. 82 A timestamp is stored in `~/.config/gh-update` for the next update time. 83 84 You can enable to always update automatically by answering `always` when a new version is released, or setting the global git config `gh.autoUpdate`: 85 86 ``` 87 $ git config --global gh.autoUpdate always 88 ``` 89 90 You can also disable completely automatic updates by answering `never` when a new version is released, or setting the global git config `gh.autoUpdate`: 91 92 ``` 93 $ git config --global gh.autoUpdate never 94 ``` 95 96 ### Homebrew 97 98 If you installed `gh` with `brew tap jingweno/gh`, you can update it with: 99 100 $ brew upgrade gh 101 102 ### Source 103 104 To update gh from source, run: 105 106 $ cd GH_SOURCE_DIR 107 $ git pull origin master 108 $ script/install 109 110 Aliasing 111 -------- 112 113 It's best to use `gh` by aliasing it to `git`. 114 All git commands will still work with `gh` adding some sugar. 115 116 `gh alias` displays instructions for the current shell. With the `-s` flag, 117 it outputs a script suitable for `eval`. 118 119 You should place this command in your `.bash_profile` or other startup 120 script: 121 122 eval "$(gh alias -s)" 123 124 For more details, run `gh help alias`. 125 126 Commands 127 -------- 128 129 Assuming you've aliased gh as `git`, the following commands now have: 130 131 ### git init 132 133 $ git init -g 134 > git init 135 > git remote add origin git@github.com:YOUR_USER/REPO.git 136 137 ### git push 138 139 $ git push origin,staging,qa bert_timeout 140 > git push origin bert_timeout 141 > git push staging bert_timeout 142 > git push qa bert_timeout 143 144 $ git push origin 145 > git push origin HEAD 146 147 ### git checkout 148 149 $ git checkout https://github.com/jingweno/gh/pull/35 150 > git remote add -f -t feature git://github:com/foo/gh.git 151 > git checkout --track -B foo-feature foo/feature 152 153 $ git checkout https://github.com/jingweno/gh/pull/35 custom-branch-name 154 155 ### git merge 156 157 $ git merge https://github.com/jingweno/gh/pull/73 158 > git fetch git://github.com/jingweno/gh.git +refs/heads/feature:refs/remotes/jingweno/feature 159 > git merge jingweno/feature --no-ff -m 'Merge pull request #73 from jingweno/feature...' 160 161 ### git clone 162 163 $ git clone jingweno/gh 164 > git clone git://github.com/jingweno/gh 165 166 $ git clone -p jingweno/gh 167 > git clone git@github.com:jingweno/gh.git 168 169 $ git clone jekyll_and_hype 170 > git clone git://github.com/YOUR_LOGIN/jekyll_and_hype. 171 172 $ git clone -p jekyll_and_hype 173 > git clone git@github.com:YOUR_LOGIN/jekyll_and_hype.git 174 175 ### git fetch 176 177 $ git fetch jingweno 178 > git remote add jingweno git://github.com/jingweno/REPO.git 179 > git fetch jingweno 180 181 $ git fetch jingweno,foo 182 > git remote add jingweno ... 183 > git remote add foo ... 184 > git fetch --multiple jingweno foo 185 186 $ git fetch --multiple jingweno foo 187 > git remote add jingweno ... 188 > git remote add foo ... 189 > git fetch --multiple jingweno foo 190 191 ### git cherry-pick 192 193 $ git cherry-pick https://github.com/jingweno/gh/commit/a319d88#comments 194 > git remote add -f jingweno git://github.com/jingweno/gh.git 195 > git cherry-pick a319d88 196 197 $ git cherry-pick jingweno@a319d88 198 > git remote add -f jingweno git://github.com/jingweno/gh.git 199 > git cherry-pick a319d88 200 201 $ git cherry-pick jingweno@SHA 202 > git fetch jingweno 203 > git cherry-pick SHA 204 205 ### git remote 206 207 $ git remote add jingweno 208 > git remote add -f jingweno git://github.com/jingweno/CURRENT_REPO.git 209 210 $ git remote add -p jingweno 211 > git remote add -f jingweno git@github.com:jingweno/CURRENT_REPO.git 212 213 $ git remote add origin 214 > git remote add -f YOUR_USER git://github.com/YOUR_USER/CURRENT_REPO.git 215 216 ### git submodule 217 218 $ git submodule add jingweno/gh vendor/gh 219 > git submodule add git://github.com/jingweno/gh.git vendor/gh 220 221 $ git submodule add -p jingweno/gh vendor/gh 222 > git submodule add git@github.com:jingweno/gh.git vendor/gh 223 224 $ git submodule add -b gh --name gh jingweno/gh vendor/gh 225 > git submodule add -b gh --name gh git://github.com/jingweno/gh.git vendor/gh 226 227 ### git pull-request 228 229 # while on a topic branch called "feature": 230 $ git pull-request 231 [ opens text editor to edit title & body for the request ] 232 [ opened pull request on GitHub for "YOUR_USER:feature" ] 233 234 # explicit pull base & head: 235 $ git pull-request -b jingweno:master -h jingweno:feature 236 237 $ git pull-request -m "title\n\nbody" 238 [ create pull request with title & body ] 239 240 $ git pull-request -i 123 241 [ attached pull request to issue #123 ] 242 243 $ git pull-request https://github.com/jingweno/gh/pull/123 244 [ attached pull request to issue #123 ] 245 246 $ git pull-request -F FILE 247 [ create pull request with title & body from FILE ] 248 249 ### git apply 250 251 $ git apply https://github.com/jingweno/gh/pull/55 252 > curl https://github.com/jingweno/gh/pull/55.patch -o /tmp/55.patch 253 > git apply /tmp/55.patch 254 255 $ git apply --ignore-whitespace https://github.com/jingweno/gh/commit/fdb9921 256 > curl https://github.com/jingweno/gh/commit/fdb9921.patch -o /tmp/fdb9921.patch 257 > git apply --ignore-whitespace /tmp/fdb9921.patch 258 259 $ git apply https://gist.github.com/8da7fb575debd88c54cf 260 > curl https://gist.github.com/8da7fb575debd88c54cf.txt -o /tmp/gist-8da7fb575debd88c54cf.txt 261 > git apply /tmp/gist-8da7fb575debd88c54cf.txt 262 263 ### git fork 264 265 $ git fork 266 [ repo forked on GitHub ] 267 > git remote add -f YOUR_USER git@github.com:YOUR_USER/CURRENT_REPO.git 268 269 $ git fork --no-remote 270 [ repo forked on GitHub ] 271 272 ### git create 273 274 $ git create 275 ... create repo on github ... 276 > git remote add -f origin git@github.com:YOUR_USER/CURRENT_REPO.git 277 278 # with description: 279 $ git create -d 'It shall be mine, all mine!' 280 281 $ git create recipes 282 [ repo created on GitHub ] 283 > git remote add origin git@github.com:YOUR_USER/recipes.git 284 285 $ git create sinatra/recipes 286 [ repo created in GitHub organization ] 287 > git remote add origin git@github.com:sinatra/recipes.git 288 289 ### git ci-status 290 291 $ git ci-status 292 > (prints CI state of HEAD and exits with appropriate code) 293 > One of: success (0), error (1), failure (1), pending (2), no status (3) 294 295 $ git ci-status -v 296 > (prints CI state of HEAD, the URL to the CI build results and exits with appropriate code) 297 > One of: success (0), error (1), failure (1), pending (2), no status (3) 298 299 $ git ci-status BRANCH 300 > (prints CI state of BRANCH and exits with appropriate code) 301 > One of: success (0), error (1), failure (1), pending (2), no status (3) 302 303 $ git ci-status SHA 304 > (prints CI state of SHA and exits with appropriate code) 305 > One of: success (0), error (1), failure (1), pending (2), no status (3) 306 307 ### git browse 308 309 $ git browse 310 > open https://github.com/YOUR_USER/CURRENT_REPO 311 312 $ git browse commit/SHA 313 > open https://github.com/YOUR_USER/CURRENT_REPO/commit/SHA 314 315 $ git browse issues 316 > open https://github.com/YOUR_USER/CURRENT_REPO/issues 317 318 $ git browse -p jingweno/gh 319 > open https://github.com/jingweno/gh 320 321 $ git browse -p jingweno/gh commit/SHA 322 > open https://github.com/jingweno/gh/commit/SHA 323 324 $ git browse -p resque 325 > open https://github.com/YOUR_USER/resque 326 327 $ git browse -p resque network 328 > open https://github.com/YOUR_USER/resque/network 329 330 ### git compare 331 332 $ git compare refactor 333 > open https://github.com/CURRENT_REPO/compare/refactor 334 335 $ git compare 1.0..1.1 336 > open https://github.com/CURRENT_REPO/compare/1.0...1.1 337 338 $ git compare -u other-user patch 339 > open https://github.com/other-user/REPO/compare/patch 340 341 ### git release (beta) 342 343 $ git release 344 > (prints a list of releases of YOUR_USER/CURRENT_REPO) 345 346 $ git release TAG 347 > (creates a new release for the given tag) 348 349 ### git issues (beta) 350 351 $ git issue 352 > (prints a list of issues for YOUR_USER/CURRENT_REPO) 353 354 $ git issue create 355 > (creates an issue for the project that "origin" remte points to) 356 357 Configuration 358 ------------- 359 360 ### GitHub OAuth authentication 361 362 `gh` will prompt for GitHub username & password the first time it needs 363 to access the API and exchange it for an OAuth token, which it saves in 364 `~/.config/gh`. 365 366 ### HTTPS instead of git protocol 367 368 If you prefer using the HTTPS protocol for GitHub repositories instead 369 of the git protocol for read and ssh for write, you can set 370 "gh.protocol" to "https". 371 372 # default behavior 373 $ git clone jingweno/gh 374 < git clone > 375 376 # opt into HTTPS: 377 $ git config --global gh.protocol https 378 $ git clone jingweno/gh 379 < https clone > 380 381 382 ### Crash reports 383 384 `gh` includes automatic crash reporting in case that something unexpected happens. 385 It will ask you if you want to report the error to us if the program terminates suddenly, and 386 then it will open an issue on your behalf under [the crash report issues](https://github.com/jingweno/gh/issues?labels=Crash+Report&page=1&state=open). 387 388 `gh` doesn't send any information about the command that you ran. 389 Check [some examples](https://github.com/jingweno/gh/issues?labels=Crash+Report&state=closed) of the information included by default, you can always modify it before the issue is open. 390 391 You can enable to always send crash reports with the default information by answering `always` when a crash error happens, or setting the global git config `gh.reportCrash`: 392 393 ``` 394 $ git config --global gh.reportCrash always 395 ``` 396 397 You can also disable completely crash report notifications by answering `never` when a crash report happens, or setting the global git config `gh.reportCrash`: 398 399 ``` 400 $ git config --global gh.reportCrash never 401 ``` 402 403 Release Notes 404 ------------- 405 406 See [Releases](https://github.com/jingweno/gh/releases). 407 408 Roadmap 409 ------- 410 411 See [Issues](https://github.com/jingweno/gh/issues?labels=feature&page=1&state=open). 412 413 Development 414 ----------- 415 416 [Godep](https://github.com/kr/godep) is used to lock down all the 417 dependencies. You need to use the wrapper scripts to build/install/test `gh`: 418 419 ### script/bootstrap 420 421 This script will get all the dependencies ready so you can start hacking on gh. 422 423 ``` 424 $ ./script/bootstrap 425 ``` 426 427 ### script/build 428 429 This script will build gh. It will also perform script/bootstrap, which gets all dependencies and all that jazz. 430 431 ``` 432 $ ./script/build 433 ``` 434 435 ### script/install 436 437 This script will build and install gh. It will also perform script/bootstrap, which gets all dependencies and all that jazz. 438 439 ``` 440 $ ./script/install 441 ``` 442 443 ### script/package 444 445 This script will cross-compile gh and package release for current platform. 446 It executes the `package` [gotask](https://github.com/jingweno/gotask) [task](https://github.com/jingweno/gh/blob/master/gh_task.go). 447 448 ``` 449 $ ./script/package 450 ``` 451 452 ### script/test 453 454 For your convenience, there is a script to run the tests. 455 456 ``` 457 $ ./script/test 458 ``` 459 460 See [this guide](https://github.com/jingweno/gh/blob/master/CONTRIBUTING.md) on how to submit a pull request. 461 462 Contributors 463 ------------ 464 465 See [Contributors](https://github.com/jingweno/gh/graphs/contributors). 466 467 License 468 ------- 469 470 gh is released under the MIT license. See [LICENSE.md](https://github.com/jingweno/gh/blob/master/LICENSE.md).