зеркало из https://github.com/mislav/hub.git
244 строки
9.8 KiB
HTML
244 строки
9.8 KiB
HTML
---
|
|
---
|
|
<!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>
|