<rss version="2.0"><channel><title xml:lang="en">GitHub Guides</title><atom:link type="application/atom+xml" href="https://guides.github.com/feed/index.xml" rel="self"/><link>https://guides.github.com/</link><pubDate>Fri, 13 Mar 2020 09:23:49 +0000</pubDate><lastBuildDate>Fri, 13 Mar 2020 09:23:49 +0000</lastBuildDate><language>en-US</language><generator>GitHub Guides</generator><description>Learn how to do more with GitHub.</description><item><title>Forking Projects</title><link>http://guides.github.com/activities/forking/</link><pubDate>Thu, 30 Nov 2017 00:00:00 +0000</pubDate><guid isPermaLink="true">http://guides.github.com/activities/forking/index.md</guid><description><p><a id="contributing" title="Contributing to a project" class="toc-item"></a>

<p>Is staging and committing changes locally too advanced right now? <a href="https://services.github.com/on-demand/">Check out this on-demand training</a> for interactive tutorials to help you learn more.</p>

<p><strong>ProTip:</strong> This tutorial is aimed at researchers who want to cite GitHub repositories in academic literature. Provided you’ve already set up a GitHub repository, this tutorial can be completed without installing any special software. If you haven’t yet created a project on GitHub, start first by <a href="https://help.github.com/categories/importing-your-projects-to-github/">uploading your work</a> to a repository.</p>

<p><strong>Important!</strong> Make sure you tell people how they can reuse your work by including a license in your repository. If you don’t know which license is right for you, then take a look at <a href="http://choosealicense.com/">choosealicense.com</a>.</p>

<p><strong>Important!</strong> If you want to archive a repository that belongs to an organization on GitHub, you will need to make sure that the organization administrator has enabled <a href="https://help.github.com/articles/approving-third-party-applications-for-your-organization/">third-party access</a> to the Zenodo application.</p>

<p><strong>Important!</strong> Zenodo can only access your public repositories so make sure the repository you want to archive is <a href="https://help.github.com/articles/making-a-private-repository-public/">public</a>.</p>

<p><strong>ProTip:</strong> If you really want to show off, then right click on the gray and blue DOI image and copy the URL and place it in your README on your GitHub repo.</p>

<a href="https://github.com/cheshire137" class="founder" target="_blank">
  <img class="avatar" alt="cheshire137" width="86" height="86" data-proofer-ignore="true" src="https://avatars3.githubusercontent.com/cheshire137?v=3&amp;s=86" srcset="https://avatars3.githubusercontent.com/cheshire137?v=3&amp;s=86 1x, https://avatars3.githubusercontent.com/cheshire137?v=3&amp;s=172 2x, https://avatars3.githubusercontent.com/cheshire137?v=3&amp;s=258 3x, https://avatars3.githubusercontent.com/cheshire137?v=3&amp;s=344 4x" />
  <p><strong>cheshire137</strong></p>
</a>

<a href="https://github.com/charliesome" class="founder" target="_blank">
  <img class="avatar" alt="charliesome" width="86" height="86" data-proofer-ignore="true" src="https://avatars3.githubusercontent.com/charliesome?v=3&amp;s=86" srcset="https://avatars3.githubusercontent.com/charliesome?v=3&amp;s=86 1x, https://avatars3.githubusercontent.com/charliesome?v=3&amp;s=172 2x, https://avatars3.githubusercontent.com/charliesome?v=3&amp;s=258 3x, https://avatars3.githubusercontent.com/charliesome?v=3&amp;s=344 4x" />
  <p><strong>charliesome</strong></p>
</a>

<a href="https://github.com/benbalter" class="founder" target="_blank">
  <img class="avatar" alt="benbalter" width="86" height="86" data-proofer-ignore="true" src="https://avatars2.githubusercontent.com/benbalter?v=3&amp;s=86" srcset="https://avatars2.githubusercontent.com/benbalter?v=3&amp;s=86 1x, https://avatars2.githubusercontent.com/benbalter?v=3&amp;s=172 2x, https://avatars2.githubusercontent.com/benbalter?v=3&amp;s=258 3x, https://avatars2.githubusercontent.com/benbalter?v=3&amp;s=344 4x" />
  <p><strong>benbalter</strong></p>
</a>

<a href="https://github.com/jeffrafter" class="founder" target="_blank">
  <img class="avatar" alt="jeffrafter" width="86" height="86" data-proofer-ignore="true" src="https://avatars2.githubusercontent.com/jeffrafter?v=3&amp;s=86" srcset="https://avatars2.githubusercontent.com/jeffrafter?v=3&amp;s=86 1x, https://avatars2.githubusercontent.com/jeffrafter?v=3&amp;s=172 2x, https://avatars2.githubusercontent.com/jeffrafter?v=3&amp;s=258 3x, https://avatars2.githubusercontent.com/jeffrafter?v=3&amp;s=344 4x" />
  <p><strong>jeffrafter</strong></p>
</a>

<a href="https://github.com/muan" class="founder" target="_blank">
  <img class="avatar" alt="muan" width="86" height="86" data-proofer-ignore="true" src="https://avatars3.githubusercontent.com/muan?v=3&amp;s=86" srcset="https://avatars3.githubusercontent.com/muan?v=3&amp;s=86 1x, https://avatars3.githubusercontent.com/muan?v=3&amp;s=172 2x, https://avatars3.githubusercontent.com/muan?v=3&amp;s=258 3x, https://avatars3.githubusercontent.com/muan?v=3&amp;s=344 4x" />
  <p><strong>muan</strong></p>
</a>

<a href="https://github.com/pifafu" class="founder" target="_blank">
  <img class="avatar" alt="pifafu" width="86" height="86" data-proofer-ignore="true" src="https://avatars3.githubusercontent.com/pifafu?v=3&amp;s=86" srcset="https://avatars3.githubusercontent.com/pifafu?v=3&amp;s=86 1x, https://avatars3.githubusercontent.com/pifafu?v=3&amp;s=172 2x, https://avatars3.githubusercontent.com/pifafu?v=3&amp;s=258 3x, https://avatars3.githubusercontent.com/pifafu?v=3&amp;s=344 4x" />
  <p><strong>pifafu</strong></p>
</a>

<li><a href="https://help.github.com/categories/importing-your-projects-to-github/">Getting your project on GitHub</a></li>
<li><a href="/activities/forking/">Fork A Repository</a></li>

<li>Create and use a repository</li>
<li>Start and manage a new branch</li>
<li>Make changes to a file and push them to GitHub as commits</li>
<li>Open and merge a pull request</li>

<p><strong>Tip:</strong> Open this guide in a separate browser window (or tab) so you can see it while you complete the steps in the tutorial.</p>

<li>In the upper right corner, next to your avatar or identicon, click <span class="octicon octicon-plus"></span> and then select <strong>New repository</strong>.</li>
<li>Name your repository <code class="language-plaintext highlighter-rouge">hello-world</code>.</li>
<li>Write a short description.</li>
<li>Select <strong>Initialize this repository with a README</strong>.</li>

<li>The <code class="language-plaintext highlighter-rouge">master</code> branch</li>
<li>A new branch called <code class="language-plaintext highlighter-rouge">feature</code> (because we’re doing ‘feature work’ on this branch)</li>
<li>The journey that <code class="language-plaintext highlighter-rouge">feature</code> takes before it’s merged into <code class="language-plaintext highlighter-rouge">master</code></li>

<li><code class="language-plaintext highlighter-rouge">story.txt</code></li>
<li><code class="language-plaintext highlighter-rouge">story-joe-edit.txt</code></li>
<li><code class="language-plaintext highlighter-rouge">story-joe-edit-reviewed.txt</code></li>

<li>Go to your new repository <code class="language-plaintext highlighter-rouge">hello-world</code>.</li>
<li>Click the drop down at the top of the file list that says <strong>branch: master</strong>.</li>
<li>Type a branch name, <code class="language-plaintext highlighter-rouge">readme-edits</code>, into the new branch text box.</li>
<li>Select the blue <strong>Create branch</strong> box or hit “Enter” on your keyboard.</li>

