forked from mislav/hub
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
243 lines (199 loc) · 9.77 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
---
---
<!doctype html>
<head>
<title>hub · an extension to command-line git</title>
<meta charset="utf-8">
<meta name=viewport content='initial-scale=1.0'>
<link rel="stylesheet" href="style.css">
<body>
<header>
<h1><a href="{{ site.github.repository_url }}#readme">hub</a>: use GitHub from the command-line</h1>
</header>
<section id=install>
<p>
<strong>hub</strong> is <em>an extension to command-line git</em> that
helps you do everyday GitHub tasks without ever leaving the terminal.
</p>
<p>Read the full documentation: <a href="hub.1.html">man hub</a>, or
visit this project <a href="{{ site.github.repository_url }}">on GitHub</a>.</p>
<pre><span class="comment"># install with <a href="https://docs.brew.sh/Installation">Homebrew</a> (macOS, Linux)</span>
<span class="comment"># or see <a href="{{ site.github.repository_url }}#installation">other installation options</a></span>
<span class=p></span>brew install hub
<span class=p></span>hub version
git version 2.25.0
hub version {{ site.github.latest_release.tag_name | replace_first: "v", "" }} <span class="comment"><span class="hidden">#</span> ← it works!</span>
<span class="comment"># indicate that you prefer HTTPS to SSH git clone URLs</span>
<span class=p></span>git config --global hub.protocol https
</pre>
</section>
<section id=developer>
<h2>Staying productive on the command-line</h2>
<p>
hub makes it easy to <em>clone or create repositories</em>, <em>browse project
pages</em>, <em>list known issues</em>, ensure your local branches <em>stay up
to date</em>, and <em>share logs or code snippets via Gist</em>.
</p>
<pre>
<span class="comment"># clone your own project</span>
<span class=p></span><strong>hub clone</strong> dotfiles
<span class="result">→ git clone git://github.com/YOUR_USER/dotfiles.git</span>
<span class="comment"># clone another project</span>
<span class=p></span><strong>hub clone</strong> github/hub
<span class="result">→ git clone git://github.com/github/hub.git</span>
<span class="comment"># fast-forward all local branches to match the latest state on the remote</span>
<span class=p></span>cd myproject
<span class=p></span><strong>hub sync</strong>
<span class="comment"># list latest open issues in the current repository</span>
<span class=p></span><strong>hub issue</strong> --limit 10
<span class="comment"># open the current project's issues page</span>
<span class=p></span><strong>hub browse</strong> -- issues
<span class="result">→ open https://github.com/github/hub/issues</span>
<span class="comment"># open another project's wiki</span>
<span class=p></span><strong>hub browse</strong> rbenv/ruby-build wiki
<span class="result">→ open https://github.com/rbenv/ruby-build/wiki</span>
<span class="comment"># share log output via Gist</span>
<span class=p></span><strong>hub gist create</strong> --copy build.log
<span class="result">→ (the URL of the new private gist copied to clipboard)</span>
</pre>
<p>
Starting a new project has never been easier:
</p>
<pre>
<span class="comment"># create a repo to host a new project on GitHub</span>
<span class=p></span>git init
<span class=p></span>git add .
<span class=p></span>git commit -m "And so, it begins."
<span class=p></span><strong>hub create</strong>
<span class="result">→ (creates a new GitHub repository with the name of the current directory)</span>
<span class=p></span>git push -u origin HEAD
</pre>
</section>
<section id=contributor>
<h2>Lowering the barrier to contributing to open-source</h2>
<p>
Whether you are beginner or an experienced contributor to open-source, hub makes
it easier to <em>fork repositories</em>, check the <em>CI status of a
branch</em>, and even <em>submit pull requests</em> from the same environment
where you write & commit your code.
</p>
<pre>
<span class=p></span><strong>hub clone</strong> octocat/Spoon-Knife
<span class=p></span>cd Spoon-Knife
<span class="comment"># create a topic branch</span>
<span class=p></span>git checkout -b feature
<span class="comment"># make some changes...</span>
<span class=p></span>git commit -am "done with feature"
<span class="comment"># It's time to fork the repo!</span>
<span class=p></span><strong>hub fork</strong> --remote-name origin
<span class="result">→ (forking repo on GitHub...)</span>
<span class="result">→ git remote add origin git@github.com:YOUR_USER/Spoon-Knife.git</span>
<span class="comment"># push the changes to your new remote</span>
<span class=p></span>git push origin feature
<span class="comment"># check the CI status for this branch</span>
<span class=p></span><strong>hub ci-status</strong> --verbose
<span class="comment"># open a pull request for the branch you've just pushed</span>
<span class=p></span><strong>hub pull-request</strong>
<span class="result">→ (opens a text editor for your pull request message)</span>
</pre>
</section>
<section id=scripting>
<h2>Automating tasks for fun and profit</h2>
<p>
Scripting is much easier now that you can <em>list or create</em>
issues, pull requests, and GitHub Releases in the <em>format of your choice</em>.
</p>
<pre>
<span class="comment"># List issues assigned to you that are labeled "urgent"</span>
<span class=p></span><strong>hub issue</strong> --assignee YOUR_USER --labels urgent
<span class="comment"># List the URLs of at most 20 pull requests based on the "develop" branch:</span>
<span class=p></span><strong>hub pr list</strong> --limit 20 --base develop --format='%t [%H] | %U%n'
<span class="comment"># Create a GitHub Release from master using release notes from a file</span>
<span class=p></span><strong>hub release create</strong> --copy -F release-notes.txt v2.3.0
<span class="result">→ (the URL of the new release copied to clipboard)</span>
</pre>
<h3>Drop down to the API level</h3>
<p>
Even if hub doesn't support the exact feature you need, you can use
<a href="/hub-api.1.html"><code>hub api</code></a> to manually make requests against any
GitHub API—even <a href="https://developer.github.com/v4/#about-graphql">GraphQL</a>—and
have hub handle authentication, JSON encoding/decoding, and pagination for you.
</p>
<pre>
<span class="comment"># use contents of a file to post a comment on issue #123 of the current repo</span>
<span class=p></span><strong>hub api</strong> repos/{owner}/{repo}/issues/123/comments --field body=<span class=value>@mycomment.txt</span>
<span class="comment"># find a pull request that introduced a specific commit SHA into a repo</span>
<span class=p></span>REPO="github/hub"
<span class=p></span>SHA="b0db79db"
<span class=p></span><strong>hub api graphql</strong> --flat -f q="repo:<span class=value>$REPO</span> type:pr <span class=value>$SHA</span>" -f query=<span class=value>'
query($q: String!) {
search(query: $q, type: ISSUE, first: 3) {
nodes {
... on PullRequest {
url
}
}
}
}
'</span> | awk '/\.url/ { print $2 }'
</pre>
<p>
See <a href="https://github.com/mislav/hub-api-utils">hub-api-utils</a> for more examples.
</p>
</section>
<section id=maintainer>
<h2>Designed for open-source maintainers</h2>
<p>
Maintaining a project is easier when you can easily <em>fetch from other forks</em>,
<em>check out pull requests</em>, <em>close issues</em>, and even <em>cherry-pick
commits by URL</em>.
</p>
<pre>
<span class="comment"># fetch from multiple trusted forks, even if they don't yet exist as remotes</span>
<span class=p></span><strong>hub fetch</strong> mislav,cehoffman
<span class="result">→ git remote add mislav git://github.com/mislav/hub.git</span>
<span class="result">→ git remote add cehoffman git://github.com/cehoffman/hub.git</span>
<span class="result">→ git fetch --multiple mislav cehoffman</span>
<span class="comment"># check out a pull request for review</span>
<span class=p></span><strong>hub pr checkout</strong> 134
<span class="result">→ (creates a new branch with the contents of the pull request)</span>
<span class="comment"># make new commits, then update the pull request</span>
<span class=p></span>git push
<span class="comment"># close an issue</span>
<span class=p></span><strong>hub issue update</strong> 134 --state closed
<span class="comment"># directly apply all commits from a pull request to the current branch</span>
<span class=p></span><strong>hub am -3</strong> https://github.com/github/hub/pull/134
<span class="comment"># cherry-pick a GitHub URL</span>
<span class=p></span><strong>hub cherry-pick</strong> https://github.com/xoebus/hub/commit/177eeb8
<span class="comment"># open the GitHub compare view between two releases</span>
<span class=p></span><strong>hub compare</strong> v0.9..v1.0
<span class="comment"># put the compare URL for a topic branch to your clipboard</span>
<span class=p></span><strong>hub compare --url</strong> feature | pbcopy
</pre>
</section>
<section id=work>
<h2>Using GitHub for work</h2>
<p>
Save time at work by opening <em>pull requests for code reviews</em> and
pushing to <em>multiple remotes at once</em>. Even <em>GitHub Enterprise</em>
is supported.
</p>
<pre>
<span class="comment"># have hub recognize your GitHub Enterprise hostname</span>
<span class=p></span>git config --global --add hub.host <strong>my.example.org</strong>
<span class="comment"># transfer an issue to another repo</span>
<span class=p></span><strong>hub issue transfer</strong> 123 NEWREPO
<span class="comment"># open a pull request with title & body from a file</span>
<span class=p></span>git push origin feature
<span class=p></span><strong>hub pull-request</strong> --copy -F prepared-message.md
<span class="result">→ (the URL of the new pull request copied to clipboard)</span>
<span class="comment"># push to multiple remotes</span>
<span class=p></span><strong>hub push</strong> production,staging
</pre>
<p>
See the <a href="hub.1.html#configuration">full reference documentation</a> to learn more.
</p>
</section>
<footer>
<p>made with <3 at GitHub</p>
</footer>