hub 1.6.1 → 1.7.0

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.

This version of hub might be problematic. Click here for more details.

Files changed (16) hide show
  1. data/README.md +94 -60
  2. data/Rakefile +74 -38
  3. data/lib/hub/args.rb +16 -3
  4. data/lib/hub/commands.rb +340 -101
  5. data/lib/hub/context.rb +270 -112
  6. data/lib/hub/runner.rb +4 -2
  7. data/lib/hub/standalone.rb +13 -7
  8. data/lib/hub/version.rb +1 -1
  9. data/man/hub.1 +162 -80
  10. data/man/hub.1.html +163 -96
  11. data/man/hub.1.ronn +84 -167
  12. data/test/alias_test.rb +0 -1
  13. data/test/helper.rb +8 -8
  14. data/test/hub_test.rb +395 -71
  15. data/test/standalone_test.rb +0 -1
  16. metadata +8 -6
data/man/hub.1.html CHANGED
@@ -76,98 +76,122 @@
76
76
 
77
77
  <h2 id="SYNOPSIS">SYNOPSIS</h2>
78
78
 
79
- <p><code>hub</code> <var>COMMAND</var> <var>OPTIONS</var><br />
79
+ <p><code>hub</code> [<code>--noop</code>] <var>COMMAND</var> <var>OPTIONS</var><br />
80
80
  <code>hub alias</code> [<code>-s</code>] <var>SHELL</var></p>
81
81
 
82
+ <h3 id="Expanded-git-commands-">Expanded git commands:</h3>
83
+
82
84
  <p><code>git init -g</code> <var>OPTIONS</var><br />
83
- <code>git create</code> [<code>-p</code>] [<code>-d &lt;DESCRIPTION></code>] [<code>-h &lt;HOMEPAGE></code>]<br />
84
85
  <code>git clone</code> [<code>-p</code>] <var>OPTIONS</var> [<var>USER</var>/]<var>REPOSITORY</var> <var>DIRECTORY</var><br />
85
86
  <code>git remote add</code> [<code>-p</code>] <var>OPTIONS</var> <var>USER</var>[/<var>REPOSITORY</var>]<br />
86
87
  <code>git remote set-url</code> [<code>-p</code>] <var>OPTIONS</var> <var>REMOTE-NAME</var> <var>USER</var>[/<var>REPOSITORY</var>]<br />
87
88
  <code>git fetch</code> <var>USER-1</var>,[<var>USER-2</var>,...]<br />
89
+ <code>git checkout</code> <var>PULLREQ-URL</var> [<var>BRANCH</var>]<br />
88
90
  <code>git cherry-pick</code> <var>GITHUB-REF</var><br />
89
91
  <code>git am</code> <var>GITHUB-URL</var><br />
92
+ <code>git apply</code> <var>GITHUB-URL</var><br />
90
93
  <code>git push</code> <var>REMOTE-1</var>,<var>REMOTE-2</var>,...,<var>REMOTE-N</var> [<var>REF</var>]<br />
94
+ <code>git submodule add</code> [<code>-p</code>] <var>OPTIONS</var> [<var>USER</var>/]<var>REPOSITORY</var> <var>DIRECTORY</var></p>
95
+
96
+ <h3 id="Custom-git-commands-">Custom git commands:</h3>
97
+
98
+ <p><code>git create</code> [<var>NAME</var>] [<code>-p</code>] [<code>-d</code> <var>DESCRIPTION</var>] [<code>-h</code> <var>HOMEPAGE</var>]<br />
91
99
  <code>git browse</code> [<code>-u</code>] [[<var>USER</var><code>/</code>]<var>REPOSITORY</var>] [SUBPAGE]<br />
92
100
  <code>git compare</code> [<code>-u</code>] [<var>USER</var>] [<var>START</var>...]<var>END</var><br />
93
- <code>git submodule add</code> [<code>-p</code>] <var>OPTIONS</var> [<var>USER</var>/]<var>REPOSITORY</var> <var>DIRECTORY</var><br />
94
- <code>git fork</code> [<code>--no-remote</code>]</p>
101
+ <code>git fork</code> [<code>--no-remote</code>]<br />
102
+ <code>git pull-request</code> [<code>-f</code>] [<var>TITLE</var>|<code>-i</code> <var>ISSUE</var>] [<code>-b</code> <var>BASE</var>] [<code>-h</code> <var>HEAD</var>]:</p>
95
103
 
96
104
  <h2 id="DESCRIPTION">DESCRIPTION</h2>
97
105
 
98
- <p><code>hub</code> enhances various <code>git</code> commands with GitHub remote expansion. The
99
- alias command displays information on configuring your environment:</p>
106
+ <p>hub enhances various git commands to ease most common workflows with GitHub.</p>
100
107
 