<li>Click the <code class="language-plaintext highlighter-rouge">README.md</code> file.</li>
<li>Click the <span class="octicon octicon-pencil"></span> pencil icon in the upper right corner of the file view to edit.</li>
<li>In the editor, write a bit about yourself.</li>
<li>Write a commit message that describes your changes.</li>
<li>Click <strong>Commit changes</strong> button.</li>

<p><strong>Tip</strong>: You can use <a href="https://help.github.com/articles/basic-writing-and-formatting-syntax/#using-emoji">emoji</a> and <a href="https://help.github.com/articles/file-attachments-on-issues-and-pull-requests/">drag and drop images and gifs</a> onto comments and Pull Requests.</p>

<li>Click the green <strong>Merge pull request</strong> button to merge the changes into <code class="language-plaintext highlighter-rouge">master</code>.</li>
<li>Click <strong>Confirm merge</strong>.</li>
<li>Go ahead and delete the branch, since its changes have been incorporated, with the <strong>Delete branch</strong> button in the purple box.</li>

<li>Created an open source repository</li>
<li>Started and managed a new branch</li>
<li>Changed a file and committed those changes to GitHub</li>
<li>Opened and merged a Pull Request</li>

<p><strong>Tip</strong>: Check out our other <a href="http://guides.github.com">Guides</a>, <a href="http://youtube.com/githubguides">YouTube Channel</a> and <a href="https://services.github.com/on-demand/">On-Demand Training</a> for more on how to get started with GitHub.</p>

<li>
  <p>README files are a quick and simple way for other users to learn more about your work.</p>
</li>
<li>
  <p>Wikis on GitHub help you present in-depth information about your project in a useful way.</p>
</li>

<li>
  <p><strong>Project name</strong>: Your project’s name is the first thing people will see upon scrolling down to your README, and is included upon creation of your README file.</p>
</li>
<li>
  <p><strong>Description</strong>: A description of your project follows. A good description is clear, short, and to the point. Describe the importance of your project, and what it does.</p>
</li>
<li>
  <p><strong>Table of Contents</strong>: Optionally, include a table of contents in order to allow other people to quickly navigate especially long or detailed READMEs.</p>
</li>
<li>
  <p><strong>Installation</strong>: Installation is the next section in an effective README. Tell other users how to install your project locally. Optionally, include a gif to make the process even more clear for other people.</p>
</li>
<li>
  <p><strong>Usage</strong>: The next section is usage, in which you instruct other people on how to use your project after they’ve installed it. This would also be a good place to include screenshots of your project in action.</p>
</li>
<li>
  <p><strong>Contributing</strong>: Larger projects often have sections on contributing to their project, in which contribution instructions are outlined. Sometimes, this is a separate file. If you have specific contribution preferences, explain them so that other developers know how to best contribute to your work. To learn more about how to help others contribute, check out the guide for <a href="https://help.github.com/articles/setting-guidelines-for-repository-contributors/">setting guidelines for repository contributors</a>.</p>
</li>
<li>
  <p><strong>Credits</strong>: Include a section for credits in order to highlight and link to the authors of your project.</p>
</li>
<li>
  <p><strong>License</strong>: Finally, include a section for the license of your project. For more information on choosing a license, check out GitHub’s <a href="http://choosealicense.com/">licensing guide</a>!</p>
</li>

<p>
  If you're knowledgable with the command line, you can also modify wikis locally. Check out <a href="https://help.github.com/articles/adding-and-editing-wiki-pages-locally">our help article</a> for more info.
</p>

def foo
  puts 'bar'
end

</code></pre></div></div>

<p>The block must start with three backticks, optionally followed by the the name of the language that is contained by the block. See <a href="http://pygments.org/docs/lexers/">Pygments for the list of languages</a> that can be syntax highlighted.</p>

<p>The block contents should be indented at the same level as the opening backticks. The block must end with three backticks indented at the same level as the opening backticks.</p>

<h2>You’re done!</h2>

<p>You have learned some important information about how to best share your work with the rest of the GitHub community, whether your project is large enough in scope for its own wiki or you’re just starting out and setting up a clear and concise README.</p>

<p>To read more on the topics covered in this article, our guides for <a href="https://help.github.com/articles/creating-a-new-repository/">creating a new repository</a>, <a href="https://help.github.com/articles/editing-files-in-your-repository/">editing files in your repository</a>, <a href="https://help.github.com/articles/setting-guidelines-for-repository-contributors/">setting guidelines for repository contributors</a> and <a href="http://choosealicense.com">choosing a license</a> are great places to start. Otherwise, check out some other <a href="http://guides.github.com/">GitHub Guides</a> to keep learning.</p>

<p>Finally, if you’re interested in building a documentation site for your project, we recommend using <a href="https://pages.github.com/">GitHub Pages</a>.</p>
</description></item><item><title>Mastering Markdown</title><link>http://guides.github.com/features/mastering-markdown/</link><pubDate>Wed, 15 Jan 2014 00:00:00 +0000</pubDate><guid isPermaLink="true">http://guides.github.com/features/mastering-markdown/index.md</guid><description><p><a id="intro" title="Intro" class="toc-item"></a>
Markdown is a lightweight and easy-to-use syntax for styling all forms of writing on the GitHub platform.</p>

<p><strong>What you will learn:</strong></p>

<ul>
  <li>How the Markdown format makes styled collaborative editing easy</li>
  <li>How Markdown differs from traditional formatting approaches</li>
  <li>How to use Markdown to format text</li>
  <li>How to leverage GitHub’s automatic Markdown rendering</li>
  <li>How to apply GitHub’s unique Markdown extensions</li>
</ul>

<p><a id="what" title="What is Markdown?" class="toc-item"></a></p>

<h2>What is Markdown?</h2>

<p><a href="http://daringfireball.net/projects/markdown/">Markdown</a> is a way to style text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like <code class="language-plaintext highlighter-rouge">#</code> or <code class="language-plaintext highlighter-rouge">*</code>.</p>

<p>You can use Markdown most places around GitHub:</p>

<ul>
  <li><a href="https://gist.github.com/">Gists</a></li>
  <li>Comments in Issues and Pull Requests</li>
  <li>Files with the <code class="language-plaintext highlighter-rouge">.md</code> or <code class="language-plaintext highlighter-rouge">.markdown</code> extension</li>
</ul>

<p>For more information, see “<a href="https://help.github.com/categories/writing-on-github/">Writing on GitHub</a>” in the <em>GitHub Help</em>.</p>

<p><a id="examples" title="Examples" class="toc-item"></a></p>

<h2>Examples</h2>

<ul class="example-nav js-examples-nav">
  <li><a href="#" class="selected" data-container-id="example-text" data-proofer-ignore="">Text</a></li>
  <li><a href="#" data-container-id="example-lists" data-proofer-ignore="">Lists</a></li>
  <li><a href="#" data-container-id="example-images" data-proofer-ignore="">Images</a></li>
  <li><a href="#" data-container-id="example-headers" data-proofer-ignore="">Headers &amp; Quotes</a></li>
  <li><a href="#" data-container-id="example-code" data-proofer-ignore="">Code</a></li>
  <li><a href="#" data-container-id="example-extras" data-proofer-ignore="">Extras</a></li>
</ul>

<div class="markdown-example" id="example-text">
<pre class="source">
It's very easy to make some words **bold** and other words *italic* with Markdown. You can even <span style="white-space:nowrap">[link to Google!](http://google.com)</span>
</pre>
<div class="rendered">
It's very easy to make some words <strong>bold</strong> and other words <em>italic</em> with Markdown. You can even <a href="http://google.com">link to Google!</a>
</div>
</div>

<div class="markdown-example" id="example-lists" style="display:none">
<pre class="source">
Sometimes you want numbered lists:

1. One
2. Two
3. Three

Sometimes you want bullet points:

* Start a line with a star
* Profit!

Alternatively,

