diff --git a/Gemfile b/Gemfile index 316ccc17..0b7729b2 100644 --- a/Gemfile +++ b/Gemfile @@ -5,6 +5,5 @@ gem 'cucumber', '~> 1.3.9' gem 'sinatra' group :development do - gem 'rake', '~> 10.1.1' gem 'ronn' end diff --git a/Gemfile.lock b/Gemfile.lock index 4a4241bc..f38ffb94 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -28,7 +28,6 @@ GEM rack (1.4.1) rack-protection (1.2.0) rack - rake (10.1.1) rdiscount (1.6.8) ronn (0.7.3) hpricot (>= 0.8.2) @@ -51,6 +50,8 @@ PLATFORMS DEPENDENCIES aruba (~> 0.5.3) cucumber (~> 1.3.9) - rake (~> 10.1.1) ronn sinatra + +BUNDLED WITH + 1.11.2 diff --git a/README.md b/README.md index cf2dc754..2ffb3ae0 100644 --- a/README.md +++ b/README.md @@ -82,246 +82,6 @@ complement existing completion scripts that ship with git. * [hub bash completion](https://github.com/github/hub/blob/master/etc/hub.bash_completion.sh) * [hub zsh completion](https://github.com/github/hub/blob/master/etc/hub.zsh_completion) -Commands --------- - -Assuming you've aliased hub as `git`, the following commands now have -superpowers: - -### git clone - - $ git clone schacon/ticgit - > git clone git://github.com/schacon/ticgit.git - - $ git clone -p schacon/ticgit - > git clone git@github.com:schacon/ticgit.git - - $ git clone resque - > git clone git@github.com:YOUR_USER/resque.git - -### git remote add - - $ git remote add rtomayko - > git remote add rtomayko git://github.com/rtomayko/CURRENT_REPO.git - - $ git remote add -p rtomayko - > git remote add rtomayko git@github.com:rtomayko/CURRENT_REPO.git - - $ git remote add origin - > git remote add origin git://github.com/YOUR_USER/CURRENT_REPO.git - -### 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 - -### git cherry-pick - - $ git cherry-pick http://github.com/mislav/REPO/commit/SHA - > git remote add -f --no-tags mislav git://github.com/mislav/REPO.git - > git cherry-pick SHA - - $ git cherry-pick mislav@SHA - > git remote add -f --no-tags mislav git://github.com/mislav/CURRENT_REPO.git - > git cherry-pick SHA - - $ git cherry-pick mislav@SHA - > git fetch mislav - > git cherry-pick SHA - -### git am, git apply - - $ git am https://github.com/defunkt/hub/pull/55 - [ downloads patch via API ] - > git am /tmp/55.patch - - $ git am --ignore-whitespace https://github.com/davidbalbert/hub/commit/fdb9921 - [ downloads patch via API ] - > git am --ignore-whitespace /tmp/fdb9921.patch - - $ git apply https://gist.github.com/8da7fb575debd88c54cf - [ downloads patch via API ] - > git apply /tmp/gist-8da7fb575debd88c54cf.txt - -### git fork - - $ git fork - [ repo forked on GitHub ] - > git remote add -f YOUR_USER git@github.com:YOUR_USER/CURRENT_REPO.git - -### git pull-request - - # while on a topic branch called "feature": - $ git pull-request - [ opens text editor to edit title & body for the request ] - [ opened pull request on GitHub for "YOUR_USER:feature" ] - - # explicit title, pull base & head: - $ git pull-request -m "Implemented feature X" -b defunkt:master -h mislav:feature - -### git checkout - - $ git checkout https://github.com/defunkt/hub/pull/73 - > git remote add -f --no-tags -t feature mislav git://github.com/mislav/hub.git - > git checkout --track -B mislav-feature mislav/feature - - $ git checkout https://github.com/defunkt/hub/pull/73 custom-branch-name - -### git merge - - $ git merge https://github.com/defunkt/hub/pull/73 - > git fetch git://github.com/mislav/hub.git +refs/heads/feature:refs/remotes/mislav/feature - > git merge mislav/feature --no-ff -m 'Merge pull request #73 from mislav/feature...' - -### git create - - $ git create - [ repo created on GitHub ] - > git remote add origin git@github.com:YOUR_USER/CURRENT_REPO.git - - # with description: - $ git create -d 'It shall be mine, all mine!' - - $ git create recipes - [ repo created on GitHub ] - > git remote add origin git@github.com:YOUR_USER/recipes.git - - $ git create sinatra/recipes - [ repo created in GitHub organization ] - > git remote add origin git@github.com:sinatra/recipes.git - -### git init - - $ git init -g - > git init - > git remote add origin git@github.com:YOUR_USER/REPO.git - -### git push - - $ git push origin,staging,qa bert_timeout - > git push origin bert_timeout - > git push staging bert_timeout - > git push qa bert_timeout - -### git browse - - $ git browse - > open https://github.com/YOUR_USER/CURRENT_REPO - - $ git browse -- commit/SHA - > open https://github.com/YOUR_USER/CURRENT_REPO/commit/SHA - - $ git browse -- issues - > open https://github.com/YOUR_USER/CURRENT_REPO/issues - - $ git browse -- issues/10 - > open https://github.com/YOUR_USER/CURRENT_REPO/issues/10 - - $ git browse schacon/ticgit - > open https://github.com/schacon/ticgit - - $ git browse schacon/ticgit commit/SHA - > open https://github.com/schacon/ticgit/commit/SHA - - $ git browse resque - > open https://github.com/YOUR_USER/resque - - $ git browse resque network - > open https://github.com/YOUR_USER/resque/network - -### git compare - - $ git compare refactor - > open https://github.com/CURRENT_REPO/compare/refactor - - $ git compare 1.0..1.1 - > open https://github.com/CURRENT_REPO/compare/1.0...1.1 - - $ git compare -u fix - > (https://github.com/CURRENT_REPO/compare/fix) - - $ git compare other-user patch - > open https://github.com/other-user/REPO/compare/patch - -### git submodule - - $ git submodule add wycats/bundler vendor/bundler - > git submodule add git://github.com/wycats/bundler.git vendor/bundler - - $ git submodule add -p wycats/bundler vendor/bundler - > git submodule add git@github.com:wycats/bundler.git vendor/bundler - - $ git submodule add -b ryppl --name pip ryppl/pip vendor/pip - > git submodule add -b ryppl --name pip git://github.com/ryppl/pip.git vendor/pip - -### git ci-status - - $ git ci-status [commit] - > (prints CI state of commit and exits with appropriate code) - > One of: success (0), error (1), failure (1), pending (2), no status (3) - - -### git help - - $ git help - > (improved git help) - $ git help hub - > (hub man page) - - -Configuration -------------- - -### GitHub OAuth authentication - -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". - -To avoid being prompted, use **GITHUB_USER** and **GITHUB_PASSWORD** environment -variables. - -Alternatively, you may provide **GITHUB_TOKEN**, an access token with -**repo** permissions. This will not be written to `~/.config/hub`. - -### HTTPS instead of git protocol - -If you prefer the HTTPS protocol for GitHub repositories, you can set -"hub.protocol" to "https". This will affect `clone`, `fork`, `remote add` -and other operations that expand references to GitHub repositories as full -URLs that otherwise use git and ssh protocols. - -"hub.protocol" only applies when the "OWNER/REPO" shorthand is used instead of -a full git URL. - - # default behavior - $ git clone defunkt/repl - < git clone > - - # opt into HTTPS: - $ git config --global hub.protocol https - $ git clone defunkt/repl - < https clone > - -### GitHub Enterprise - -By default, hub will only work with repositories that have remotes which -point to github.com. GitHub Enterprise hosts need to be whitelisted to -configure hub to treat such remotes same as github.com: - - $ git config --global --add hub.host my.git.org - -The default host for commands like `init` and `clone` is still -github.com, but this can be affected with the `GITHUB_HOST` environment -variable: - - $ GITHUB_HOST=my.git.org git clone myproject - Meta ---- diff --git a/Rakefile b/Rakefile deleted file mode 100644 index c62531fe..00000000 --- a/Rakefile +++ /dev/null @@ -1,57 +0,0 @@ -desc "Show man page" -task :man => "man:build" do - exec "man man/hub.1" -end - -desc "Build man pages" -task "man:build" => ["man/hub.1", "man/hub.1.html"] - -# split readme in sections -# and return the specified section -def split_readme(file, index) - File.read(file).split(/^-{4,}$/)[index].strip -end - -def extract_configs(readme_file) - configs = split_readme(readme_file, 4) - configs.gsub!(/\*\*(.+?)\*\*/, '<\1>') # replace **xx** with - configs.sub!(/\n+.+\Z/, '') # remove last line - configs -end - -def extract_examples(readme_file) - examples = split_readme(readme_file, 3) - examples.sub!(/^.+?(###)/m, '\1') # strip intro paragraph - examples.sub!(/\n+.+\Z/, '') # remove last line - examples -end - -# inject configs and examples from README file to .ronn source -def compiled_source(source, readme) - configs = extract_configs(readme) - examples = extract_examples(readme) - compiled = File.read(source) - compiled.sub!('{{CONFIGS}}', configs) - compiled.sub!('{{README}}', examples) - compiled -end - -# generate man page with ronn -def compile_ronn(destination, type, contents) - File.popen("ronn --pipe --#{type} --organization=GITHUB --manual='Hub Manual'", 'w+') { |io| - io.write contents - io.close_write - File.open(destination, 'w') { |f| f << io.read } - } - abort "ronn --#{type} conversion failed" unless $?.success? -end - -file "man/hub.1" => ["man/hub.1.ronn", "README.md"] do |task| - contents = compiled_source(*task.prerequisites) - compile_ronn(task.name, 'roff', contents) - compile_ronn("#{task.name}.html", 'html', contents) -end - -file "man/hub.1.html" => ["man/hub.1.ronn", "README.md"] do |task| - Rake::Task["man/hub.1"].invoke -end diff --git a/man/hub.1.ronn b/man/hub.1.ronn index 566a89ea..a0ce694c 100644 --- a/man/hub.1.ronn +++ b/man/hub.1.ronn @@ -3,186 +3,45 @@ hub(1) -- git + hub = github ## SYNOPSIS -`hub` [`--noop`] -`hub alias` [`-s`] [] - -### Expanded git commands: - -`git init -g` -`git clone` [`-p`] [/] -`git remote add` [`-p`] [/] -`git remote set-url` [`-p`] [/] -`git fetch` ,[,...] -`git checkout` [] -`git merge` -`git cherry-pick` -`git am` -`git apply` -`git push` ,,..., [] -`git submodule add` [`-p`] [/] - -### Custom git commands: - -`git create` [] [`-p`] [`-d` ] [`-h` ] -`git browse` [`-u`] [[`/`]] [SUBPAGE] -`git compare` [`-u`] [`-b` ] [] [[...]] -`git fork` [`--no-remote`] -`git pull-request` [`-o`|`--browse`] [`-f`] [`-m` |`-F` |`-i` |] [`-b` ] [`-h` ] [`-a` ] [`-M` ] [`-l` ]: -`git ci-status` [`-v`] [] - -## DESCRIPTION - -hub enhances various git commands to ease most common workflows with GitHub. - - * `hub --noop` : - Shows which command(s) would be run as a result of the current command. - Doesn't perform anything. - - * `hub alias` [`-s`] []: - Shows shell instructions for wrapping git. If given, specifies the - type of shell; otherwise defaults to the value of SHELL environment - variable. With `-s`, outputs shell script suitable for `eval`. - - * `git init` `-g` : - Create a git repository as with git-init(1) and add remote `origin` at - "git@github.com:/.git"; is your GitHub username and - is the current working directory's basename. - - * `git clone` [`-p`] [`/`] : - Clone repository "git://github.com//.git" into - as with git-clone(1). When / is omitted, assumes - your GitHub login. - - If the repository is private or the current user has push access to the - repository, hub will use the ssh protocol for cloning. Use `-p` to select - the ssh protocol unconditionally. HTTPS protocol can be used instead by - setting "hub.protocol" (see ). - - * `git remote add` [`-p`] [`/`]: - Add remote "git://github.com//.git" as with - git-remote(1). When / is omitted, the basename of the - current working directory is used. With `-p`, use private remote - "git@github.com:/.git". If is "origin" - then uses your GitHub login. - - * `git remote set-url` [`-p`] [/]: - Sets the url of remote using the same rules as - `git remote add`. - - * `git fetch` ,[,...]: - Adds missing remote(s) with `git remote add` prior to fetching. New - remotes are only added if they correspond to valid forks on GitHub. - - * `git checkout` []: - Checks out the head of the pull request as a local branch, to allow for - reviewing, rebasing and otherwise cleaning up the commits in the pull - request before merging. The name of the local branch can explicitly be - set with . - - * `git merge` : - Merge the pull request with a commit message that includes the pull request - ID and title, similar to the GitHub Merge Button. - - * `git cherry-pick` : - Cherry-pick a commit from a fork using either full URL to the commit - or GitHub-flavored Markdown notation, which is `user@sha`. If the remote - doesn't yet exist, it will be added. A `git fetch ` is issued - prior to the cherry-pick attempt. - - * `git [am|apply]` : - Downloads the patch file for the pull request or commit at the URL and - applies that patch from disk with `git am` or `git apply`. Similar to - `cherry-pick`, but doesn't add new remotes. `git am` creates commits while - preserving authorship info while `apply` only applies the patch to the - working copy. - - * `git push` ,,..., []: - Push to each of through by executing - multiple `git push` commands. - - * `git submodule add` [`-p`] [/] : - Submodule repository "git://github.com//.git" into - as with git-submodule(1). When / is omitted, assumes - your GitHub login. With `-p`, use private remote - "git@github.com:/.git". - - * `git help`: - Display enhanced git-help(1). - -hub also adds some custom commands that are otherwise not present in git: - - * `git create` [] [`-p`] [`-d` ] [`-h` ]: - Create a new public GitHub repository from the current git - repository and add remote `origin` at - "git@github.com:/.git"; is your GitHub - username and is the current working directory name. - To explicitly name the new repository, pass in , optionally in - / form to create under an organization you're a - member of. With `-p`, create a private repository, and with `-d` and `-h` - set the repository's description and homepage URL, respectively. - - * `git browse` [`-u`] [[`/`]] [SUBPAGE]: - Open repository's GitHub page in the system's default web browser using - `open(1)` or the `BROWSER` env variable. If the repository isn't - specified, `browse` opens the page of the repository found in the current - directory. - If SUBPAGE is specified, the browser will open on the specified - subpage: one of "wiki", "commits", "issues" or other (the default is - "tree"). A specific commit in the default repository can be opened with - `git browse -- commit/`. - With `-u`, outputs the URL rather than opening the browser. - - * `git compare` [`-u`] [`-b` ] [] [[...]]: - Open a GitHub compare view page in the system's default web browser. - to are branch names, tag names, or commit SHA1s specifying - the range of history to compare. If a range with two dots (`a..b`) is given, - it will be transformed into one with three dots. If is omitted, - GitHub will compare against the base branch (the default is "master"). - If is omitted, GitHub compare view is opened for the current branch. - With `-u`, outputs the URL rather than opening the browser. With `-b`, uses - as base branch rather than the default branch (master). - - * `git fork` [`--no-remote`]: - Forks the original project (referenced by "origin" remote) on GitHub and - adds a new remote for it under your username. - - * `git pull-request` [`-o`|`--browse`] [`-f`] [`-m` |`-F` |`-i` |] [`-b` ] [`-h` ] [`-a` ] [`-M` ] [`-l` ]: - Opens a pull request on GitHub for the project that the "origin" remote - points to. The default head of the pull request is the current branch. - Both base and head of the pull request can be explicitly given in one of - the following formats: "branch", "owner:branch", "owner/repo:branch". - This command will abort operation if it detects that the current topic - branch has local commits that are not yet pushed to its upstream branch - on the remote. To skip this check, use `-f`. - - Without or , a text editor will open in which title and body - of the pull request can be entered in the same manner as git commit message. - Pull request message can also be passed via stdin with `-F -`. - - With `-o` or `--browse`, the new pull request will open in the web browser. - - With `-a` or `--assign`, the new pull request will be assigned to . - With `-M` or `--milestone`, it will be added to milestone with ID . - With `-l` or `--labels`, the comma-separated list of labels will be applied. - - Issue to pull request conversion via `-i ` or - arguments is deprecated and will likely be removed from the future versions - of both hub and GitHub API. - - * `git ci-status` [`-v`] []: - Looks up the SHA for in GitHub Status API and displays the latest - status. Exits with one of: - success (0), error (1), failure (1), pending (2), no status (3) - - If `-v` is given, additionally print detailed report of all checks and their URLs. +`hub` [`--noop`] [] +`hub alias` [`-s`] [] +`hub help` hub- ## CONFIGURATION -{{CONFIGS}} +### GitHub OAuth authentication -## EXAMPLES +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`. -{{README}} +To avoid being prompted, use `GITHUB_USER` and `GITHUB_PASSWORD` environment +variables. + +Alternatively, you may provide `GITHUB_TOKEN`, an access token with +**repo** permissions. This will not be written to `~/.config/hub`. + +### HTTPS instead of git protocol + +If you prefer the HTTPS protocol for git operations, you can configure hub to +generate all URLs with `https:` instead of `git:` or `ssh:`: + + $ git config --global hub.protocol https + +This will affect `clone`, `fork`, `remote add` and other hub commands that +expand shorthand references to GitHub repo URLs. + +### GitHub Enterprise + +By default, hub will only work with repositories that have remotes which +point to `github.com`. GitHub Enterprise hosts need to be whitelisted to +configure hub to treat such remotes same as github.com: + + $ git config --global --add hub.host MY.GIT.ORG + +The default host for commands like `init` and `clone` is still `github.com`, but +this can be affected with the `GITHUB_HOST` environment variable: + + $ GITHUB_HOST=my.git.org git clone myproject ## BUGS diff --git a/script/bootstrap b/script/bootstrap index 09c71b0d..596f26a0 100755 --- a/script/bootstrap +++ b/script/bootstrap @@ -24,7 +24,7 @@ fi { ruby --version bundle install --path vendor/bundle - bundle binstub rake cucumber ronn + bundle binstub cucumber ronn } || { echo "You need Ruby 1.9 or higher and Bundler to run hub tests" >&2 STATUS=1