101
- <ul>
102
- <li><p><code>hub alias</code> [<code>-s</code>] <var>SHELL</var>:
103
- Writes shell aliasing code for <var>SHELL</var> (<code>bash</code>, <code>sh</code>, <code>zsh</code>,
108
+ <dl>
109
+ <dt><code>hub --noop</code> <var>COMMAND</var></dt><dd><p>Shows which command(s) would be run as a result of the current command.
110
+ Doesn't perform anything.</p></dd>
111
+ <dt><code>hub alias</code> [<code>-s</code>] <var>SHELL</var></dt><dd><p>Writes shell aliasing code for <var>SHELL</var> (<code>bash</code>, <code>sh</code>, <code>zsh</code>,
104
112
  <code>csh</code>) to standard output. With the <code>-s</code> option, the output of
105
113
  this command can be evaluated directly within the shell:<br />
106
- <code>eval $(hub alias -s bash)</code></p></li>
107
- <li><p><code>git init</code> <code>-g</code> <var>OPTIONS</var>:
108
- Create a git repository as with <span class="man-ref">git-init<span class="s">(1)</span></span> and add remote <code>origin</code> at
114
+ <code>eval $(hub alias -s bash)</code></p></dd>
115
+ <dt><code>git init</code> <code>-g</code> <var>OPTIONS</var></dt><dd><p>Create a git repository as with <span class="man-ref">git-init<span class="s">(1)</span></span> and add remote <code>origin</code> at
109
116
  "git@github.com:<var>USER</var>/<var>REPOSITORY</var>.git"; <var>USER</var> is your GitHub username and
110
- <var>REPOSITORY</var> is the current working directory's basename.</p></li>
111
- <li><p><code>git create</code> [<code>-p</code>] [<code>-d &lt;DESCRIPTION></code>] [<code>-h &lt;HOMEPAGE></code>]:<br />
112
- Create a new public github repository from the current git
113
- repository and add remote <code>origin</code> at
114
- "git@github.com:<var>USER</var>/<var>REPOSITORY</var>.git"; <var>USER</var> is your GitHub
115
- username and <var>REPOSITORY</var> is the current working directory's
116
- basename. With <code>-p</code>, create a private repository. <code>-d</code> and <code>-h</code>
117
- set the repository's description and homepage, respectively.</p></li>
118
- <li><p><code>git clone</code> [<code>-p</code>] <var>OPTIONS</var> [<var>USER</var><code>/</code>]<var>REPOSITORY</var> <var>DIRECTORY</var>:<br />
119
- Clone repository "git://github.com/<var>USER</var>/<var>REPOSITORY</var>.git" into
117
+ <var>REPOSITORY</var> is the current working directory's basename.</p></dd>
118
+ <dt><code>git clone</code> [<code>-p</code>] <var>OPTIONS</var> [<var>USER</var><code>/</code>]<var>REPOSITORY</var> <var>DIRECTORY</var></dt><dd><p>Clone repository "git://github.com/<var>USER</var>/<var>REPOSITORY</var>.git" into
120
119
  <var>DIRECTORY</var> as with <span class="man-ref">git-clone<span class="s">(1)</span></span>. When <var>USER</var>/ is omitted, assumes
121
- your GitHub login. With <code>-p</code>, use private remote
122
- "git@github.com:<var>USER</var>/<var>REPOSITORY</var>.git".</p></li>
123
- <li><p><code>git remote add</code> [<code>-p</code>] <var>OPTIONS</var> <var>USER</var>[<code>/</code><var>REPOSITORY</var>]:<br />
124
- Add remote "git://github.com/<var>USER</var>/<var>REPOSITORY</var>.git" as with
120
+ your GitHub login. With <code>-p</code>, clone private repositories over SSH.
121
+ For repositories under your GitHub login, <code>-p</code> is implicit.</p></dd>
122
+ <dt><code>git remote add</code> [<code>-p</code>] <var>OPTIONS</var> <var>USER</var>[<code>/</code><var>REPOSITORY</var>]</dt><dd><p>Add remote "git://github.com/<var>USER</var>/<var>REPOSITORY</var>.git" as with
125
123
  <span class="man-ref">git-remote<span class="s">(1)</span></span>. When /<var>REPOSITORY</var> is omitted, the basename of the
126
124
  current working directory is used. With <code>-p</code>, use private remote
127
125
  "git@github.com:<var>USER</var>/<var>REPOSITORY</var>.git". If <var>USER</var> is "origin"
128
- then uses your GitHub login.</p></li>
129
- <li><p><code>git remote set-url</code> [<code>-p</code>] <var>OPTIONS</var> <var>REMOTE-NAME</var> <var>USER</var>[/<var>REPOSITORY</var>]<br />
130
- Sets the url of remote <var>REMOTE-NAME</var> using the same rules as
131
- <code>git remote add</code>.</p></li>
132
- <li><p><code>git fetch</code> <var>USER-1</var>,[<var>USER-2</var>,...]:
133
- Adds missing remote(s) with <code>git remote add</code> prior to fetching. New
134
- remotes are only added if they correspond to valid forks on GitHub.</p></li>
135
- <li><p><code>git cherry-pick</code> <var>GITHUB-REF</var>:
136
- Cherry-pick a commit from a fork using either full URL to the commit
126
+ then uses your GitHub login.</p></dd>
127
+ <dt><code>git remote set-url</code> [<code>-p</code>] <var>OPTIONS</var> <var>REMOTE-NAME</var> <var>USER</var>[/<var>REPOSITORY</var>]</dt><dd><p>Sets the url of remote <var>REMOTE-NAME</var> using the same rules as
128
+ <code>git remote add</code>.</p></dd>
129
+ <dt><code>git fetch</code> <var>USER-1</var>,[<var>USER-2</var>,...]</dt><dd><p>Adds missing remote(s) with <code>git remote add</code> prior to fetching. New
130
+ remotes are only added if they correspond to valid forks on GitHub.</p></dd>
131
+ <dt><code>git checkout</code> <var>PULLREQ-URL</var> [<var>BRANCH</var>]</dt><dd><p>Checks out the head of the pull request as a local branch, to allow for
132
+ reviewing, rebasing and otherwise cleaning up the commits in the pull
133
+ request before merging. The name of the local branch can explicitly be
134
+ set with <var>BRANCH</var>.</p></dd>
135
+ <dt><code>git cherry-pick</code> <var>GITHUB-REF</var></dt><dd><p>Cherry-pick a commit from a fork using either full URL to the commit
137
136
  or GitHub-flavored Markdown notation, which is <code>user@sha</code>. If the remote
138
137
  doesn't yet exist, it will be added. A <code>git fetch &lt;user></code> is issued
139
- prior to the cherry-pick attempt.</p></li>
140
- <li><p><code>git am</code> <var>GITHUB-URL</var>:
141
- Downloads the patch file for the pull request or commit at the URL and
142
- applies that patch from disk with <code>git am</code>. Similar to <code>cherry-pick</code>, but
143
- doesn't add new remotes.</p></li>
144
- <li><p><code>git push</code> <var>REMOTE-1</var>,<var>REMOTE-2</var>,...,<var>REMOTE-N</var> [<var>REF</var>]:
145
- Push <var>REF</var> to each of <var>REMOTE-1</var> through <var>REMOTE-N</var> by executing
146
- multiple <code>git push</code> commands.</p></li>
147
- <li><p><code>git browse</code> [<code>-u</code>] [[<var>USER</var><code>/</code>]<var>REPOSITORY</var>] [SUBPAGE]:
148
- Open repository's GitHub page in the system's default web browser using
138
+ prior to the cherry-pick attempt.</p></dd>
139
+ <dt><code>git [am|apply]</code> <var>GITHUB-URL</var></dt><dd><p>Downloads the patch file for the pull request or commit at the URL and
140
+ applies that patch from disk with <code>git am</code> or <code>git apply</code>. Similar to
141
+ <code>cherry-pick</code>, but doesn't add new remotes. <code>git am</code> creates commits while
142
+ preserving authorship info while <code>apply</code> only applies the patch to the
143
+ working copy.</p></dd>
144
+ <dt><code>git push</code> <var>REMOTE-1</var>,<var>REMOTE-2</var>,...,<var>REMOTE-N</var> [<var>REF</var>]</dt><dd><p>Push <var>REF</var> to each of <var>REMOTE-1</var> through <var>REMOTE-N</var> by executing
145
+ multiple <code>git push</code> commands.</p></dd>
146
+ <dt><code>git submodule add</code> [<code>-p</code>] <var>OPTIONS</var> [<var>USER</var>/]<var>REPOSITORY</var> <var>DIRECTORY</var></dt><dd><p>Submodule repository "git://github.com/<var>USER</var>/<var>REPOSITORY</var>.git" into
147
+ <var>DIRECTORY</var> as with <span class="man-ref">git-submodule<span class="s">(1)</span></span>. When <var>USER</var>/ is omitted, assumes
148
+ your GitHub login. With <code>-p</code>, use private remote
149
+ "git@github.com:<var>USER</var>/<var>REPOSITORY</var>.git".</p></dd>
150
+ <dt><code>git help</code></dt><dd><p>Display enhanced <span class="man-ref">git-help<span class="s">(1)</span></span>.</p></dd>
151
+ </dl>
152
+
153
+
154
+ <p>hub also adds some custom commands that are otherwise not present in git:</p>
155
+
156
+ <dl>
157
+ <dt><code>git create</code> [<var>NAME</var>] [<code>-p</code>] [<code>-d</code> <var>DESCRIPTION</var>] [<code>-h</code> <var>HOMEPAGE</var>]</dt><dd><p>Create a new public GitHub repository from the current git
158
+ repository and add remote <code>origin</code> at
159
+ "git@github.com:<var>USER</var>/<var>REPOSITORY</var>.git"; <var>USER</var> is your GitHub
160
+ username and <var>REPOSITORY</var> is the current working directory name.
161
+ To explicitly name the new repository, pass in <var>NAME</var>, optionally in
162
+ <var>ORGANIZATION</var>/<var>NAME</var> form to create under an organization you're a
163
+ member of. With <code>-p</code>, create a private repository, and with <code>-d</code> and <code>-h</code>
164
+ set the repository's description and homepage URL, respectively.</p></dd>
165
+ <dt><code>git browse</code> [<code>-u</code>] [[<var>USER</var><code>/</code>]<var>REPOSITORY</var>] [SUBPAGE]</dt><dd><p>Open repository's GitHub page in the system's default web browser using
149
166
  <code>open(1)</code> or the <code>BROWSER</code> env variable. If the repository isn't
150
167
  specified, <code>browse</code> opens the page of the repository found in the current
151
168
  directory. If SUBPAGE is specified, the browser will open on the specified
152
169
  subpage: one of "wiki", "commits", "issues" or other (the default is
153
- "tree").</p></li>
154
- <li><p><code>git compare</code> [<code>-u</code>] [<var>USER</var>] [<var>START</var>...]<var>END</var>:
155
- Open a GitHub compare view page in the system's default web browser.
170
+ "tree").</p></dd>
171
+ <dt><code>git compare</code> [<code>-u</code>] [<var>USER</var>] [<var>START</var>...]<var>END</var></dt><dd><p>Open a GitHub compare view page in the system's default web browser.
156
172
  <var>START</var> to <var>END</var> are branch names, tag names, or commit SHA1s specifying
