GitHub Guideshttps://guides.github.com/
Tue, 19 Feb 2019 08:42:46 +0000Tue, 19 Feb 2019 08:42:46 +0000en-USGitHub GuidesLearn how to do more with GitHub.Documenting your projects on GitHubhttp://guides.github.com/features/wikis/
Fri, 15 Jul 2016 00:00:00 +0000http://guides.github.com/features/wikis/index.md<p><a id="intro" title="Intro" class="toc-item"></a>
Good documentation is key to the success of any project. Making documentation accessible enables people to learn about a project; making it easy to update ensures that documentation stays relevant.</p>
<p>Two common ways to document a project are <em>README files</em> and <em>wikis</em>:</p>
<ul>
<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>
</ul>
<p>It’s a good idea to at least have a README on your project, because it’s the first thing many people will read when they first find your work.</p>
<p><a id="creating-a-readme" title="Creating your README" class="toc-item"></a></p>
<h2>Creating your README</h2>
<p>When you <a href="https://help.github.com/articles/creating-a-new-repository/">create a new repository</a> though GitHub, select “Initialize this repository with a README” unless you plan to import an existing repository.
<img src="https://cloud.githubusercontent.com/assets/4122993/16925080/64863a10-4cd7-11e6-8da7-b31a29b769f2.png" alt="Screenshot of initializing a README" /></p>
<p>Your README.md file is now available for editing in your brand-new repository. Your project’s name is at the top, followed by any description you chose to include when creating the repository. READMEs are easy to modify, both <a href="https://help.github.com/articles/editing-files-in-your-repository/">on GitHub</a> or locally. Check out the <a href="http://guides.github.com/features/mastering-markdown/">Mastering Markdown guide</a> to learn more about how to modify the text within the file after you’ve made it.</p>
<p><a id="Formatting-a-readme" title="Formatting your README" class="toc-item"></a></p>
<h2>Formatting your README</h2>
<p>READMEs generally follow one format in order to immediately orient developers to the most important aspects of your project.</p>
<ul>
<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>
</ul>
<p>Your README should contain only the necessary information for developers to get started using and contributing to your project. Longer documentation is best suited for wikis, outlined below.</p>
<p><a id="creating-your-wiki" title="Creating your wiki" class="toc-item"></a></p>
<h2>Creating your wiki</h2>
<p>Every repository on GitHub comes with a wiki. After you’ve created a repository, you can set up the included wiki through the sidebar navigation. Starting your wiki is simply a matter of clicking the wiki button and creating your first page.</p>
<p><img src="/features/wikis/wiki-blank-slate.png" alt="Screenshot of the starting page" /></p>
<p><a id="adding-content" title="Adding content" class="toc-item"></a></p>
<h2>Adding content</h2>
<p>Wiki content is designed to be easily editable. You can add or change content on any wiki page by clicking the <strong>Edit</strong> button located in the upper right corner of each page. This opens up the wiki editor.</p>
<p><img src="/features/wikis/wiki-editor.png" alt="Screenshot of the wiki editor" /></p>
<p>Wiki pages can be written in any format supported by <a href="http://github.com/github/markup">GitHub Markup</a>. Using the drop-down menu in the editor, you can select the format of your wiki, and then use wiki toolbar to create and include content on a page. Wikis also give you the option of including a custom footer where you can list things like contact details or license information for your project.</p>
<p>GitHub keeps track of changes made to each page in your wiki. Below a page title, you can see who made the most recent edits, in addition to the number of commits made to the page. Clicking on this information will take you to the full page history where you can compare revisions or see a detailed list of edits over time.</p>
<p><a id="adding-pages" title="Adding pages" class="toc-item"></a></p>
<h2>Adding pages</h2>
<p>You can add additional pages to your wiki by selecting <strong>New Page</strong> in the upper right corner. By default, each page you create is included automatically in your wiki’s sidebar and listed in alphabetical order.</p>
<p><img src="/features/wikis/wiki-sidebar-closeup.png" alt="Screenshot of the wiki sidebar" /></p>
<p>You can also add a custom sidebar to your wiki by clicking the <strong>Add custom sidebar</strong> link. Custom sidebar content can include text, images, and links.</p>
<p>Note: The page called “Home” functions as the entrance page to your wiki. If it is missing, an automatically generated table of contents will be shown instead.</p>
<div class="alert">
<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>
</div>
<p><a id="syntax-highlighting" title="Syntax highlighting" class="toc-item"></a></p>
<h2>Syntax highlighting</h2>
<p>Wiki pages support automatic syntax highlighting of code for a wide range of languages by using the following syntax:</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>```ruby
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>
Mastering Issueshttp://guides.github.com/features/issues/
Mon, 07 Apr 2014 00:00:00 +0000http://guides.github.com/features/issues/index.md<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="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="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="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>
Mastering Markdownhttp://guides.github.com/features/mastering-markdown/
Wed, 15 Jan 2014 00:00:00 +0000http://guides.github.com/features/mastering-markdown/index.md<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="highlighter-rouge">#</code> or <code class="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="highlighter-rouge">.md</code> or <code class="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:
```
if (isAwesome){
return true
}
```
And if you'd like to use syntax highlighting, include the language:
```javascript
if (isAwesome){
return true
}
```
</pre>
<div class="rendered">
<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>
<pre><code>if (isAwesome){
return true
}
</code></pre>
<p>GitHub also supports something called code fencing, which allows for multiple lines without indentation:</p>
<pre><code>if (isAwesome){
return true
}
</code></pre>
<p>And if you&rsquo;d like to use syntax highlighting, include the language:</p>
<div class="highlight highlight-javascript"><pre><span class="k">if</span> <span class="p">(</span><span class="nx">isAwesome</span><span class="p">){</span>
<span class="k">return</span> <span class="kc">true</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="markdown-example" id="example-extras" style="display:none">
<pre class="source">
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 @kneath — love your sweater!
But I have to admit, tasks lists are my favorite:
- [x] This is a complete item
- [ ] This is an incomplete item
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!
And, of course emoji!
</pre>
<div class="rendered">
<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>
</div>
</div>
<p><a id="syntax" title="Basic syntax" class="toc-item"></a></p>
<h2>Syntax guide</h2>
<p>Here’s an overview of Markdown syntax that you can use anywhere on GitHub.com or in your own text files.</p>
<h3>Headers</h3>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gh"># This is an &lt;h1&gt; tag</span>
<span class="gu">## This is an &lt;h2&gt; tag</span>
<span class="gu">###### This is an &lt;h6&gt; tag</span>
</code></pre></div></div>
<h3>Emphasis</h3>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="ge">*This text will be italic*</span>
<span class="ge">_This will also be italic_</span>
<span class="gs">**This text will be bold**</span>
<span class="gs">__This will also be bold__</span>
<span class="ge">_You **can** combine them_</span>
</code></pre></div></div>
<h3>Lists</h3>
<h4>Unordered</h4>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">*</span> Item 1
<span class="p">*</span> Item 2
<span class="p"> *</span> Item 2a
<span class="p"> *</span> Item 2b
</code></pre></div></div>
<h4>Ordered</h4>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">1.</span> Item 1
<span class="p">1.</span> Item 2
<span class="p">1.</span> Item 3
<span class="p"> 1.</span> Item 3a
<span class="p"> 1.</span> Item 3b
</code></pre></div></div>
<h3>Images</h3>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">![</span><span class="nv">GitHub Logo</span><span class="p">](</span><span class="sx">/images/logo.png</span><span class="p">)</span>
Format: !<span class="p">[</span><span class="nv">Alt Text</span><span class="p">](</span><span class="sx">url</span><span class="p">)</span>
</code></pre></div></div>
<h3>Links</h3>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>http://github.com - automatic!
<span class="p">[</span><span class="nv">GitHub</span><span class="p">](</span><span class="sx">http://github.com</span><span class="p">)</span>
</code></pre></div></div>
<h3>Blockquotes</h3>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>As Kanye West said:
<span class="gt">
&gt; We're living the future so</span>
<span class="gt">&gt; the present is our past.</span>
</code></pre></div></div>
<h3>Inline code</h3>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>I think you should use an
`&lt;addr&gt;` element here instead.
</code></pre></div></div>
<p><a id="GitHub-flavored-markdown" title="GFM" class="toc-item"></a></p>
<h2>GitHub Flavored Markdown</h2>
<p>GitHub.com uses its own version of the Markdown syntax that provides an additional set of useful features, many of which make it easier to work with content on GitHub.com.</p>
<p>Note that some features of GitHub Flavored Markdown are only available in the descriptions and comments of Issues and Pull Requests. These include @mentions as well as references to SHA-1 hashes, Issues, and Pull Requests. Task Lists are also available in Gist comments and in Gist Markdown files.</p>
<h3>Syntax highlighting</h3>
<p>Here’s an example of how you can use syntax highlighting with <a href="https://help.github.com/articles/basic-writing-and-formatting-syntax/">GitHub Flavored Markdown</a>:</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>```javascript
function fancyAlert(arg) {
if(arg) {
$.facebox({div:'#foo'})
}
}
```
</code></pre></div></div>
<p>You can also simply indent your code by four spaces:</p>
<div class="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="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="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="highlighter-rouge">-</code> (for the first row), and then separating each column with a pipe <code class="highlighter-rouge">|</code>:</p>
<div class="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="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="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="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="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="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>
Getting Started with GitHub Pageshttp://guides.github.com/features/pages/
Sun, 01 Dec 2013 00:00:00 +0000http://guides.github.com/features/pages/index.md<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="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="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="highlighter-rouge">master</code>.</p>
<p>View the <code class="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>
Hello Worldhttp://guides.github.com/activities/hello-world/
Thu, 07 Apr 2016 00:00:00 +0000http://guides.github.com/activities/hello-world/index.md<p><a id="intro" title="Intro" class="toc-item"></a></p>
<p>The <strong>Hello World</strong> project is a time-honored tradition in computer programming. It is a simple exercise that gets you started when learning something new. Let’s get started with GitHub!</p>
<p><strong>You’ll learn how to:</strong></p>
<ul>
<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>
</ul>
<p><a id="what" title="What is GitHub?" class="toc-item"></a></p>
<h2>What is GitHub?</h2>
<p>GitHub is a code hosting platform for version control and collaboration. It lets you and others work together on projects from anywhere.</p>
<p>This tutorial teaches you GitHub essentials like <em>repositories</em>, <em>branches</em>, <em>commits</em>, and <em>Pull Requests</em>. You’ll create your own Hello World repository and learn GitHub’s Pull Request workflow, a popular way to create and review code.</p>
<h4>No coding necessary</h4>
<p>To complete this tutorial, you need a <a href="http://github.com">GitHub.com account</a> and Internet access. You don’t need to know how to code, use the command line, or install Git (the version control software GitHub is built on).</p>
<blockquote>
<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>
</blockquote>
<p><a id="repository" title="Create a Repository" class="toc-item"></a></p>
<h2>Step 1. Create a Repository</h2>
<p>A <strong>repository</strong> is usually used to organize a single project. Repositories can contain folders and files, images, videos, spreadsheets, and data sets – anything your project needs. We recommend including a <em>README</em>, or a file with information about your project. GitHub makes it easy to add one at the same time you create your new repository. <em>It also offers other common options such as a license file.</em></p>
<p>Your <code class="highlighter-rouge">hello-world</code> repository can be a place where you store ideas, resources, or even share and discuss things with others.</p>
<h3>To create a new repository</h3>
<ol>
<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="highlighter-rouge">hello-world</code>.</li>
<li>Write a short description.</li>
<li>Select <strong>Initialize this repository with a README</strong>.</li>
</ol>
<p><img src="/activities/hello-world/create-new-repo.png" alt="new-repo-form" /></p>
<p>Click <strong>Create repository</strong>.</p>
<p><a id="branch" title="Create a Branch" class="toc-item"></a></p>
<h2>Step 2. Create a Branch</h2>
<p><strong>Branching</strong> is the way to work on different versions of a repository at one time.</p>
<p>By default your repository has one branch named <code class="highlighter-rouge">master</code> which is considered to be the definitive branch. We use branches to experiment and make edits before committing them to <code class="highlighter-rouge">master</code>.</p>
<p>When you create a branch off the <code class="highlighter-rouge">master</code> branch, you’re making a copy, or snapshot, of <code class="highlighter-rouge">master</code> as it was at that point in time. If someone else made changes to the <code class="highlighter-rouge">master</code> branch while you were working on your branch, you could pull in those updates.</p>
<p>This diagram shows:</p>
<ul>
<li>The <code class="highlighter-rouge">master</code> branch</li>
<li>A new branch called <code class="highlighter-rouge">feature</code> (because we’re doing ‘feature work’ on this branch)</li>
<li>The journey that <code class="highlighter-rouge">feature</code> takes before it’s merged into <code class="highlighter-rouge">master</code></li>
</ul>
<p><img src="/activities/hello-world/branching.png" alt="a branch" /></p>
<p>Have you ever saved different versions of a file? Something like:</p>
<ul>
<li><code class="highlighter-rouge">story.txt</code></li>
<li><code class="highlighter-rouge">story-joe-edit.txt</code></li>
<li><code class="highlighter-rouge">story-joe-edit-reviewed.txt</code></li>
</ul>
<p>Branches accomplish similar goals in GitHub repositories.</p>
<p>Here at GitHub, our developers, writers, and designers use branches for keeping bug fixes and feature work separate from our <code class="highlighter-rouge">master</code> (production) branch. When a change is ready, they merge their branch into <code class="highlighter-rouge">master</code>.</p>
<h3>To create a new branch</h3>
<ol>
<li>Go to your new repository <code class="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="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>
</ol>
<p><img src="/activities/hello-world/readme-edits.gif" alt="branch gif" /></p>
<p>Now you have two branches, <code class="highlighter-rouge">master</code> and <code class="highlighter-rouge">readme-edits</code>. They look exactly the same, but not for long! Next we’ll add our changes to the new branch.</p>
<p><a id="commit" title="Make a Commit" class="toc-item"></a></p>
<h2>Step 3. Make and commit changes</h2>
<p>Bravo! Now, you’re on the code view for your <code class="highlighter-rouge">readme-edits</code> branch, which is a copy of <code class="highlighter-rouge">master</code>. Let’s make some edits.</p>
<p>On GitHub, saved changes are called <em>commits</em>. Each commit has an associated <em>commit message</em>, which is a description explaining why a particular change was made. Commit messages capture the history of your changes, so other contributors can understand what you’ve done and why.</p>
<h4>Make and commit changes</h4>
<ol>
<li>Click the <code class="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>
</ol>
<p><img src="/activities/hello-world/commit.png" alt="commit" /></p>
<p>These changes will be made to just the README file on your <code class="highlighter-rouge">readme-edits</code> branch, so now this branch contains content that’s different from <code class="highlighter-rouge">master</code>.</p>
<p><a id="pr" title="Open a Pull Request" class="toc-item"></a></p>
<h2>Step 4. Open a Pull Request</h2>
<p>Nice edits! Now that you have changes in a branch off of <code class="highlighter-rouge">master</code>, you can open a <em>pull request</em>.</p>
<p>Pull Requests are the heart of collaboration on GitHub. When you open a <em>pull request</em>, you’re proposing your changes and requesting that someone review and pull in your contribution and merge them into their branch. Pull requests show <em>diffs</em>, or differences, of the content from both branches. The changes, additions, and subtractions are shown in green and red.</p>
<p>As soon as you make a commit, you can open a pull request and start a discussion, even before the code is finished.</p>
<p>By using GitHub’s <a href="https://help.github.com/articles/about-writing-and-formatting-on-github/#text-formatting-toolbar">@mention system</a> in your pull request message, you can ask for feedback from specific people or teams, whether they’re down the hall or 10 time zones away.</p>
<p>You can even open pull requests in your own repository and merge them yourself. It’s a great way to learn the GitHub flow before working on larger projects.</p>
<h4>Open a Pull Request for changes to the README</h4>
<p><em>Click on the image for a larger version</em></p>
<table>
<thead>
<tr>
<th>Step</th>
<th>Screenshot</th>
</tr>
</thead>
<tbody>
<tr>
<td>Click the <span class="octicon octicon-git-pull-request"></span> <strong>Pull Request</strong> tab, then from the Pull Request page, click the green <strong>New pull request</strong> button.</td>
<td><a href="pr-tab.gif"><img src="/activities/hello-world/pr-tab.gif" alt="pr-tab" /></a></td>
</tr>
<tr>
<td>In the <strong>Example Comparisons</strong> box, select the branch you made, <code class="highlighter-rouge">readme-edits</code>, to compare with <code class="highlighter-rouge">master</code> (the original).</td>
<td><a href="pick-branch.png"><img src="/activities/hello-world/pick-branch.png" alt="branch" /></a></td>
</tr>
<tr>
<td>Look over your changes in the diffs on the Compare page, make sure they’re what you want to submit.</td>
<td><a href="diff.png"><img src="/activities/hello-world/diff.png" alt="diff" /></a></td>
</tr>
<tr>
<td>When you’re satisfied that these are the changes you want to submit, click the big green <strong>Create Pull Request</strong> button.</td>
<td><a href="create-pr.png"><img src="/activities/hello-world/create-pr.png" alt="create-pull" /></a></td>
</tr>
<tr>
<td>Give your pull request a title and write a brief description of your changes.</td>
<td><a href="pr-form.png"><img src="/activities/hello-world/pr-form.png" alt="pr-form" /></a></td>
</tr>
</tbody>
</table>
<p>When you’re done with your message, click <strong>Create pull request</strong>!</p>
<hr />
<blockquote>
<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>
</blockquote>
<p><a id="merge" title="Merge Pull Request" class="toc-item"></a></p>
<h2>Step 5. Merge your Pull Request</h2>
<p>In this final step, it’s time to bring your changes together – merging your <code class="highlighter-rouge">readme-edits</code> branch into the <code class="highlighter-rouge">master</code> branch.</p>
<ol>
<li>Click the green <strong>Merge pull request</strong> button to merge the changes into <code class="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>
</ol>
<p><img src="/activities/hello-world/merge-button.png" alt="merge" />
<img src="/activities/hello-world/delete-button.png" alt="delete" /></p>
<h3>Celebrate!</h3>
<p>By completing this tutorial, you’ve learned to create a project and make a pull request on GitHub!</p>
<p>Here’s what you accomplished in this tutorial:</p>
<ul>
<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>
</ul>
<p>Take a look at your GitHub profile and you’ll see your new <a href="https://help.github.com/articles/viewing-contributions">contribution squares</a>!</p>
<p>To learn more about the power of Pull Requests, we recommend reading the <a href="http://guides.github.com/overviews/flow/">GitHub flow Guide</a>. You might also visit <a href="http://github.com/explore">GitHub Explore</a> and get involved in an Open Source project.</p>
<hr />
<blockquote>
<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>
</blockquote>
Be Socialhttp://guides.github.com/activities/socialize/
Thu, 17 May 2018 00:00:00 +0000http://guides.github.com/activities/socialize/index.md<link rel="stylesheet" type="text/css" href="socialize.css" />
<p><a id="intro" title="Intro" class="toc-item"></a></p>
<p>With more and more people joining GitHub and adding projects every day, keeping up with all of them can be difficult. However, this can be fun and easy by following users or watching repositories, simply showing interest in them by starring, or using Explore to find new people and projects.</p>
<p><a id="follow-a-friend" title="Follow A Friend" class="toc-item"></a></p>
<h2>Follow a Friend</h2>
<p>One of the great features on GitHub is the ability to see what other people are working on and who they are connecting with.
When you follow someone, you’ll get notifications about their GitHub activity. Following friends
helps you find new projects and new people that you may share interests with. You can see what some of your friends are
interested in by looking at your <a href="https://github.com/dashboard">personal dashboard</a> or you can check out what’s going on in the GitHub community by looking at <a href="https://github.com/explore">the Explore page</a>.</p>
<h3>Step 1: Pick a friend.</h3>
<p>Why not follow one of these cool people from GitHub:</p>
<div class="founders">
<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>
</div>
<h3>Step 2: Follow that friend</h3>
<p>Once you are on someone’s profile, click the “follow” button.</p>
<p><img src="https://github-images.s3.amazonaws.com/help/profile/follow-user-button.png" alt="Follow user button" /></p>
<p>Congratulations! You are now following a friend.</p>
<p><a id="watch-a-project" title="Watch A Project" class="toc-item"></a></p>
<h2>Watch a Project’s Repository</h2>
<p>At some point you may want to stay up-to-date with a specific project. This is similar to following a person, except
the focus is narrowed to only events in the project’s repository. You can choose to have notifications for this repository sent via email or viewable on the web by <a href="https://github.com/settings/notifications">configuring your settings</a>. Typical notifications would be comments on a Pull Request or an issue, or just a comment anywhere within the repository.</p>
<p>Our friend the Octocat has a repository called <a href="https://github.com/octocat/Hello-World">Hello World</a> that we’d like to watch.</p>
<p>Once you are on the repository page, you will notice there is a “watch” button at the top of the page. Click on it.</p>
<p><img src="https://github-images.s3.amazonaws.com/help/repository/repo-actions-watch.png" alt="Watch repository button" /></p>
<p>Congratulations! You are now watching the Hello World repository. If the Octocat updates it, you will see what happened in your dashboard or receive a notification.</p>
<p><a id="explore" title="More Things You Can Do" class="toc-item"></a></p>
<h2>More Things You Can Do</h2>
<p>You’ve done some of the most basic social interaction GitHub has to offer, but don’t stop there! Check out these other social features:</p>
<h4>Stargazing</h4>
<p>If you’re interested in some of the repositories your friends have starred in the past, but you no longer see it on your dashboard, head over to your <a href="https://github.com/stars">stars page</a> and jump to another user!</p>
<p><img src="/activities/socialize/jump-to-another-user.png" alt="Jump to another user" /></p>
<h4>Discover Repositories</h4>
<p>After you’ve watched, followed, and starred your favorite people and repositories on GitHub, head over to your <a href="https://github.com/dashboard/discover">Discover Repositories</a> page to see personalized repository recommendations based on these things!</p>
<h4>Explore / Newsletter</h4>
<p>The Explore page has repositories that have been starred by people you follow, GitHub staff, and general trending repositories right on the first page.</p>
<p>If you want to receive these as a newsletter daily, weekly, or monthly, check out the newsletter announcement at the bottom of the Explore page.</p>
<p><img src="/activities/socialize/subscribe-explore.png" alt="Newsletter" /></p>
<p>You can also configure this setting later at <a href="https://github.com/explore/subscribe">the subscription page</a>.</p>
<p>If you want to view just trending repositories and users, <a href="https://github.com/trending">head over to Trending</a> and take a look.</p>
<p><img src="/activities/socialize/trending.png" alt="trending" /></p>
<p><a id="celebrate" title="Celebrate" class="toc-item"></a></p>
<h2>Celebrate</h2>
<p>Congratulations! You are quite the socialite. Check out some of these next steps:</p>
<ul>
<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>
</ul>
Making Your Code Citablehttp://guides.github.com/activities/citable-code/
Sat, 01 Oct 2016 00:00:00 +0000http://guides.github.com/activities/citable-code/index.md<p><a id="intro" title="Intro" class="toc-item"></a></p>
<p><a href="http://en.wikipedia.org/wiki/Digital_object_identifier">Digital Object Identifiers</a> (DOI) are the backbone of the academic reference and metrics system. If you’re a researcher writing software, this guide will show you how to make the work you share on GitHub citable by archiving one of your GitHub repositories and assigning a DOI with the data archiving tool <a href="https://zenodo.org/about">Zenodo</a>.</p>
<blockquote>
<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>
</blockquote>
<p><a id="repository" title="Choosing Your Repo" class="toc-item"></a></p>
<h2>Choose your repository</h2>
<p>Repositories are the most basic element of GitHub. They’re easiest to imagine as your project’s folder. The first step in creating a DOI is to select the repository you want to archive in Zenodo. To do so, head over to your profile and click the <strong>Repositories</strong> tab.</p>
<p><img src="/activities/citable-code/repos.png" alt="login" /></p>
<blockquote>
<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>
</blockquote>
<p><a id="login" title="Login to Zenodo" class="toc-item"></a></p>
<h2>Login to Zenodo</h2>
<p>Next, head over to <a href="http://zenodo.org">Zenodo</a> and click the <strong>Log in</strong> button at the top right of the page, which gives you an option to login with your GitHub account.</p>
<p><img src="/activities/citable-code/zenodo-login.png" alt="login" /></p>
<p>Zenodo will redirect you back to GitHub to ask for your permission to share your email address and the ability to configure <a href="https://developer.github.com/webhooks/">webhooks</a> on your repositories. Go ahead and click <strong>Authorize application</strong> to give Zenodo the permissions it needs.</p>
<blockquote>
<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>
</blockquote>
<p><img src="/activities/citable-code/zenodo-authorize.png" alt="auth" /></p>
<h3>Pick the repository you want to archive</h3>
<p>At this point, you’ve authorized Zenodo to configure the repository webhooks needed to allow for archiving and DOI-issuing. To enable this functionality, simply click the <strong>On</strong> toggle button next to your repository (in this case <strong>My-Awesome-Science-Software</strong>).</p>
<blockquote>
<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>
</blockquote>
<p><img src="/activities/citable-code/zenodo-toggle-on.png" alt="toggle" /></p>
<p><a id="check" title="Check Repo Settings" class="toc-item"></a></p>
<h2>Check repository settings</h2>
<p>By enabling archiving in Zenodo, you have set up a new webhook on your repository. Click the settings tab on your repository, and then click ‘Webhooks’ in the left-hand menu. You should see something like the image below, which shows a new webhook configured to send messages to Zenodo.</p>
<p><img src="/activities/citable-code/webhook-view.png" alt="webhooks" /></p>
<p><a id="create" title="Create a New Release" class="toc-item"></a></p>
<h2>Create a new release</h2>
<p>By default, Zenodo takes an archive of your GitHub repository each time you create a new <a href="https://help.github.com/articles/about-releases">Release</a>. To test this out, head back to the main repository view and click on the <strong>releases</strong> header item.</p>
<p><img src="/activities/citable-code/repo-view.png" alt="repo" /></p>
<p>Unless you’ve created releases for this repository before, you will be asked to <strong>Create a new release</strong>. Go ahead and click this button and fill in the new release form.</p>
<p><img src="/activities/citable-code/create-release.png" alt="create-release" /></p>
<p>If this is the first release of your code then you should give it a version number of <code class="highlighter-rouge">v1.0.0</code>. Fill in any release notes and click the <strong>Publish release</strong> button.</p>
<p><img src="/activities/citable-code/first-release.png" alt="first-release" /></p>
<h2>Checking everything has worked</h2>
<p>Creating a new release will trigger Zenodo into archiving your repository. You can confirm that this process took place by click the <strong>Upload</strong> tab in your Zenodo profile. You should see a new upload in the right-hand panel.</p>
<p><img src="/activities/citable-code/upload-tab.png" alt="uploads" /></p>
<p><a id="finishing" title="Minting a DOI" class="toc-item"></a></p>
<h2>Minting a DOI</h2>
<p>Before Zenodo can issue a DOI for your repository, you will need to provide some information about the GitHub repo that you’ve just archived.</p>
<p>Once you’re happy with the description of your software, click the <strong>Publish</strong> button at the bottom of the Zenodo form, and voilà, you’ve just made a new DOI for your GitHub repository!</p>
<p><img src="/activities/citable-code/zenodo-form.png" alt="form" /></p>
<p><a id="finishing-up" title="Finishing up" class="toc-item"></a></p>
<h2>Finishing up</h2>
<p>Back on your <a href="https://zenodo.org/account/settings/github" data-proofer-ignore="">Zenodo GitHub page</a> you should now see your repository listed with a shiny new badge showing your new DOI!</p>
<blockquote>
<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>
</blockquote>
<p><img src="/activities/citable-code/releases-present.png" alt="releases-present" /></p>
Forking Projectshttp://guides.github.com/activities/forking/
Thu, 30 Nov 2017 00:00:00 +0000http://guides.github.com/activities/forking/index.md<p><a id="contributing" title="Contributing to a project" class="toc-item"></a>
After using GitHub by yourself for a while, you may find yourself wanting to contribute to someone else’s project. Or maybe you’d like to use someone’s project as the starting point for your own. This process is known as <em>forking.</em></p>
<p>Creating a “fork” is producing a personal copy of someone else’s project. Forks act as a sort of bridge between the original repository and your personal copy. You can submit <em>Pull Requests</em> to help make other people’s projects better by offering your changes up to the original project. Forking is at the core of social coding at GitHub.</p>
<p>For this tutorial, we’ll be using <a href="https://github.com/octocat/Spoon-Knife">the Spoon-Knife project</a>, a test repository that’s hosted on GitHub.com that lets you test the Pull Request workflow.</p>
<p><a id="fork" title="Fork the repository" class="toc-item"></a></p>
<h2>Fork the repository</h2>
<p>To fork the Spoon-Knife repository, click the <strong>Fork</strong> button in the header of the repository.</p>
<p><img src="https://github-images.s3.amazonaws.com/help/bootcamp/Bootcamp-Fork.png" alt="A repository's fork button" /></p>
<p>Sit back and watch the forking magic. When it’s finished, you’ll be taken to your copy of the Spoon-Knife repository.</p>
<p><a id="clone" title="Clone your fork" class="toc-item"></a></p>
<h2>Clone your fork</h2>
<p>You’ve successfully forked the Spoon-Knife repository, but so far, it only exists on GitHub. To be able to work on the project, you will need to clone it to your computer.</p>
<p>If you’re using <a href="https://desktop.github.com/">GitHub Desktop</a>, this process is a breeze. On your fork of Spoon-Knife, navigate over to the right hand side bar and click <strong>Clone or Download</strong>. How you clone is up to you. Some options are <a href="https://services.github.com/on-demand/github-cli/clone-repo-cli">cloning with the command line</a>, or by <a href="https://services.github.com/on-demand/github-desktop/clone-repository-github-desktop">using GitHub Desktop</a>.</p>
<p><a id="making-changes" title="Making and pushing changes" class="toc-item"></a></p>
<h2>Making and pushing changes</h2>
<p>Go ahead and make a few changes to the project using your favorite text editor, like <a href="https://atom.io">Atom</a>. You could, for example, change the text in <em>index.html</em> to add your GitHub username.</p>
<p>When you’re ready to submit your changes, <strong>stage</strong> and <strong>commit</strong> your changes.</p>
<blockquote>
<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>
</blockquote>
<p>Right now, you’ve essentially told Git, “Okay, I’ve taken a snapshot of my changes!” You can continue to make more changes, and take more commit snapshots. When you’re ready to push your changes up to GitHub.com, push your changes to the remote.</p>
<p><a id="making-a-pull-request" title="Making a Pull Request" class="toc-item"></a></p>
<h2>Making a Pull Request</h2>
<p>At last, you’re ready to propose changes into the main project! This is the final step in producing a fork of someone else’s project, and arguably the most important. If you’ve made a change that you feel would benefit the community as a whole, you should definitely consider contributing back.</p>
<p>To do so, head on over to the repository on GitHub.com where your project lives. For this example, it would be at <code class="highlighter-rouge">https://www.github.com/&lt;your_username&gt;/Spoon-Knife</code>. You’ll see a banner indicating that you’ve recently pushed a new branch, and that you can submit this branch “upstream,” to the original repository:</p>
<p><img src="https://github-images.s3.amazonaws.com/help/pull_requests/recently_pushed_branch.png" alt="Recently pushed branch banner" /></p>
<p>Clicking on <strong>Compare and Pull Request</strong> sends you to a discussion page, where you can enter a title and optional description. It’s important to provide as much useful information and a rationale for <em>why</em> you’re making this Pull Request in the first place. The project owner needs to be able to determine whether your change is as useful to everyone as you think it is.</p>
<p>When you’re ready typing out your heartfelt argument, click on <strong>Send pull request</strong>. You’re done!</p>
<p><img src="https://github-images.s3.amazonaws.com/help/pull_requests/pullrequest-send.png" alt="Send Pull Request button" /></p>
<p>Pull Requests are an area for discussion. In this case, the Octocat is very busy, and probably won’t merge your changes. For other projects, don’t be offended if the project owner rejects your Pull Request, or asks for more information on why it’s been made. It may even be that the project owner chooses not to merge your pull request, and that’s totally okay. Your copy will exist in infamy on the Internet. And who knows–maybe someone you’ve never met will find your changes much more valuable than the original project. Share and share alike!</p>
<p><a id="huzzah" title="Huzzah!" class="toc-item"></a></p>
<h2>Huzzah!</h2>
<p>You’ve successfully forked and contributed back to a repository. Go forth, and
contribute some more!</p>
Git Handbookhttp://guides.github.com/introduction/git-handbook/
Mon, 25 Sep 2017 00:00:00 +0000http://guides.github.com/introduction/git-handbook/index.md<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="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="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="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="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="highlighter-rouge">git add</code> will become a part of the snapshot with <code class="highlighter-rouge">git commit</code>.</p>
</li>
<li>
<p><code class="highlighter-rouge">git status</code> shows the status of changes as untracked, modified, or staged.</p>
</li>
<li>
<p><code class="highlighter-rouge">git branch</code> shows the branches being worked on locally.</p>
</li>
<li>
<p><code class="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="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="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="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="highlighter-rouge">git pull</code> and <code class="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="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>
touch 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>
Understanding the GitHub flowhttp://guides.github.com/introduction/flow/
Thu, 30 Nov 2017 00:00:00 +0000http://guides.github.com/introduction/flow/index.md<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>