- Dashes work just as well
- And if you have sub points, put two spaces before the dash or star:
  - Like this
  - And this
</pre>
<div class="rendered">
  <p>Sometimes you want numbered lists:</p>
  <ol>
  <li>One</li>
  <li>Two</li>
  <li>Three</li>
  </ol>
  <p>Sometimes you want bullet points:</p>
  <ul>
  <li>Start a line with a star</li>
  <li>Profit!</li>
  </ul>
  <p>Alternatively,</p>
  <ul>
  <li>Dashes work just as well</li>
  <li>And if you have sub points, put two spaces before the dash or star:
  <ul>
  <li>Like this</li>
  <li>And this</li>
  </ul>
  </li>
  </ul>
</div>
</div>

<div class="markdown-example" id="example-images" style="display:none">
<pre class="source">
If you want to embed images, this is how you do it:

![Image of Yaktocat](https://octodex.github.com/images/yaktocat.png)
</pre>
<div class="rendered">
  <p>If you want to embed images, this is how you do it:</p>
  <p><img src="https://octodex.github.com/images/yaktocat.png" alt="Image of Yakotocat" /></p>
</div>
</div>

<div class="markdown-example" id="example-headers" style="display:none">
<pre class="source">
# Structured documents

Sometimes it's useful to have different levels of headings to structure your documents. Start lines with a `#` to create headings. Multiple `##` in a row denote smaller heading sizes.

### This is a third-tier heading

You can use one `#` all the way up to `######` six for different heading sizes.

If you'd like to quote someone, use the &gt; character before the line:

&gt; Coffee. The finest organic suspension ever devised... I beat the Borg with it.
&gt; - Captain Janeway
</pre>
<div class="rendered">
  <h1>Structured documents</h1>

  <p>Sometimes it&rsquo;s useful to have different levels of headings to structure your documents. Start lines with a <code>#</code> to create headings. Multiple <code>##</code> in a row denote smaller heading sizes.</p>

  <h3>This is a third-tier heading</h3>

  <p>You can use  one <code>#</code> all the way up to <code>######</code> six for different heading sizes.</p>

  <p>If you&rsquo;d like to quote someone, use the &gt; character before the line:</p>

  <blockquote><p>Coffee. The finest organic suspension ever devised&hellip; I beat the Borg with it.
  - Captain Janeway</p></blockquote>
</div>
</div>

<div class="markdown-example" id="example-code" style="display:none">
<pre class="source">
There are many different ways to style code with GitHub's markdown. If you have inline code blocks, wrap them in backticks: `var example = true`.  If you've got a longer block of code, you can indent with four spaces:

    if (isAwesome){
      return true
    }

GitHub also supports something called code fencing, which allows for multiple lines without indentation:

return true

And if you'd like to use syntax highlighting, include the language:

```javascript
if (isAwesome){
  return true
}

<p>There are many different ways to style code with GitHub&rsquo;s markdown. If you have inline code blocks, wrap them in backticks: <code>var example = true</code>.  If you&rsquo;ve got a longer block of code, you can indent with four spaces:</p>

return true

<p>GitHub also supports something called code fencing, which allows for multiple lines without indentation:</p>

return true

<p>And if you&rsquo;d like to use syntax highlighting, include the language:</p>

<span class="k">return</span> <span class="kc">true</span>

<p>GitHub supports many extras in Markdown that help you reference and link to people. If you ever want to direct a comment at someone, you can prefix their name with an @ symbol: Hey <a href="https://github.com/kneath" class="user-mention">@kneath</a> — love your sweater!</p>

<p>But I have to admit, tasks lists are my favorite:</p>

<ul class="task-list">
<li class="task-list-item">
<input type="checkbox" class="task-list-item-checkbox" checked="" disabled="" /> This is a complete item</li>
<li class="task-list-item">
<input type="checkbox" class="task-list-item-checkbox" disabled="" /> This is an incomplete item</li>
</ul>
<p>When you include a task list in the first comment of an Issue, you will see a helpful progress bar in your list of issues. It works in Pull Requests, too!</p>
<p>And, of course emoji! </p>

if(arg) {
  $.facebox({div:'#foo'})
}

</code></pre></div></div>

<p>You can also simply indent your code by four spaces:</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>    function fancyAlert(arg) {
      if(arg) {
        $.facebox({div:'#foo'})
      }
    }
</code></pre></div></div>

<p>Here’s an example of Python code without syntax highlighting:</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>def foo():
    if not bar:
        return True
</code></pre></div></div>

<h3>Task Lists</h3>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>- [x] @mentions, #refs, [links](), **formatting**, and &lt;del&gt;tags&lt;/del&gt; supported
- [x] list syntax required (any unordered or ordered list supported)
- [x] this is a complete item
- [ ] this is an incomplete item
</code></pre></div></div>

<p>If you include a task list in the first comment of an Issue, you will get a handy progress indicator in your issue list. It also works in Pull Requests!</p>

<h3>Tables</h3>

<p>You can create tables by assembling a list of words and dividing them with hyphens <code class="language-plaintext highlighter-rouge">-</code> (for the first row), and then separating each column with a pipe <code class="language-plaintext highlighter-rouge">|</code>:</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>First Header | Second Header
------------ | -------------
Content from cell 1 | Content from cell 2
Content in the first column | Content in the second column
</code></pre></div></div>

<p>Would become:</p>

<table>
  <thead>
    <tr>
      <th>First Header</th>
      <th>Second Header</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Content from cell 1</td>
      <td>Content from cell 2</td>
    </tr>
    <tr>
      <td>Content in the first column</td>
      <td>Content in the second column</td>
    </tr>
  </tbody>
</table>

<h3>SHA references</h3>

<p>Any reference to a commit’s <a href="http://en.wikipedia.org/wiki/SHA-1">SHA-1 hash</a> will be automatically converted into a link to that commit on GitHub.</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>16c999e8c71134401a78d4d46435517b2271d6ac
mojombo@16c999e8c71134401a78d4d46435517b2271d6ac
mojombo/github-flavored-markdown@16c999e8c71134401a78d4d46435517b2271d6ac
</code></pre></div></div>

<h3>Issue references within a repository</h3>

<p>Any number that refers to an Issue or Pull Request will be automatically converted into a link.</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>#1
mojombo#1
mojombo/github-flavored-markdown#1
</code></pre></div></div>

<h3>Username @mentions</h3>

<p>Typing an <code class="language-plaintext highlighter-rouge">@</code> symbol, followed by a username, will notify that person to come and view the comment. This is called an “@mention”, because you’re <em>mentioning</em> the individual. You can also @mention teams within an organization.</p>

<h3>Automatic linking for URLs</h3>

<p>Any URL (like <code class="language-plaintext highlighter-rouge">http://www.github.com/</code>) will be automatically converted into a clickable link.</p>

<h3>Strikethrough</h3>

<p>Any word wrapped with two tildes (like <code class="language-plaintext highlighter-rouge">~~this~~</code>) will appear crossed out.</p>

<h3>Emoji</h3>

<p>GitHub supports <a href="https://help.github.com/articles/basic-writing-and-formatting-syntax/#using-emoji">emoji</a>!</p>

<p>To see a list of every image we support, check out the <a href="https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md">Emoji Cheat Sheet</a>.</p>
</description></item><item><title>Mastering Issues</title><link>http://guides.github.com/features/issues/</link><pubDate>Mon, 07 Apr 2014 00:00:00 +0000</pubDate><guid isPermaLink="true">http://guides.github.com/features/issues/index.md</guid><description><p><a id="intro" title="Intro" class="toc-item"></a>
Issues are a great way to keep track of tasks, enhancements, and bugs for your projects. They’re kind of like email—except they can be shared and discussed with the rest of your team. Most software projects have a bug tracker of some kind. GitHub’s tracker is called <strong>Issues</strong>, and has its own section in every repository.</p>

<p><img src="/features/issues/navigation-highlight.png" alt="Highlighting navigation" /></p>

<p>For example, let’s take a look at <a href="https://github.com/twbs/bootstrap/issues" target="_blank">Bootstrap’s Issues section</a>:</p>

<p><img src="/features/issues/listing-screen.png" alt="List of issues" /></p>

<p>GitHub’s issue tracking is special because of our focus on collaboration, references, and excellent text formatting. A typical issue on GitHub looks a bit like this:</p>

<p><img src="/features/issues/example-issue.png" alt="An example issue" /></p>

<ul>
  <li>
    <p>A <strong>title</strong> and <strong>description</strong> describe what the issue is all about.</p>
  </li>
  <li>
    <p>Color-coded <strong>labels</strong> help you categorize and filter your issues (just like labels in email).</p>
  </li>
  <li>
    <p>A <strong>milestone</strong> acts like a container for issues. This is useful for associating issues with specific features or project phases (e.g. <em>Weekly Sprint 9/5-9/16</em> or <em>Shipping 1.0</em>).</p>
  </li>
  <li>
    <p>One <strong>assignee</strong> is responsible for working on the issue at any given time.</p>
  </li>
  <li>
    <p><strong>Comments</strong> allow anyone with access to the repository to provide feedback.</p>
  </li>
</ul>

<p><a id="filtering" title="Milestones, Labels &amp; Assignees" class="toc-item"></a></p>

<h2>Milestones, Labels, and Assignees</h2>

<p>Once you’ve collected a lot of issues, you may find it hard to find the ones you care about. <strong>Milestones</strong>, <strong>labels</strong>, and <strong>assignees</strong> are great features to filter and categorize issues.</p>

<p>You can change or add a milestone, an assignee, and labels by clicking their corresponding gears in the sidebar on the right.</p>

<p><img src="/features/issues/labels.png" alt="Viewing labels" /></p>

<p>If you don’t see edit buttons, that’s because you don’t have permission to edit the issue. You can ask the repository owner to add you as a collaborator to get access.</p>

<h3>Milestones</h3>

<p><img src="/features/issues/milestones.png" alt="Viewing Milestones" /></p>

<p>Milestones are groups of issues that correspond to a project, feature, or time period. People use them in many different ways in software development. Some examples of milestones on GitHub include:</p>

<ul>
  <li>
    <p><strong>Beta Launch</strong> — File bugs that you need to fix before you can launch the beta of your project. It’s a great way to make sure you aren’t missing anything.</p>
  </li>
  <li>
    <p><strong>October Sprint</strong> — File issues that you’d like to work on in October. A great way to focus your efforts when there’s a lot to do.</p>
  </li>
  <li>
    <p><strong>Redesign</strong> — File issues related to redesigning your project. A great way to collect ideas on what to work on.</p>
  </li>
</ul>

<h3>Labels</h3>

<p>Labels are a great way to organize different types of issues. Issues can have as many labels as you want, and you can filter by one or many labels at once.</p>

<p><img src="/features/issues/labels-listing.png" alt="Viewing label listings" /></p>

<h3>Assignees</h3>

<p>Each issue can have an assignee — one person that’s responsible for moving the issue forward. Assignees are selected the same way milestones are, through the grey bar at the top of the issue.</p>

<p><a id="notifications" title="Notifications, @mentions, and references" class="toc-item"></a></p>

<h2>Notifications, @mentions, and References</h2>

<p>By using @mentions and references inside of Issues, you can notify other GitHub users &amp; teams, and cross-connect issues to each other. These provide a flexible way to get the right people involved to resolve issues effectively, and are easy to learn and use. They work across all text fields on GitHub — they’re a part of our text formatting syntax called <a href="https://help.github.com/articles/writing-on-github#name-and-team-mentions-autocomplete">GitHub Flavored Markdown</a>.</p>

<p><img src="/features/issues/markdown-example.png" alt="Example of Markdown" /></p>

<p>If you’d like to learn more, have a look at <strong><a href="http://guides.github.com/features/mastering-markdown/">Mastering Markdown</a></strong>.</p>

<h3>Notifications</h3>

<p><a href="https://github.com/notifications" target="_blank">Notifications</a> are GitHub’s way to keep up to date with your Issues. You can use them to find out about new issues on repositories, or just to know when someone needs your input to move forward on an issue.</p>

<p>There are two ways to receive notifications: via email, and via the web. You can configure how you receive notifications <a href="https://github.com/settings/notifications" target="_blank">in your settings</a>. If you plan on receiving a lot of notifications, we like to recommend that you receive web + email notifications for <strong>Participating</strong> and web notifications for <strong>Watching</strong>.</p>

<p><img src="/features/issues/notifications.png" alt="Screenshot of notifications" /></p>

<p>With these settings, you receive emails when people specifically mention you, then visit the web-based interface to keep up to date with repositories you’re interested in.</p>

<p>You can access your notifications through the <a href="https://github.com/notifications" target="_blank">notifications</a> screen. This screen is nice for scanning many notifications at once and marking them as read or muting the thread. Try using keyboard shortcuts to speed up your workflow here — press <code class="language-plaintext highlighter-rouge">?</code> on the page to see which shortcuts are available.</p>

<p><img src="/features/issues/notification.png" alt="Screenshot of an individual notification" /></p>

<p>Muted threads won’t show up as unread again until you are specifically @mentioned again. This makes muting a great strategy for threads that you have little interest in (perhaps a sub-system that you aren’t familiar with). If you mark an issue as read, it will stay that way until someone comments on the thread again.</p>

<p>GitHub also syncs read/unread status for email notifications — if you read a notification in your email client, it will be marked as read in the web-based interface (make sure you allow your email client to display images if you’d like this functionality).</p>

<h3>@mentions</h3>

<p>@mentions are the way that we reference other GitHub users inside of GitHub Issues. Inside of the description or any comment of the issue, include the @username of another GitHub user to send them a notification. This works very similar to how Twitter uses @mentions.</p>

<p>We like to use the <code class="language-plaintext highlighter-rouge">/cc</code> syntax (an abbreviation for carbon copy) to include people in issues:</p>

<blockquote>
  <p>It looks like the new widget form is broken on Safari. When I try and create the widget, Safari crashes. This is reproducible on 10.8, but not 10.9. Maybe a browser bug?</p>

  <p>/cc @kneath @jresig</p>
</blockquote>

<p>This works great if you know the specific users to include, but many times we’re working across teams and don’t really know who might be able to help us. @mentions also work for Teams within your GitHub organization. If you create a Team called <em>browser-bugs</em> under the @acmeinc organization, you can reference the team with @mentions:</p>

<blockquote>
  <p>/cc @acmeinc/browser-bugs</p>
</blockquote>

<p>This will send notifications to every member of the browser-bugs team.</p>

<h3>References</h3>

<p>Often times issues are dependent on other issues, or at least relate to them and you’d like to connect the two. You can reference issues by typing in a hashtag plus the issue number.</p>
<blockquote>
  <p>Hey @kneath, I think the problem started in #42</p>
</blockquote>

<p>When you do this, we’ll create an event inside of issue #42 that looks something like this:</p>

<p><img src="/features/issues/reference.png" alt="Screenshot of creating a reference" /></p>

<p>Issue in another repository? Just include the repository before the name like <code class="language-plaintext highlighter-rouge">kneath/example-project#42</code>.</p>

<p>One of the more interesting ways to use GitHub Issues is to reference issues directly from commits. Include the issue number inside of the commit message.</p>

<p><img src="/features/issues/commit.png" alt="Screenshot of referencing a commit" /></p>

<p>By prefacing your commits with “Fixes”, “Fixed”, “Fix”, “Closes”, “Closed”, or “Close” when the commit is merged into master, it will also automatically close the issue.</p>

<p>References make it possible to deeply connect the work being done with the bug being tracked, and are a great way to add visibility into the history of your project.</p>

<p><a id="search" title="Search" class="toc-item"></a></p>

<h2>Search</h2>

<p>At the very top of each page is a search box that lets you search through issues.</p>

<p><img src="/features/issues/search.png" alt="Screenshot of making a search" /></p>

<p>You can scope search results by:</p>

<ul>
  <li>
    <p>Keyword, such as, <a href="https://github.com/twbs/bootstrap/issues?q=sidebar">all issues mentioning the sidebar</a></p>
  </li>
  <li>
    <p>State, such as, <a href="https://github.com/twbs/bootstrap/issues?q=sidebar+is%3Aclosed">all issues mentioning the sidebar that are closed</a></p>
  </li>
  <li>
    <p>Assignee, such as, <a href="https://github.com/twbs/bootstrap/issues?q=sidebar+is%3Aclosed+assignee%3Amdo">all issues mentioning the sidebar that were assigned to @mdo</a></p>
  </li>
</ul>

<p><a href="https://help.github.com/articles/using-search-to-filter-issues-and-pull-requests">Our Help article on searching Issues</a> can show you other ways to search: using created/updated dates, labels, authors, comment counts, by repository owner, and more.</p>

<p><a id="overviews" title="Overviews &amp; Reports" class="toc-item"></a></p>

<h2>Overviews &amp; Reports</h2>

<p>Outside of the Issues section, there are two other pages that help summarize what’s going on with Issues across your repository and across all of your repositories.</p>

<h3>The Issue Dashboard</h3>

<p>If you’re looking for a broader listing of all of your issues across many projects, the <a href="https://github.com/issues" target="_blank" data-proofer-ignore="">Issues Dashboard</a> can be a great tool. The dashboard works very similar to the issues section, but collects issues differently:</p>

<ul>
  <li>All issues in repositories you own and collaborate on</li>
  <li>Issues assigned to you</li>
  <li>Issues you’ve created</li>
</ul>

<p>If you use organizations, each one has its own Issues dashboard that separates out Issues within the organization.</p>

<h3>Pulse</h3>

<p>Underneath each repository is a section called <strong>Pulse</strong> — Pulse is a snapshot of everything that’s happened in the repository in the past week (or day, or past 3 months, etc).</p>

<p><img src="/features/issues/pulse.png" alt="Screenshot of the Pulse feature" /></p>

<p>It’s a great way to catch up with repositories when you’ve been away and don’t want the granularity notifications offer when watching a repository.</p>

<p><a id="uses" title="Other uses for Issues" class="toc-item"></a></p>

<h2>Other Uses for Issues</h2>

<p>Issues are great for tracking all kinds of things — and GitHub is a great place to easily share and collaborate on your issues.  Here’s some of our favorites:</p>

<ul>
  <li>
    <p><a href="https://github.com/joyent/node/issues" target="_blank">Bug tracker for your open source projects</a></p>
  </li>
  <li>
    <p><a href="https://github.com/newmerator/recipes/issues" target="_blank">Request for recipes</a> (maybe you have a good <strong><a href="https://github.com/newmerator/recipes/issues/3" target="_blank">gluten-free pizza dough recipe</a>?</strong>)</p>
  </li>
</ul>

<h2>Fin</h2>

<p><strong>Now congratulate yourself</strong> — that was a lot to read! Issue management is one of the most powerful tools at any developer’s disposal. I guess all that’s left is to actually fix the bugs now.</p>
</description></item><item><title>Getting Started with GitHub Pages</title><link>http://guides.github.com/features/pages/</link><pubDate>Sun, 01 Dec 2013 00:00:00 +0000</pubDate><guid isPermaLink="true">http://guides.github.com/features/pages/index.md</guid><description><p><a id="intro" title="Intro" class="toc-item"></a>
GitHub Pages are public webpages hosted and easily published through GitHub. The quickest way to get up and running is by using the Jekyll Theme Chooser to load a pre-made theme. You can then modify your GitHub Pages’ content and style remotely via the web or locally on your computer.</p>

<p><img src="/features/pages/pages-home-page.png" alt="pages-home-page" /></p>

<p><a id="setup" title="Create Your Website" class="toc-item"></a></p>

<h2>Create Your Website</h2>

<p>Once you’ve <a href="https://github.com/login" target="_blank">signed in</a>, you’ll create a new repository to get started.</p>

<p><img src="/features/pages/create-new-repo-button.png" alt="new-repo-button" /></p>

<p>On the new repository screen, you need to give this repository a special name to generate your website.</p>

<p><img src="/features/pages/create-new-repo-screen.png" alt="new-repo-screen" /></p>

<p>Your website’s files will live in a repository named <code class="language-plaintext highlighter-rouge">username.github.io</code> (where “username” is your actual GitHub user name). To begin setting up your site, you have to open the Settings tab</p>

<p><img src="/features/pages/repo-settings.png" alt="settings-tab" /></p>

<p>If you scroll down on the settings page, you’ll see the <strong>GitHub Pages</strong> section near the bottom. Click the <strong>Choose a theme</strong> button to start the process of creating your site.</p>

<p><img src="/features/pages/launch-theme-chooser.png" alt="launch-theme-chooser" /></p>

<p>Once you’ve clicked the button, you’ll be directed to the Theme Chooser. You’ll see several theme options in a carousel across the top of the page. Click on the images to preview the themes. Once you’ve selected one, click <strong>Select theme</strong> on the right to move on. It’s easy to change your theme later, so if you’re not sure, just choose one for now.</p>

<p><img src="/features/pages/theme-chooser.png" alt="theme-chooser" /></p>

<p>Here’s where you’ll write your own content (You can keep the default content for now, if you’d like).</p>

<p><img src="/features/pages/code-editor.png" alt="code-editor" /></p>

<p>Once you’re finished editing, scroll down to the bottom of the page and click <strong>Commit changes</strong>.</p>

<p><img src="/features/pages/commit-edits.png" alt="commit-edits" /></p>

<p>GitHub does all the work to direct visitors to <code class="language-plaintext highlighter-rouge">username.github.io</code> to view your new website. This can take up to 10 minutes. After some time has passed, you can open a new tab in your browser to go to your site!</p>

<p><a id="changes" title="Making Changes" class="toc-item"></a></p>

<h2>Making Changes</h2>

<p>One of the first things you can do is remove the default title of your index page, and add a friendlier message to it. Since this is a very quick change – and your first one – you’re going to make it on the default branch: <code class="language-plaintext highlighter-rouge">master</code>.</p>

<p>View the <code class="language-plaintext highlighter-rouge">_config.yml</code> file by navigating to it in the <strong>Code</strong> tab. You can edit the file by clicking on the pencil icon.</p>

<p><img src="/features/pages/edit-file.png" alt="edit-page" /></p>

<p>Currently your site has no set title, so we’re falling back to the name of the repo. To change this, I’m going to add the line “title: Welcome to the Octocat’s homepage!” to this file. Feel free to do the same, except for your own username.</p>

<p>Under this title, you can add a message about the purpose of the page and describe what you want people to do while they’re here. I’m going set mine to “Feel free to bookmark this to keep an eye on my project updates”</p>

<p><img src="/features/pages/change-title-description.png" alt="change-title-description" /></p>

<p>After you’re done making this small change, scroll to the bottom of the page to make your second commit. You have two places to write about this change: a subject and an extended description. The extended description is optional, so let’s leave a descriptive message in the subject.</p>

<p>When you’re done, click <strong>Commit changes</strong> and your updates will go live in just a few seconds!</p>

<p><img src="/features/pages/commit-messages-matter.png" alt="be-descriptive" /></p>

<p><a id="next-steps" title="Next Steps" class="toc-item"></a></p>

<h2>Next Steps</h2>

<p>Just because you’ve made some changes into your project doesn’t mean you should stop! Check out these other guides to learn how to contribute to other projects or perfect the way you work on projects:</p>

<ul>
  <li><a href="/introduction/flow">GitHub flow</a></li>
  <li><a href="/activities/contributing-to-open-source/">Contributing to Open Source</a></li>
  <li><a href="/features/mastering-markdown/">Mastering Markdown</a></li>
</ul>

</description></item><item><title>Git Handbook</title><link>http://guides.github.com/introduction/git-handbook/</link><pubDate>Mon, 25 Sep 2017 00:00:00 +0000</pubDate><guid isPermaLink="true">http://guides.github.com/introduction/git-handbook/index.md</guid><description><p><a id="version-control" title="What is Version Control?" class="toc-item"></a></p>

<h3>What’s a version control system?</h3>

<p>A version control system, or VCS, tracks the history of changes as people and teams collaborate on projects together. As the project evolves, teams can run tests, fix bugs, and contribute new code with the confidence that any version can be recovered at any time. Developers can review project history to find out:</p>

<ul>
  <li>Which changes were made?</li>
  <li>Who made the changes?</li>
  <li>When were the changes made?</li>
  <li>Why were changes needed?</li>
</ul>

<h3>What’s a distributed version control system?</h3>

<p>Git is an example of a distributed version control system (DVCS) commonly used for open source and commercial software development. DVCSs allow full access to every file, branch, and iteration of a project, and allows every user access to a full and self-contained history of all changes. Unlike once popular centralized version control systems, DVCSs like Git don’t need a constant connection to a central repository. Developers can work anywhere and collaborate asynchronously from any time zone.</p>

<p>Without version control, team members are subject to redundant tasks, slower timelines, and multiple copies of a single project. To eliminate unnecessary work, Git and other VCSs give each contributor a unified and consistent view of a project, surfacing work that’s already in progress. Seeing a transparent history of changes, who made them, and how they contribute to the development of a project helps team members stay aligned while working independently.</p>

<h3>Why Git?</h3>

<p>According to the latest <a href="https://insights.stackoverflow.com/survey/2017#technology">Stack Overflow developer survey</a>, more than 70 percent of developers use Git, making it the most-used VCS in the world. Git is commonly used for both open source and commercial software development, <strong>with significant benefits</strong> for individuals, teams and businesses.</p>

<ul>
  <li>
    <p>Git lets developers see the entire timeline of their changes, decisions, and progression of any project in one place. From the moment they access the history of a project, the developer has all the context they need to understand it and start contributing.</p>
  </li>
  <li>
    <p>Developers work in every time zone. With a DVCS like Git, collaboration can happen any time while maintaining source code integrity. Using branches, developers can safely propose changes to production code.</p>
  </li>
  <li>
    <p>Businesses using Git can break down communication barriers between teams and keep them focused on doing their best work. Plus, Git makes it possible to align experts across a business to collaborate on major projects.</p>
  </li>
</ul>

<p><a id="repository" title="Repositories" class="toc-item"></a></p>

<h3>What’s a repository?</h3>

<p>A <em>repository</em>, or <a href="https://git-scm.com/">Git project</a>, encompasses the entire collection of files and folders associated with a project, along with each file’s revision history. The file history appears as snapshots in time called <em>commits</em>, and the commits exist as a linked-list relationship, and can be organized into multiple lines of development called <em>branches</em>. Because Git is a DVCS, repositories are self-contained units and anyone who owns a copy of the repository can access the entire codebase and its history. Using the command line or other ease-of-use interfaces, a git repository also allows for: interaction with the history, cloning, creating branches, committing, merging, comparing changes across versions of code, and more.</p>

<p>Working in repositories keeps development projects organized and protected. Developers are encouraged to fix bugs, or create fresh features, without fear of derailing mainline development efforts. Git facilitates this through the use of topic branches: lightweight pointers to commits in history that can be easily created and deprecated when no longer needed.</p>

<p>Through platforms like GitHub, Git also provides more opportunities for project transparency and collaboration. Public repositories help teams work together to build the best possible final product.</p>

<p><a id="basic-git" title="Basic Git" class="toc-item"></a></p>

<h3>Basic Git commands</h3>

<p>To use Git, developers use specific commands to copy, create, change, and combine code. These commands can be executed directly from the command line or by using an application like <a href="https://desktop.github.com/">GitHub Desktop</a> or Git Kraken. Here are some common commands for using Git:</p>

<ul>
  <li>
    <p><code class="language-plaintext highlighter-rouge">git init</code> initializes a brand new Git repository and begins tracking an existing directory. It adds a hidden subfolder within the existing directory that houses the internal data structure required for version control.</p>
  </li>
  <li>
    <p><code class="language-plaintext highlighter-rouge">git clone</code> creates a local copy of a project that already exists remotely. The clone includes all the project’s files, history, and branches.</p>
  </li>
  <li>
    <p><code class="language-plaintext highlighter-rouge">git add</code> stages a change. Git tracks changes to a developer’s codebase, but it’s necessary to stage and take a snapshot of the changes to include them in the project’s history. This command performs staging, the first part of that two-step process. Any changes that are staged will become a part of the next snapshot and a part of the project’s history. Staging and committing separately gives developers complete control over the history of their project without changing how they code and work.</p>
  </li>
  <li>
    <p><code class="language-plaintext highlighter-rouge">git commit</code> saves the snapshot to the project history and completes the change-tracking process. In short, a commit functions like taking a photo. Anything that’s been staged with <code class="language-plaintext highlighter-rouge">git add</code> will become a part of the snapshot with <code class="language-plaintext highlighter-rouge">git commit</code>.</p>
  </li>
  <li>
    <p><code class="language-plaintext highlighter-rouge">git status</code> shows the status of changes as untracked, modified, or staged.</p>
  </li>
  <li>
    <p><code class="language-plaintext highlighter-rouge">git branch</code> shows the branches being worked on locally.</p>
  </li>
  <li>
    <p><code class="language-plaintext highlighter-rouge">git merge</code> merges lines of development together. This command is typically used to combine changes made on two distinct branches. For example, a developer would merge when they want to combine changes from a feature branch into the master branch for deployment.</p>
  </li>
  <li>
    <p><code class="language-plaintext highlighter-rouge">git pull</code> updates the local line of development with updates from its remote counterpart. Developers use this command if a teammate has made commits to a branch on a remote, and they would like to reflect those changes in their local environment.</p>
  </li>
  <li>
    <p><code class="language-plaintext highlighter-rouge">git push</code> updates the remote repository with any commits made locally to a branch.</p>
  </li>
</ul>

<p>Learn more from <a href="https://git-scm.com/docs">a full reference guide to Git commands</a>.</p>

<h4>Explore more Git commands</h4>

<p>For a detailed look at Git practices, the videos below show how to get the most out of some Git commands.</p>

<ul>
  <li><a href="https://www.youtube.com/watch?v=rBbbOouhI-s&amp;index=2&amp;list=PLg7s6cbtAD17Gw5u8644bgKhgRLiJXdX4">Working locally</a></li>
  <li><a href="https://www.youtube.com/watch?v=SxmveNrZb5k&amp;list=PLg7s6cbtAD17Gw5u8644bgKhgRLiJXdX4&amp;index=3"><code class="language-plaintext highlighter-rouge">git status</code></a></li>
  <li><a href="https://www.youtube.com/watch?v=Vb0Ghkkc2hk&amp;index=4&amp;list=PLg7s6cbtAD17Gw5u8644bgKhgRLiJXdX4">Two-step commits</a></li>
  <li><a href="https://www.youtube.com/watch?v=-uQHV9GOA0w&amp;index=5&amp;list=PLg7s6cbtAD17Gw5u8644bgKhgRLiJXdX4"><code class="language-plaintext highlighter-rouge">git pull</code> and <code class="language-plaintext highlighter-rouge">git push</code></a></li>
</ul>

<p><a id="github" title="GitHub" class="toc-item"></a></p>

<h3>How GitHub fits in</h3>

<p>GitHub is a Git hosting repository that provides developers with tools to ship better code through command line features, issues (threaded discussions), pull requests, code review, or the use of a collection of free and for-purchase apps in the GitHub Marketplace. With collaboration layers like the GitHub flow, a community of 15 million developers, and an ecosystem with hundreds of integrations, GitHub changes the way software is built.</p>

<h3>How GitHub works</h3>

<p>GitHub builds collaboration directly into the development process. Work is organized into repositories, where developers can outline requirements or direction and set expectations for team members. Then, using the GitHub flow, developers simply create a branch to work on updates, commit changes to save them, open a pull request to propose and discuss changes, and merge pull requests once everyone is on the same page.</p>

<h3>The GitHub flow</h3>

<p>The GitHub flow is a lightweight, branch-based workflow built around core Git commands used by teams around the globe—including ours.</p>

<p>The GitHub flow has six steps, each with distinct benefits when implemented:</p>

<ol>
  <li><strong>Create a branch:</strong> Topic branches created from the canonical deployment branch (usually <code class="language-plaintext highlighter-rouge">master</code>) allow teams to contribute to many parallel efforts. Short-lived topic branches, in particular, keep teams focused and results in quick ships.</li>
  <li><strong>Add commits:</strong> Snapshots of development efforts within a branch create safe, revertible points in the project’s history.</li>
  <li><strong>Open a pull request:</strong> Pull requests publicize a project’s ongoing efforts and set the tone for a transparent development process.</li>
  <li><strong>Discuss and review code:</strong> Teams participate in code reviews by commenting, testing, and reviewing open pull requests. Code review is at the core of an open and participatory culture.</li>
  <li><strong>Merge:</strong> Upon clicking merge, GitHub automatically performs the equivalent of a local ‘git merge’ operation. GitHub also keeps the entire branch development history on the merged pull request.</li>
  <li><strong>Deploy:</strong> Teams can choose the best release cycles or incorporate continuous integration tools and operate with the assurance that code on the deployment branch has gone through a robust workflow.</li>
</ol>

<h4>Learn more about the GitHub flow</h4>

<p>Developers can find more information about the GitHub flow in the resources provided below.</p>

<ul>
  <li><a href="https://guides.github.com/introduction/flow/">Interactive guide</a></li>
  <li><a href="https://www.youtube.com/watch?v=47E-jcuQz5c&amp;index=1&amp;list=PLg7s6cbtAD17Gw5u8644bgKhgRLiJXdX4">GitHub Flow video</a></li>
</ul>

<h3>GitHub and the command line</h3>

<p>For developers new to the command line, the GitHub Training team has put together a series of <a href="https://help.github.com/articles/git-and-github-learning-resources/">tutorials</a> on Git commands to guide the way. Sometimes, a series of commands can paint a picture of how to use Git:</p>

<h4>Example: Contribute to an existing repository</h4>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># download a repository on GitHub.com to our machine</span>
git clone https://github.com/me/repo.git

<span class="c"># change into the `repo` directory</span>
<span class="nb">cd </span>repo

<span class="c"># create a new branch to store any new changes</span>
git branch my-branch

<span class="c"># switch to that branch (line of development)</span>
git checkout my-branch

<span class="c"># make changes, for example, edit `file1.md` and `file2.md` using the text editor</span>

<span class="c"># stage the changed files</span>
git add file1.md file2.md

<span class="c"># take a snapshot of the staging area (anything that's been added)</span>
git commit <span class="nt">-m</span> <span class="s2">"my snapshot"</span>

<span class="c"># push changes to github</span>
git push <span class="nt">--set-upstream</span> origin my-branch
</code></pre></div></div>

<h4>Example: Start a new repository and publish it to GitHub</h4>

<p>First, you will need to create a new repository on GitHub. You can learn how to create a new repository in our <a href="https://guides.github.com/activities/hello-world/#repository">Hello World guide</a>. <strong>Do not</strong> initialize the repository with a README, .gitignore or License. This empty repository will await your code.</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># create a new directory, and initialize it with git-specific functions</span>
git init my-repo

<span class="c"># change into the `my-repo` directory</span>
<span class="nb">cd </span>my-repo

<span class="c"># create the first file in the project</span>
<span class="nb">touch </span>README.md

<span class="c"># git isn't aware of the file, stage it</span>
git add README.md

<span class="c"># take a snapshot of the staging area</span>
git commit <span class="nt">-m</span> <span class="s2">"add README to initial commit"</span>

<span class="c"># provide the path for the repository you created on github</span>
git remote add origin https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git

<span class="c"># push changes to github</span>
git push <span class="nt">--set-upstream</span> origin master
</code></pre></div></div>

<h4>Example: contribute to an existing branch on GitHub</h4>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># assumption: a project called `repo` already exists on the machine, and a new branch has been pushed to GitHub.com since the last time changes were made locally</span>

<span class="c"># change into the `repo` directory</span>
<span class="nb">cd </span>repo

<span class="c"># update all remote tracking branches, and the currently checked out branch</span>
git pull

<span class="c"># change into the existing branch called `feature-a`</span>
git checkout feature-a

<span class="c"># make changes, for example, edit `file1.md` using the text editor</span>

<span class="c"># stage the changed file</span>
git add file1.md

<span class="c"># take a snapshot of the staging area</span>
git commit <span class="nt">-m</span> <span class="s2">"edit file1"</span>

<span class="c"># push changes to github</span>
git push
</code></pre></div></div>

<h3>Models for collaborative development</h3>

<p>There are two primary ways people collaborate on GitHub:</p>

<ol>
  <li>Shared repository</li>
  <li><a href="https://help.github.com/articles/about-forks/">Fork</a> and <a href="https://help.github.com/articles/using-pull-requests">pull</a></li>
</ol>

<p>With a <em>shared repository</em>, individuals and teams are explicitly designated as contributors with read, write, or administrator access. This simple permission structure, combined with features like protected branches and Marketplace, helps teams progress quickly when they adopt GitHub.</p>

<p>For an open source project, or for projects to which anyone can contribute, managing individual permissions can be challenging, but a <em>fork and pull</em> model allows anyone who can view the project to contribute. A fork is a copy of a project under an developer’s personal account. Every developer has full control of their fork and is free to implement a fix or new feature. Work completed in forks is either kept separate, or is surfaced back to the original project via a pull request. There, maintainers can review the suggested changes before they’re merged. See the <a href="https://guides.github.com/activities/forking/">Forking Projects Guide</a> for more information.</p>

<h3>Learn at your own pace</h3>

<p>The GitHub team has created a library of educational videos and guides to help users continue to develop their skills and build better software.</p>

<ul>
  <li><a href="https://github.com/showcases/great-for-new-contributors">Beginner projects to explore</a></li>
  <li><a href="https://youtube.com/githubguides">GitHub video guides</a></li>
  <li><a href="https://services.github.com/on-demand/">GitHub on-demand training</a></li>
  <li><a href="https://guides.github.com/">GitHub training guides</a></li>
  <li><a href="https://services.github.com/resources/">GitHub training resources</a></li>
</ul>
</description></item><item><title>Understanding the GitHub flow</title><link>http://guides.github.com/introduction/flow/</link><pubDate>Thu, 30 Nov 2017 00:00:00 +0000</pubDate><guid isPermaLink="true">http://guides.github.com/introduction/flow/index.md</guid><description><p>GitHub flow is a lightweight, branch-based workflow that supports teams and projects where deployments are made regularly. This guide explains how and why GitHub flow works.</p>

<script type="text/javascript" src="flow.js"></script>

<link rel="stylesheet" type="text/css" href="flow.css" />

<div class="scrollable-diagram js-scrollable-diagram">
  <div class="features-branch-diagram" id="js-features-branch-diagram">
    <svg width="930px" height="350" id="js-features-branch-diagram-svg" xmlns="http://www.w3.org/2000/svg">
      <path d="M66.2711864,5.96363636 C135.523206,5.96363636 143.460673,112 191.02837,112 C238.596067,112 681.049887,112 725.83852,112 C770.627152,112 786.056674,5.95721244 855.110732,5.96363636" id="js-branch-diagram-branch" stroke="#4182C4" stroke-width="4" fill="none"></path>
      <path d="M0,7 L766,7 L920,7" id="js-branch-diagram-master" stroke="#c6d9ed" stroke-width="8"></path>
      <path id="js-branch-diagram-arrow" d="M907.2,10 C910.98,8.95 915.22,8.05 918,7 C914.22,5.95 910.98,5.05 907.2,4" stroke="#c6d9ed" stroke-width="8" fill="none"></path>
    </svg>

    <div class="diagram-icon js-diagram-icon diagram-icon-branch" data-diagram-step="branch">
      <span class="mega-octicon octicon-git-branch"></span>
    </div>
    <div class="diagram-icon-small js-diagram-icon-small diagram-icon-commit-1" data-diagram-step="commits">
      <span class="mega-octicon octicon-git-commit"></span>
    </div>
    <div class="diagram-icon-small js-diagram-icon-small diagram-icon-commit-2" data-diagram-step="commits">
      <span class="mega-octicon octicon-git-commit"></span>
    </div>
    <div class="diagram-icon-small js-diagram-icon-small diagram-icon-commit-3" data-diagram-step="commits">
      <span class="mega-octicon octicon-git-commit"></span>
    </div>
    <div class="diagram-icon js-diagram-icon diagram-icon-pr" data-diagram-step="pr">
      <span class="mega-octicon octicon-git-pull-request"></span>
    </div>
    <div class="diagram-icon js-diagram-icon diagram-icon-merge" data-diagram-step="merge">
      <span class="mega-octicon octicon-git-merge"></span>
    </div>
    <div class="diagram-icon-small js-diagram-icon-small diagram-icon-discussion-1" data-diagram-step="code-review">
      <span class="mega-octicon octicon-comment-discussion"></span>
    </div>
    <div class="diagram-icon-small js-diagram-icon-small diagram-icon-commit-4" data-diagram-step="code-review">
      <span class="mega-octicon octicon-git-commit"></span>
    </div>
    <div class="diagram-icon-small js-diagram-icon-small diagram-icon-discussion-2" data-diagram-step="code-review">
      <span class="mega-octicon octicon-comment-discussion"></span>
    </div>
    <div class="diagram-icon-small js-diagram-icon-small diagram-icon-commit-5" data-diagram-step="code-review">
      <span class="mega-octicon octicon-git-commit"></span>
    </div>
    <div class="diagram-icon-small js-diagram-icon-small diagram-icon-discussion-3" data-diagram-step="code-review">
      <span class="mega-octicon octicon-comment-discussion"></span>
    </div>
    <div class="diagram-icon-small js-diagram-icon-small diagram-icon-commit-6" data-diagram-step="code-review">
      <span class="mega-octicon octicon-git-commit"></span>
    </div>
    <div class="diagram-icon js-diagram-icon-small diagram-icon-deploy" data-diagram-step="deploy">
      <span class="mega-octicon octicon-squirrel"></span>
    </div>
  </div>
</div>

<div class="flow-content">

  <div class="panel-content js-panel-content js-panel-content-branch" data-step="branch">
    <h3>Create a branch</h3>

    <p>When you're working on a project, you're going to have a bunch of different features or ideas in progress at any given time – some of which are ready to go, and others which are not. Branching exists to help you manage this workflow.</p>

    <p>When you create a branch in your project, you're creating an environment where you can try out new ideas. Changes you make on a branch don't affect the <code>master</code> branch, so you're free to experiment and commit changes, safe in the knowledge that your branch won't be merged until it's ready to be reviewed by someone you're collaborating with.</p>

    <h4>ProTip</h4>

    <p>Branching is a core concept in Git, and the entire GitHub flow is based upon it. There's only one rule: anything in the <code>master</code> branch is always deployable.</p>

    <p>Because of this, it's extremely important that your new branch is created off of master when working on a feature or a fix. Your branch name should be descriptive (e.g., <code>refactor-authentication</code>, <code>user-content-cache-key</code>, <code>make-retina-avatars</code>), so that others can see what is being worked on.</p>

  </div>

  <div class="panel-content js-panel-content js-panel-content-commits" data-step="commits">
    <h3>Add commits</h3>

    <p>Once your branch has been created, it's time to start making changes. Whenever you add, edit, or delete a file, you're making a commit, and adding them to your branch. This process of adding commits keeps track of your progress as you work on a feature branch.</p>

    <p>Commits also create a transparent history of your work that others can follow to understand what you've done and why. Each commit has an associated commit message, which is a description explaining why a particular change was made. Furthermore, each commit is considered a separate unit of change. This lets you roll back changes if a bug is found, or if you decide to head in a different direction.</p>

    <h4>ProTip</h4>

    <p>Commit messages are important, especially since Git tracks your changes and then displays them as commits once they're pushed to the server. By writing clear commit messages, you can make it easier for other people to follow along and provide feedback.</p>

  </div>

  <div class="panel-content js-panel-content js-panel-content-pr" data-step="pr">
    <h3>Open a Pull Request</h3>

    <p>Pull Requests initiate discussion about your commits. Because they're tightly integrated with the underlying Git repository, anyone can see exactly what changes would be merged if they accept your request.</p>

    <p>You can open a Pull Request at any point during the development process: when you have little or no code but want to share some screenshots or general ideas, when you're stuck and need help or advice, or when you're ready for someone to review your work. By using GitHub's @mention system in your Pull Request message, you can ask for feedback from specific people or teams, whether they're down the hall or ten time zones away.</p>

    <h4>ProTip</h4>

    <p>Pull Requests are useful for contributing to open source projects and for managing changes to shared repositories. If you're using a Fork &amp; Pull Model, Pull Requests provide a way to notify project maintainers about the changes you'd like them to consider. If you're using a Shared Repository Model, Pull Requests help start code review and conversation about proposed changes before they're merged into the master branch.</p>

  </div>

  <div class="panel-content js-panel-content js-panel-content-code-review" data-step="code-review">

    <h3>Discuss and review your code</h3>

    <p>Once a Pull Request has been opened, the person or team reviewing your changes may have questions or comments. Perhaps the coding style doesn't match project guidelines, the change is missing unit tests, or maybe everything looks great and props are in order. Pull Requests are designed to encourage and capture this type of conversation.</p>

    <p>You can also continue to push to your branch in light of discussion and feedback about your commits. If someone comments that you forgot to do something or if there is a bug in the code, you can fix it in your branch and push up the change. GitHub will show your new commits and any additional feedback you may receive in the unified Pull Request view.</p>

    <h4>ProTip</h4>

    <p>Pull Request comments are written in Markdown, so you can embed images and emoji, use pre-formatted text blocks, and other lightweight formatting.</p>

  </div>

  <div class="panel-content js-panel-content js-panel-content-deploy" data-step="deploy">

    <h3>Deploy</h3>

    <p>With GitHub, you can deploy from a branch for final testing in production before merging to master.</p>

    <p>Once your pull request has been reviewed and the branch passes your tests, you can deploy your changes to verify them in production. If your branch causes issues, you can roll it back by deploying the existing master into production.</p>
  </div>

  <div class="panel-content js-panel-content js-panel-content-merge" data-step="merge">

    <h3>Merge</h3>

    <p>Now that your changes have been verified in production, it is time to merge your code into the master branch.</p>

    <p>Once merged, Pull Requests preserve a record of the historical changes to your code. Because they're searchable, they let anyone go back in time to understand why and how a decision was made.</p>

    <h4>ProTip</h4>

    <p>By incorporating certain keywords into the text of your Pull Request, you can associate issues with code. When your Pull Request is merged, the related issues are also closed. For example, entering the phrase <code>Closes #32</code> would close issue number 32 in the repository. For more information, check out our <a href="https://help.github.com/articles/closing-issues-via-commit-messages">help article</a>.</p>

  </div>

  <a href="#" class="panel-nav prev js-panel-nav-prev" title="Previous" data-proofer-ignore="">
    <span class="mega-octicon octicon-chevron-left"></span>
  </a>

  <a href="#" class="panel-nav next js-panel-nav-next" title="Next" data-proofer-ignore="">
    <span class="mega-octicon octicon-chevron-right"></span>
  </a>


</div>
</description></item></channel></rss>