157
- the range of history to compare. If <var>START</var> is omitted, GitHub will
158
- compare against the base branch (the default is "master").</p></li>
159
- <li><p><code>git submodule add</code> [<code>-p</code>] <var>OPTIONS</var> [<var>USER</var>/]<var>REPOSITORY</var> <var>DIRECTORY</var>:<br />
160
- Submodule repository "git://github.com/<var>USER</var>/<var>REPOSITORY</var>.git" into
161
- <var>DIRECTORY</var> as with <span class="man-ref">git-submodule<span class="s">(1)</span></span>. When <var>USER</var>/ is omitted, assumes
162
- your GitHub login. With <code>-p</code>, use private remote
163
- "git@github.com:<var>USER</var>/<var>REPOSITORY</var>.git".</p></li>
164
- <li><p><code>git fork</code> [<code>--no-remote</code>]:
165
- Forks the original project (referenced by "origin" remote) on GitHub and
173
+ the range of history to compare. If a range with two dots (<code>a..b</code>) is given,
174
+ it will be transformed into one with three dots. If <var>START</var> is omitted,
175
+ GitHub will compare against the base branch (the default is "master").</p></dd>
176
+ <dt><code>git fork</code> [<code>--no-remote</code>]</dt><dd><p>Forks the original project (referenced by "origin" remote) on GitHub and
166
177
  adds a new remote for it under your username. Requires <code>github.token</code> to
167
- be set (see CONFIGURATION).</p></li>
168
- <li><p><code>git help</code>:
169
- Display enhanced <span class="man-ref">git-help<span class="s">(1)</span></span>.</p></li>
170
- </ul>
178
+ be set (see CONFIGURATION).</p></dd>
179
+ <dt><code>git pull-request</code> [<code>-f</code>] [<var>TITLE</var>|<code>-i</code> <var>ISSUE</var>] [<code>-b</code> <var>BASE</var>] [<code>-h</code> <var>HEAD</var>]</dt><dd><p><code>git pull-request</code> [<code>-f</code>] <var>ISSUE-URL</var> [<code>-h</code> <var>HEAD</var>]
180
+ Opens a pull request on GitHub for the project that the "origin" remote
181
+ points to. The default head of the pull request is the current branch.
182
+ Both base and head of the pull request can be explicitly given in one of
183
+ the following formats: "branch", "owner:branch", "owner/repo:branch".
184
+ This command will abort operation if it detects that the current topic
185
+ branch has local commits that are not yet pushed to its upstream branch
186
+ on the remote. To skip this check, use <code>-f</code>.</p>
187
+
188
+ <p>If <var>TITLE</var> is omitted, a text editor will open in which title and body of
189
+ the pull request can be entered in the same manner as git commit message.</p>
190
+
191
+ <p>If instead of normal <var>TITLE</var> an issue number is given with <code>-i</code>, the pull
192
+ request will be attached to an existing GitHub issue. Alternatively, instead
193
+ of title you can paste a full URL to an issue on GitHub.</p></dd>
194
+ </dl>
171
195
 
172
196
 
173
197
  <h2 id="CONFIGURATION">CONFIGURATION</h2>
@@ -183,30 +207,20 @@ Display enhanced <span class="man-ref">git-help<span class="s">(1)</span></span>
183
207
  $ git config --global github.token &lt;token>
184
208
  </code></pre>
185
209
 
186
- <p>See <a href="http://github.com/guides/local-github-config" data-bare-link="true">http://github.com/guides/local-github-config</a> for more
210
+ <p>You can override these values with <var>GITHUB_USER</var> and <var>GITHUB_TOKEN</var>
211
+ environment variables.</p>
212
+
213
+ <p>See <a href="http://help.github.com/set-your-user-name-email-and-github-token/" data-bare-link="true">http://help.github.com/set-your-user-name-email-and-github-token/</a> for more
187
214
  information.</p>
188
215
 
189
- <p>You can also tell <code>hub</code> to use <code>http://</code> rather than <code>git://</code> when
190
- cloning:</p>
216
+ <p>If you prefer the HTTPS protocol for GitHub repositories, you can set
217
+ "hub.protocol" to "https". This will affect <code>clone</code>, <code>fork</code>, <code>remote add</code>
218
+ and other operations that expand references to GitHub repositories as full
219
+ URLs that otherwise use git and ssh protocols.</p>
191
220
 
192
- <pre><code>$ git config --global --bool hub.http-clone true
221
+ <pre><code>$ git config --global hub.protocol https
193
222
  </code></pre>
194
223
 
195
- <p>Want to use environment variables instead of a local gitconfig for
196
- authentication?</p>
197
-
198
- <ul>
199
- <li><code>GITHUB_USER</code> - If set, this will be used instead of the <code>github.user</code> config
200
-
201
- <pre><code> value to determine your GitHub username.
202
- </code></pre></li>
203
- <li><code>GITHUB_TOKEN</code> - If set, this will be used instead of the <code>github.token</code>
204
-
205
- <pre><code> config value to determine your GitHub API token.
206
- </code></pre></li>
207
- </ul>
208
-
209
-
210
224
  <h2 id="EXAMPLES">EXAMPLES</h2>
211
225
 
212
226
  <h3 id="git-clone">git clone</h3>
@@ -218,10 +232,7 @@ $ git clone -p schacon/ticgit
218
232
  &gt; git clone git@github.com:schacon/ticgit.git
219
233
 
220
234
  $ git clone resque
221
- &gt; git clone git://github.com/YOUR_USER/resque.git
222
-
223
- $ git clone -p resque
224
- &gt; git clone git@github.com:YOUR_USER/resque.git
235
+ &gt; git clone git@github.com/YOUR_USER/resque.git
225
236
  </code></pre>
226
237
 
227
238
  <h3 id="git-remote-add">git remote add</h3>
@@ -263,7 +274,7 @@ $ git cherry-pick mislav@SHA
263
274
  &gt; git cherry-pick SHA
264
275
  </code></pre>
265
276
 
266
- <h3 id="git-am">git am</h3>
277
+ <h3 id="git-am-git-apply">git am, git apply</h3>
267
278
 
268
279
  <pre><code>$ git am https://github.com/defunkt/hub/pull/55
269
280
  &gt; curl https://github.com/defunkt/hub/pull/55.patch -o /tmp/55.patch
@@ -272,27 +283,65 @@ $ git cherry-pick mislav@SHA
272
283
  $ git am --ignore-whitespace https://github.com/davidbalbert/hub/commit/fdb9921
273
284
  &gt; curl https://github.com/davidbalbert/hub/commit/fdb9921.patch -o /tmp/fdb9921.patch
274
285
  &gt; git am --ignore-whitespace /tmp/fdb9921.patch
286
+
287
+ $ git apply https://gist.github.com/8da7fb575debd88c54cf
288
+ &gt; curl https://gist.github.com/8da7fb575debd88c54cf.txt -o /tmp/gist-8da7fb575debd88c54cf.txt
289
+ &gt; git apply /tmp/gist-8da7fb575debd88c54cf.txt
275
290
  </code></pre>
276
291
 
277
292
  <h3 id="git-fork">git fork</h3>
278
293
 
279
294
  <pre><code>$ git fork
280
- ... hardcore forking action ...
281
- &gt; git remote add YOUR_USER git@github.com:YOUR_USER/CURRENT_REPO.git
295
+ [ repo forked on GitHub ]
296
+ &gt; git remote add -f YOUR_USER git@github.com:YOUR_USER/CURRENT_REPO.git
282
297
  </code></pre>
283
298
 
284
- <h3 id="git-init">git init</h3>
299
+ <h3 id="git-pull-request">git pull-request</h3>
285
300
 
286
- <pre><code>$ git init -g
287
- &gt; git init
288
- &gt; git remote add origin git@github.com:YOUR_USER/REPO.git
301
+ <pre><code># while on a topic branch called "feature":
302
+ $ git pull-request
303
+ [ opens text editor to edit title &amp; body for the request ]
304
+ [ opened pull request on GitHub for "YOUR_USER:feature" ]
305
+
306
+ # explicit title, pull base &amp; head:
307
+ $ git pull-request "I've implemented feature X" -b defunkt:master -h mislav:feature
308
+
309
+ $ git pull-request -i 123
310
+ [ attached pull request to issue #123 ]
311
+ </code></pre>
312
+
313
+ <h3 id="git-checkout">git checkout</h3>
314
+
315
+ <pre><code># $ git checkout https://github.com/defunkt/hub/pull/73
316
+ # &gt; git remote add -f -t feature git://github:com/mislav/hub.git
317
+ # &gt; git checkout -b mislav-feature mislav/feature
318
+
319
+ # $ git checkout https://github.com/defunkt/hub/pull/73 custom-branch-name
289
320
  </code></pre>
290
321
 
291
322
  <h3 id="git-create">git create</h3>
292
323
 
293
324
  <pre><code>$ git create
294
- ... hardcore creating action ...
325
+ [ repo created on GitHub ]
295
326
  &gt; git remote add origin git@github.com:YOUR_USER/CURRENT_REPO.git
327
+
328
+ # with description:
329
+ $ git create -d 'It shall be mine, all mine!'
330
+
331
+ $ git create recipes
332
+ [ repo created on GitHub ]
333
+ &gt; git remote add origin git@github.com:YOUR_USER/recipes.git
334
+
335
+ $ git create sinatra/recipes
336
+ [ repo created in GitHub organization ]
337
+ &gt; git remote add origin git@github.com:sinatra/recipes.git
338
+ </code></pre>
339
+
340
+ <h3 id="git-init">git init</h3>
341
+
342
+ <pre><code>$ git init -g
343
+ &gt; git init
344
+ &gt; git remote add origin git@github.com:YOUR_USER/REPO.git
296
345
  </code></pre>
297
346
 
298
347
  <h3 id="git-push">git push</h3>
@@ -308,12 +357,18 @@ $ git am --ignore-whitespace https://github.com/davidbalbert/hub/commit/fdb9921
308
357
  <pre><code>$ git browse
309
358
  &gt; open https://github.com/YOUR_USER/CURRENT_REPO
310
359
 
360
+ $ git browse -- commit/SHA
361
+ &gt; open https://github.com/YOUR_USER/CURRENT_REPO/commit/SHA
362
+
311
363
  $ git browse -- issues
312
364
  &gt; open https://github.com/YOUR_USER/CURRENT_REPO/issues
313
365
 
314
366
  $ git browse schacon/ticgit
315
367
  &gt; open https://github.com/schacon/ticgit
316
368
 
369
+ $ git browse schacon/ticgit commit/SHA
370
+ &gt; open https://github.com/schacon/ticgit/commit/SHA
371
+
317
372
  $ git browse resque
318
373
  &gt; open https://github.com/YOUR_USER/resque
319
374
 
@@ -326,7 +381,7 @@ $ git browse resque network
326
381
  <pre><code>$ git compare refactor
327
382
  &gt; open https://github.com/CURRENT_REPO/compare/refactor
328
383
 
329
- $ git compare 1.0...1.1
384
+ $ git compare 1.0..1.1
330
385
  &gt; open https://github.com/CURRENT_REPO/compare/1.0...1.1
331
386
 
332
387
  $ git compare -u fix
@@ -336,6 +391,18 @@ $ git compare other-user patch
336
391
  &gt; open https://github.com/other-user/REPO/compare/patch
337
392
  </code></pre>
338
393
 
394
+ <h3 id="git-submodule">git submodule</h3>
395
+
396
+ <pre><code>$ hub submodule add wycats/bundler vendor/bundler
397
+ &gt; git submodule add git://github.com/wycats/bundler.git vendor/bundler
398
+
399
+ $ hub submodule add -p wycats/bundler vendor/bundler
400
+ &gt; git submodule add git@github.com:wycats/bundler.git vendor/bundler
401
+
402
+ $ hub submodule add -b ryppl ryppl/pip vendor/pip
403
+ &gt; git submodule add -b ryppl git://github.com/ryppl/pip.git vendor/pip
404
+ </code></pre>
405
+
339
406
  <h3 id="git-help">git help</h3>
340
407
 
341
408
  <pre><code>$ git help
@@ -346,7 +413,7 @@ $ git help hub
346
413
 
347
414
  <h2 id="BUGS">BUGS</h2>
348
415
 
349
- <p><a href="http://github.com/defunkt/hub/issues" data-bare-link="true">http://github.com/defunkt/hub/issues</a></p>
416
+ <p><a href="https://github.com/defunkt/hub/issues" data-bare-link="true">https://github.com/defunkt/hub/issues</a></p>
350
417
 
351
418
  <h2 id="AUTHORS">AUTHORS</h2>
352
419
 
@@ -356,12 +423,12 @@ $ git help hub
356
423
 
357
424
  <p><span class="man-ref">git<span class="s">(1)</span></span>, <span class="man-ref">git-clone<span class="s">(1)</span></span>, <span class="man-ref">git-remote<span class="s">(1)</span></span>, <span class="man-ref">git-init<span class="s">(1)</span></span>,
358
425
  <a href="http://github.com" data-bare-link="true">http://github.com</a>,
359
- <a href="http://github.com/defunkt/hub" data-bare-link="true">http://github.com/defunkt/hub</a></p>
426
+ <a href="https://github.com/defunkt/hub" data-bare-link="true">https://github.com/defunkt/hub</a></p>
360
427
 
361
428
 
362
429
  <ol class='man-decor man-foot man foot'>
363
430
  <li class='tl'>DEFUNKT</li>
364
- <li class='tc'>May 2011</li>
431
+ <li class='tc'>November 2011</li>
365
432
  <li class='tr'>hub(1)</li>
366
433
  </ol>
367
434
 
data/man/hub.1.ronn CHANGED
@@ -3,27 +3,38 @@ hub(1) -- git + hub = github
3
3
 
4
4
  ## SYNOPSIS
5
5
 
6
- `hub` <COMMAND> <OPTIONS>
6
+ `hub` [`--noop`] <COMMAND> <OPTIONS>
7
7
  `hub alias` [`-s`] <SHELL>
8
8
 
9
+ ### Expanded git commands:
10
+
9
11
  `git init -g` <OPTIONS>
10
- `git create` [`-p`] [`-d <DESCRIPTION>`] [`-h <HOMEPAGE>`]
11
12
  `git clone` [`-p`] <OPTIONS> [<USER>/]<REPOSITORY> <DIRECTORY>
12
13
  `git remote add` [`-p`] <OPTIONS> <USER>[/<REPOSITORY>]
13
14
  `git remote set-url` [`-p`] <OPTIONS> <REMOTE-NAME> <USER>[/<REPOSITORY>]
14
15
  `git fetch` <USER-1>,[<USER-2>,...]
16
+ `git checkout` <PULLREQ-URL> [<BRANCH>]
15
17
  `git cherry-pick` <GITHUB-REF>
16
18
  `git am` <GITHUB-URL>
19
+ `git apply` <GITHUB-URL>
17
20
  `git push` <REMOTE-1>,<REMOTE-2>,...,<REMOTE-N> [<REF>]
21
+ `git submodule add` [`-p`] <OPTIONS> [<USER>/]<REPOSITORY> <DIRECTORY>
22
+
23
+ ### Custom git commands:
24
+
25
+ `git create` [<NAME>] [`-p`] [`-d` <DESCRIPTION>] [`-h` <HOMEPAGE>]
18
26
  `git browse` [`-u`] [[<USER>`/`]<REPOSITORY>] [SUBPAGE]
19
27
  `git compare` [`-u`] [<USER>] [<START>...]<END>
20
- `git submodule add` [`-p`] <OPTIONS> [<USER>/]<REPOSITORY> <DIRECTORY>
21
28
  `git fork` [`--no-remote`]
29
+ `git pull-request` [`-f`] [<TITLE>|`-i` <ISSUE>] [`-b` <BASE>] [`-h` <HEAD>]:
22
30
 
23
31
  ## DESCRIPTION
24
32
 
25
- `hub` enhances various `git` commands with GitHub remote expansion. The
26
- alias command displays information on configuring your environment:
33
+ hub enhances various git commands to ease most common workflows with GitHub.
34
+
35
+ * `hub --noop` <COMMAND>:
36
+ Shows which command(s) would be run as a result of the current command.
37
+ Doesn't perform anything.
27
38
 
28
39
  * `hub alias` [`-s`] <SHELL>:
29
40
  Writes shell aliasing code for <SHELL> (`bash`, `sh`, `zsh`,
@@ -36,28 +47,20 @@ alias command displays information on configuring your environment:
36
47
  "git@github.com:<USER>/<REPOSITORY>.git"; <USER> is your GitHub username and
37
48
  <REPOSITORY> is the current working directory's basename.
38
49
 
39
- * `git create` [`-p`] [`-d <DESCRIPTION>`] [`-h <HOMEPAGE>`]:
40
- Create a new public github repository from the current git
41
- repository and add remote `origin` at
42
- "git@github.com:<USER>/<REPOSITORY>.git"; <USER> is your GitHub
43
- username and <REPOSITORY> is the current working directory's
44
- basename. With `-p`, create a private repository. `-d` and `-h`
45
- set the repository's description and homepage, respectively.
46
-
47
- * `git clone` [`-p`] <OPTIONS> [<USER>`/`]<REPOSITORY> <DIRECTORY>:
50
+ * `git clone` [`-p`] <OPTIONS> [<USER>`/`]<REPOSITORY> <DIRECTORY>:
48
51
  Clone repository "git://github.com/<USER>/<REPOSITORY>.git" into
49
52
  <DIRECTORY> as with git-clone(1). When <USER>/ is omitted, assumes
50
- your GitHub login. With `-p`, use private remote
51
- "git@github.com:<USER>/<REPOSITORY>.git".
53
+ your GitHub login. With `-p`, clone private repositories over SSH.
54
+ For repositories under your GitHub login, `-p` is implicit.
52
55
 
53
- * `git remote add` [`-p`] <OPTIONS> <USER>[`/`<REPOSITORY>]:
56
+ * `git remote add` [`-p`] <OPTIONS> <USER>[`/`<REPOSITORY>]:
54
57
  Add remote "git://github.com/<USER>/<REPOSITORY>.git" as with
55
58
  git-remote(1). When /<REPOSITORY> is omitted, the basename of the
56
59
  current working directory is used. With `-p`, use private remote
57
60
  "git@github.com:<USER>/<REPOSITORY>.git". If <USER> is "origin"
58
61
  then uses your GitHub login.
59
62
 
60
- * `git remote set-url` [`-p`] <OPTIONS> <REMOTE-NAME> <USER>[/<REPOSITORY>]
63
+ * `git remote set-url` [`-p`] <OPTIONS> <REMOTE-NAME> <USER>[/<REPOSITORY>]:
61
64
  Sets the url of remote <REMOTE-NAME> using the same rules as
62
65
  `git remote add`.
63
66
 
@@ -65,21 +68,50 @@ alias command displays information on configuring your environment:
65
68
  Adds missing remote(s) with `git remote add` prior to fetching. New
66
69
  remotes are only added if they correspond to valid forks on GitHub.
67
70
 
71
+ * `git checkout` <PULLREQ-URL> [<BRANCH>]:
72
+ Checks out the head of the pull request as a local branch, to allow for
73
+ reviewing, rebasing and otherwise cleaning up the commits in the pull
74
+ request before merging. The name of the local branch can explicitly be
75
+ set with <BRANCH>.
76
+
68
77
  * `git cherry-pick` <GITHUB-REF>:
69
78
  Cherry-pick a commit from a fork using either full URL to the commit
70
79
  or GitHub-flavored Markdown notation, which is `user@sha`. If the remote
71
80
  doesn't yet exist, it will be added. A `git fetch <user>` is issued
72
81
  prior to the cherry-pick attempt.
73
82
 
74
- * `git am` <GITHUB-URL>:
83
+ * `git [am|apply]` <GITHUB-URL>:
75
84
  Downloads the patch file for the pull request or commit at the URL and
76
- applies that patch from disk with `git am`. Similar to `cherry-pick`, but
77
- doesn't add new remotes.
85
+ applies that patch from disk with `git am` or `git apply`. Similar to
86
+ `cherry-pick`, but doesn't add new remotes. `git am` creates commits while
87
+ preserving authorship info while `apply` only applies the patch to the
88
+ working copy.
78
89
 
79
90
  * `git push` <REMOTE-1>,<REMOTE-2>,...,<REMOTE-N> [<REF>]:
80
91
  Push <REF> to each of <REMOTE-1> through <REMOTE-N> by executing
81
92
  multiple `git push` commands.
82
93
 
94
+ * `git submodule add` [`-p`] <OPTIONS> [<USER>/]<REPOSITORY> <DIRECTORY>:
95
+ Submodule repository "git://github.com/<USER>/<REPOSITORY>.git" into
96
+ <DIRECTORY> as with git-submodule(1). When <USER>/ is omitted, assumes
97
+ your GitHub login. With `-p`, use private remote
98
+ "git@github.com:<USER>/<REPOSITORY>.git".
99
+
100
+ * `git help`:
101
+ Display enhanced git-help(1).
102
+
103
+ hub also adds some custom commands that are otherwise not present in git:
104
+
105
+ * `git create` [<NAME>] [`-p`] [`-d` <DESCRIPTION>] [`-h` <HOMEPAGE>]:
106
+ Create a new public GitHub repository from the current git
107
+ repository and add remote `origin` at
108
+ "git@github.com:<USER>/<REPOSITORY>.git"; <USER> is your GitHub
109
+ username and <REPOSITORY> is the current working directory name.
110
+ To explicitly name the new repository, pass in <NAME>, optionally in
111
+ <ORGANIZATION>/<NAME> form to create under an organization you're a
112
+ member of. With `-p`, create a private repository, and with `-d` and `-h`
113
+ set the repository's description and homepage URL, respectively.
114
+
83
115
  * `git browse` [`-u`] [[<USER>`/`]<REPOSITORY>] [SUBPAGE]:
84
116
  Open repository's GitHub page in the system's default web browser using
85
117
  `open(1)` or the `BROWSER` env variable. If the repository isn't
@@ -91,22 +123,31 @@ alias command displays information on configuring your environment:
91
123
  * `git compare` [`-u`] [<USER>] [<START>...]<END>:
92
124
  Open a GitHub compare view page in the system's default web browser.
93
125
  <START> to <END> are branch names, tag names, or commit SHA1s specifying
94
- the range of history to compare. If <START> is omitted, GitHub will
95
- compare against the base branch (the default is "master").
96
-
97
- * `git submodule add` [`-p`] <OPTIONS> [<USER>/]<REPOSITORY> <DIRECTORY>:
98
- Submodule repository "git://github.com/<USER>/<REPOSITORY>.git" into
99
- <DIRECTORY> as with git-submodule(1). When <USER>/ is omitted, assumes
100
- your GitHub login. With `-p`, use private remote
101
- "git@github.com:<USER>/<REPOSITORY>.git".
126
+ the range of history to compare. If a range with two dots (`a..b`) is given,
127
+ it will be transformed into one with three dots. If <START> is omitted,
128
+ GitHub will compare against the base branch (the default is "master").
102
129
 
103
130
  * `git fork` [`--no-remote`]:
104
131
  Forks the original project (referenced by "origin" remote) on GitHub and
105
132
  adds a new remote for it under your username. Requires `github.token` to
106
133
  be set (see CONFIGURATION).
107
134
 
108
- * `git help`:
109
- Display enhanced git-help(1).
135
+ * `git pull-request` [`-f`] [<TITLE>|`-i` <ISSUE>] [`-b` <BASE>] [`-h` <HEAD>]:
136
+ `git pull-request` [`-f`] <ISSUE-URL> [`-h` <HEAD>]
137
+ Opens a pull request on GitHub for the project that the "origin" remote
138
+ points to. The default head of the pull request is the current branch.
139
+ Both base and head of the pull request can be explicitly given in one of
140
+ the following formats: "branch", "owner:branch", "owner/repo:branch".
141
+ This command will abort operation if it detects that the current topic
142
+ branch has local commits that are not yet pushed to its upstream branch
143
+ on the remote. To skip this check, use `-f`.
144
+
145
+ If <TITLE> is omitted, a text editor will open in which title and body of
146
+ the pull request can be entered in the same manner as git commit message.
147
+
148
+ If instead of normal <TITLE> an issue number is given with `-i`, the pull
149
+ request will be attached to an existing GitHub issue. Alternatively, instead
150
+ of title you can paste a full URL to an issue on GitHub.
110
151
 
111
152
  ## CONFIGURATION
112
153
 
@@ -119,150 +160,26 @@ Or, set the GitHub username and token with:
119
160
  $ git config --global github.user <username>
120
161
  $ git config --global github.token <token>
121
162
 
122
- See <http://github.com/guides/local-github-config> for more
123
- information.
163
+ You can override these values with <GITHUB_USER> and <GITHUB_TOKEN>
164
+ environment variables.
124
165
 
125
- You can also tell `hub` to use `http://` rather than `git://` when
126
- cloning:
127
-
128
- $ git config --global --bool hub.http-clone true
166
+ See <http://help.github.com/set-your-user-name-email-and-github-token/> for more
167
+ information.
129
168
 
130
- Want to use environment variables instead of a local gitconfig for
131
- authentication?
169
+ If you prefer the HTTPS protocol for GitHub repositories, you can set
170
+ "hub.protocol" to "https". This will affect `clone`, `fork`, `remote add`
171
+ and other operations that expand references to GitHub repositories as full
172
+ URLs that otherwise use git and ssh protocols.
132
173
 
133
- * `GITHUB_USER` - If set, this will be used instead of the `github.user` config
134
- value to determine your GitHub username.
135
- * `GITHUB_TOKEN` - If set, this will be used instead of the `github.token`
136
- config value to determine your GitHub API token.
174
+ $ git config --global hub.protocol https
137
175
 
138
176
  ## EXAMPLES
139
177
 
140
- ### git clone
141
-
142
- $ git clone schacon/ticgit
143
- > git clone git://github.com/schacon/ticgit.git
144
-
145
- $ git clone -p schacon/ticgit
146
- > git clone git@github.com:schacon/ticgit.git
147
-
148
- $ git clone resque
149
- > git clone git://github.com/YOUR_USER/resque.git
150
-
151
- $ git clone -p resque
152
- > git clone git@github.com:YOUR_USER/resque.git
153
-
154
- ### git remote add
155
-
156
- $ git remote add rtomayko
157
- > git remote add rtomayko git://github.com/rtomayko/CURRENT_REPO.git
158
-
159
- $ git remote add -p rtomayko
160
- > git remote add rtomayko git@github.com:rtomayko/CURRENT_REPO.git
161
-
162
- $ git remote add origin
163
- > git remote add origin git://github.com/YOUR_USER/CURRENT_REPO.git
164
-
165
- ### git fetch
166
-
167
- $ git fetch mislav
168
- > git remote add mislav git://github.com/mislav/REPO.git
169
- > git fetch mislav
170
-
171
- $ git fetch mislav,xoebus
172
- > git remote add mislav ...
173
- > git remote add xoebus ...
174
- > git fetch --multiple mislav xoebus
175
-
176
- ### git cherry-pick
177
-
178
- $ git cherry-pick http://github.com/mislav/REPO/commit/SHA
179
- > git remote add -f mislav git://github.com/mislav/REPO.git
180
- > git cherry-pick SHA
181
-
182
- $ git cherry-pick mislav@SHA
183
- > git remote add -f mislav git://github.com/mislav/CURRENT_REPO.git
184
- > git cherry-pick SHA
185
-
186
- $ git cherry-pick mislav@SHA
187
- > git fetch mislav
188
- > git cherry-pick SHA
189
-
190
- ### git am
191
-
192
- $ git am https://github.com/defunkt/hub/pull/55
193
- > curl https://github.com/defunkt/hub/pull/55.patch -o /tmp/55.patch
194
- > git am /tmp/55.patch
195
-
196
- $ git am --ignore-whitespace https://github.com/davidbalbert/hub/commit/fdb9921
197
- > curl https://github.com/davidbalbert/hub/commit/fdb9921.patch -o /tmp/fdb9921.patch
198
- > git am --ignore-whitespace /tmp/fdb9921.patch
199
-
200
- ### git fork
201
-
202
- $ git fork
203
- ... hardcore forking action ...
204
- > git remote add YOUR_USER git@github.com:YOUR_USER/CURRENT_REPO.git
205
-
206
- ### git init
207
-
208
- $ git init -g
209
- > git init
210
- > git remote add origin git@github.com:YOUR_USER/REPO.git
211
-
212
- ### git create
213
-
214
- $ git create
215
- ... hardcore creating action ...
216
- > git remote add origin git@github.com:YOUR_USER/CURRENT_REPO.git
217
-
218
- ### git push
219
-
220
- $ git push origin,staging,qa bert_timeout
221
- > git push origin bert_timeout
222
- > git push staging bert_timeout
223
- > git push qa bert_timeout
224
-
225
- ### git browse
226
-
227
- $ git browse
228
- > open https://github.com/YOUR_USER/CURRENT_REPO
229
-
230
- $ git browse -- issues
231
- > open https://github.com/YOUR_USER/CURRENT_REPO/issues
232
-
233
- $ git browse schacon/ticgit
234
- > open https://github.com/schacon/ticgit
235
-
236
- $ git browse resque
237
- > open https://github.com/YOUR_USER/resque
238
-
239
- $ git browse resque network
240
- > open https://github.com/YOUR_USER/resque/network
241
-
242
- ### git compare
243
-
244
- $ git compare refactor
245
- > open https://github.com/CURRENT_REPO/compare/refactor
246
-
247
- $ git compare 1.0...1.1
248
- > open https://github.com/CURRENT_REPO/compare/1.0...1.1
249
-
250
- $ git compare -u fix
251
- > (https://github.com/CURRENT_REPO/compare/fix)
252
-
253
- $ git compare other-user patch
254
- > open https://github.com/other-user/REPO/compare/patch
255
-
256
- ### git help
257
-
258
- $ git help
259
- > (improved git help)
260
- $ git help hub
261
- > (hub man page)
178
+ {{README}}
262
179
 
263
180
  ## BUGS
264
181
 
265
- <http://github.com/defunkt/hub/issues>
182
+ <https://github.com/defunkt/hub/issues>
266
183
 
267
184
  ## AUTHORS
268
185
 
@@ -272,4 +189,4 @@ authentication?
272
189
 
273
190
  git(1), git-clone(1), git-remote(1), git-init(1),
274
191
  <http://github.com>,
275
- <http://github.com/defunkt/hub>
192
+ <https://github.com/defunkt/hub>