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 forking.
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 Pull Requests 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.
For this tutorial, we’ll be using the Spoon-Knife project, a test repository that’s hosted on GitHub.com that lets you test the Pull Request workflow.
To fork the Spoon-Knife repository, click the Fork button in the header of the repository.
Sit back and watch the forking magic. When it’s finished, you’ll be taken to your copy of the Spoon-Knife repository.
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.
If you’re using GitHub Desktop, this process is a breeze. On your fork of Spoon-Knife, navigate over to the right hand side bar and click Clone or Download. How you clone is up to you. Some options are cloning with the command line, or by using GitHub Desktop.
Go ahead and make a few changes to the project using your favorite text editor, like Atom. You could, for example, change the text in index.html to add your GitHub username.
When you’re ready to submit your changes, stage and commit your changes.
Is staging and committing changes locally too advanced right now? Check out this on-demand training for interactive tutorials to help you learn more.
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.
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.
To do so, head on over to the repository on GitHub.com where your project lives. For this example, it would be at https://www.github.com/<your_username>/Spoon-Knife. 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:
Clicking on Compare and Pull Request 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 why 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.
When you’re ready typing out your heartfelt argument, click on Send pull request. You’re done!
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!
You’ve successfully forked and contributed back to a repository. Go forth, and contribute some more!
<title>Making Your Code Citable</title> http://guides.github.com/activities/citable-code/ Sat, 01 Oct 2016 00:00:00 +0000 http://guides.github.com/activities/citable-code/index.mdDigital Object Identifiers (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 Zenodo.
ProTip: 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 uploading your work to a repository.
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 Repositories tab.
Important! 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 choosealicense.com.
Next, head over to Zenodo and click the Log in button at the top right of the page, which gives you an option to login with your GitHub account.
Zenodo will redirect you back to GitHub to ask for your permission to share your email address and the ability to configure webhooks on your repositories. Go ahead and click Authorize application to give Zenodo the permissions it needs.
Important! 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 third-party access to the Zenodo application.
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 On toggle button next to your repository (in this case My-Awesome-Science-Software).
Important! Zenodo can only access your public repositories so make sure the repository you want to archive is public.
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.
By default, Zenodo takes an archive of your GitHub repository each time you create a new Release. To test this out, head back to the main repository view and click on the releases header item.
Unless you’ve created releases for this repository before, you will be asked to Create a new release. Go ahead and click this button and fill in the new release form.
If this is the first release of your code then you should give it a version number of v1.0.0. Fill in any release notes and click the Publish release button.
Creating a new release will trigger Zenodo into archiving your repository. You can confirm that this process took place by click the Upload tab in your Zenodo profile. You should see a new upload in the right-hand panel.
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.
Once you’re happy with the description of your software, click the Publish button at the bottom of the Zenodo form, and voilà, you’ve just made a new DOI for your GitHub repository!
Back on your Zenodo GitHub page you should now see your repository listed with a shiny new badge showing your new DOI!
ProTip: 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.
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.
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 personal dashboard or you can check out what’s going on in the GitHub community by looking at the Explore page.
Why not follow one of these cool people from GitHub:
Once you are on someone’s profile, click the “follow” button.
Congratulations! You are now following a friend.
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 configuring your settings. Typical notifications would be comments on a Pull Request or an issue, or just a comment anywhere within the repository.
Our friend the Octocat has a repository called Hello World that we’d like to watch.
Once you are on the repository page, you will notice there is a “watch” button at the top of the page. Click on it.
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.
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:
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 stars page and jump to another user!
After you’ve watched, followed, and starred your favorite people and repositories on GitHub, head over to your Discover Repositories page to see personalized repository recommendations based on these things!
The Explore page has repositories that have been starred by people you follow, GitHub staff, and general trending repositories right on the first page.
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.
You can also configure this setting later at the subscription page.
If you want to view just trending repositories and users, head over to Trending and take a look.
Congratulations! You are quite the socialite. Check out some of these next steps:
<title>Hello World</title> http://guides.github.com/activities/hello-world/ Thu, 07 Apr 2016 00:00:00 +0000 http://guides.github.com/activities/hello-world/index.mdThe Hello World 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!
You’ll learn how to:
- Create and use a repository
- Start and manage a new branch
- Make changes to a file and push them to GitHub as commits
- Open and merge a pull request
GitHub is a code hosting platform for version control and collaboration. It lets you and others work together on projects from anywhere.
This tutorial teaches you GitHub essentials like repositories, branches, commits, and Pull Requests. You’ll create your own Hello World repository and learn GitHub’s Pull Request workflow, a popular way to create and review code.
To complete this tutorial, you need a GitHub.com account 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).
Tip: Open this guide in a separate browser window (or tab) so you can see it while you complete the steps in the tutorial.
A repository 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 README, or a file with information about your project. GitHub makes it easy to add one at the same time you create your new repository. It also offers other common options such as a license file.
Your hello-world repository can be a place where you store ideas, resources, or even share and discuss things with others.
- In the upper right corner, next to your avatar or identicon, click and then select New repository.
- Name your repository
hello-world. - Write a short description.
- Select Initialize this repository with a README.
Click Create repository.
Branching is the way to work on different versions of a repository at one time.
By default your repository has one branch named master which is considered to be the definitive branch. We use branches to experiment and make edits before committing them to master.
When you create a branch off the master branch, you’re making a copy, or snapshot, of master as it was at that point in time. If someone else made changes to the master branch while you were working on your branch, you could pull in those updates.
This diagram shows:
- The
masterbranch - A new branch called
feature(because we’re doing ‘feature work’ on this branch) - The journey that
featuretakes before it’s merged intomaster
Have you ever saved different versions of a file? Something like:
story.txtstory-joe-edit.txtstory-joe-edit-reviewed.txt
Branches accomplish similar goals in GitHub repositories.
Here at GitHub, our developers, writers, and designers use branches for keeping bug fixes and feature work separate from our master (production) branch. When a change is ready, they merge their branch into master.
- Go to your new repository
hello-world. - Click the drop down at the top of the file list that says branch: master.
- Type a branch name,
readme-edits, into the new branch text box. - Select the blue Create branch box or hit “Enter” on your keyboard.
Now you have two branches, master and readme-edits. They look exactly the same, but not for long! Next we’ll add our changes to the new branch.
Bravo! Now, you’re on the code view for your readme-edits branch, which is a copy of master. Let’s make some edits.
On GitHub, saved changes are called commits. Each commit has an associated commit message, 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.
- Click the
README.mdfile. - Click the pencil icon in the upper right corner of the file view to edit.
- In the editor, write a bit about yourself.
- Write a commit message that describes your changes.
- Click Commit changes button.
These changes will be made to just the README file on your readme-edits branch, so now this branch contains content that’s different from master.
Nice edits! Now that you have changes in a branch off of master, you can open a pull request.
Pull Requests are the heart of collaboration on GitHub. When you open a pull request, you’re proposing your changes and requesting that someone review and pull in your contribution and merge them into their branch. Pull requests show diffs, or differences, of the content from both branches. The changes, additions, and subtractions are shown in green and red.
As soon as you make a commit, you can open a pull request and start a discussion, even before the code is finished.
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 10 time zones away.
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.
Click on the image for a larger version
| Step | Screenshot |
|---|---|
| Click the Pull Request tab, then from the Pull Request page, click the green New pull request button. |  |
In the Example Comparisons box, select the branch you made, readme-edits, to compare with master (the original). |  |
| Look over your changes in the diffs on the Compare page, make sure they’re what you want to submit. |  |
| When you’re satisfied that these are the changes you want to submit, click the big green Create Pull Request button. |  |
| Give your pull request a title and write a brief description of your changes. |  |
When you’re done with your message, click Create pull request!
Tip: You can use emoji and drag and drop images and gifs onto comments and Pull Requests.
In this final step, it’s time to bring your changes together – merging your readme-edits branch into the master branch.
- Click the green Merge pull request button to merge the changes into
master. - Click Confirm merge.
- Go ahead and delete the branch, since its changes have been incorporated, with the Delete branch button in the purple box.
By completing this tutorial, you’ve learned to create a project and make a pull request on GitHub!
Here’s what you accomplished in this tutorial:
- Created an open source repository
- Started and managed a new branch
- Changed a file and committed those changes to GitHub
- Opened and merged a Pull Request
Take a look at your GitHub profile and you’ll see your new contribution squares!
To learn more about the power of Pull Requests, we recommend reading the GitHub flow Guide. You might also visit GitHub Explore and get involved in an Open Source project.
<title>Documenting your projects on GitHub</title> http://guides.github.com/features/wikis/ Fri, 15 Jul 2016 00:00:00 +0000 http://guides.github.com/features/wikis/index.mdTip: Check out our other Guides, YouTube Channel and On-Demand Training for more on how to get started with GitHub.
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.
Two common ways to document a project are README files and wikis:
-
README files are a quick and simple way for other users to learn more about your work.
-
Wikis on GitHub help you present in-depth information about your project in a useful way.
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.
When you create a new repository though GitHub, select “Initialize this repository with a README” unless you plan to import an existing repository. 
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 on GitHub or locally. Check out the Mastering Markdown guide to learn more about how to modify the text within the file after you’ve made it.
READMEs generally follow one format in order to immediately orient developers to the most important aspects of your project.
-
Project name: 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.
-
Description: 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.
-
Table of Contents: Optionally, include a table of contents in order to allow other people to quickly navigate especially long or detailed READMEs.
-
Installation: 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.
-
Usage: 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.
-
Contributing: 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 setting guidelines for repository contributors.
-
Credits: Include a section for credits in order to highlight and link to the authors of your project.
-
License: Finally, include a section for the license of your project. For more information on choosing a license, check out GitHub’s licensing guide!
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.
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.
Wiki content is designed to be easily editable. You can add or change content on any wiki page by clicking the Edit button located in the upper right corner of each page. This opens up the wiki editor.
Wiki pages can be written in any format supported by GitHub Markup. 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.
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.
You can add additional pages to your wiki by selecting New Page in the upper right corner. By default, each page you create is included automatically in your wiki’s sidebar and listed in alphabetical order.
You can also add a custom sidebar to your wiki by clicking the Add custom sidebar link. Custom sidebar content can include text, images, and links.
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.
If you're knowledgable with the command line, you can also modify wikis locally. Check out our help article for more info.
Wiki pages support automatic syntax highlighting of code for a wide range of languages by using the following syntax:
```ruby def foo puts 'bar' end ``` The block must start with three backticks, optionally followed by the the name of the language that is contained by the block. See Pygments for the list of languages that can be syntax highlighted.
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.
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.
To read more on the topics covered in this article, our guides for creating a new repository, editing files in your repository, setting guidelines for repository contributors and choosing a license are great places to start. Otherwise, check out some other GitHub Guides to keep learning.
Finally, if you’re interested in building a documentation site for your project, we recommend using GitHub Pages.
<title>Mastering Markdown</title> http://guides.github.com/features/mastering-markdown/ Wed, 15 Jan 2014 00:00:00 +0000 http://guides.github.com/features/mastering-markdown/index.mdMarkdown is a lightweight and easy-to-use syntax for styling all forms of writing on the GitHub platform.
What you will learn:
- How the Markdown format makes styled collaborative editing easy
- How Markdown differs from traditional formatting approaches
- How to use Markdown to format text
- How to leverage GitHub’s automatic Markdown rendering
- How to apply GitHub’s unique Markdown extensions
Markdown 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 # or *.
You can use Markdown most places around GitHub:
- Gists
- Comments in Issues and Pull Requests
- Files with the
.mdor.markdownextension
For more information, see “Writing on GitHub” in the GitHub Help.
It's very easy to make some words **bold** and other words *italic* with Markdown. You can even [link to Google!](http://google.com) 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
Sometimes you want numbered lists:
- One
- Two
- 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
If you want to embed images, this is how you do it: 
If you want to embed images, this is how you do it:
# 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 > character before the line: > Coffee. The finest organic suspension ever devised... I beat the Borg with it. > - Captain Janeway
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.
You can use one # all the way up to ###### six for different heading sizes.
If you’d like to quote someone, use the > character before the line:
Coffee. The finest organic suspension ever devised… I beat the Borg with it. - Captain Janeway
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 } ``` 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:
if (isAwesome){ return true }
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!
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:
- 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!
Here’s an overview of Markdown syntax that you can use anywhere on GitHub.com or in your own text files.
# This is an <h1> tag ## This is an <h2> tag ###### This is an <h6> tag *This text will be italic* _This will also be italic_ **This text will be bold** __This will also be bold__ _You **can** combine them_ * Item 1 * Item 2 * Item 2a * Item 2b 1. Item 1 1. Item 2 1. Item 3 1. Item 3a 1. Item 3b  Format:  http://github.com - automatic! [GitHub](http://github.com) As Kanye West said: > We're living the future so > the present is our past. I think you should use an `<addr>` element here instead. 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.
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.
Here’s an example of how you can use syntax highlighting with GitHub Flavored Markdown:
```javascript function fancyAlert(arg) { if(arg) { $.facebox({div:'#foo'}) } } ``` You can also simply indent your code by four spaces:
function fancyAlert(arg) { if(arg) { $.facebox({div:'#foo'}) } } Here’s an example of Python code without syntax highlighting:
def foo(): if not bar: return True - [x] @mentions, #refs, [links](), **formatting**, and <del>tags</del> supported - [x] list syntax required (any unordered or ordered list supported) - [x] this is a complete item - [ ] this is an incomplete item 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!
You can create tables by assembling a list of words and dividing them with hyphens - (for the first row), and then separating each column with a pipe |:
First Header | Second Header ------------ | ------------- Content from cell 1 | Content from cell 2 Content in the first column | Content in the second column Would become:
| First Header | Second Header |
|---|---|
| Content from cell 1 | Content from cell 2 |
| Content in the first column | Content in the second column |
Any reference to a commit’s SHA-1 hash will be automatically converted into a link to that commit on GitHub.
16c999e8c71134401a78d4d46435517b2271d6ac mojombo@16c999e8c71134401a78d4d46435517b2271d6ac mojombo/github-flavored-markdown@16c999e8c71134401a78d4d46435517b2271d6ac Any number that refers to an Issue or Pull Request will be automatically converted into a link.
#1 mojombo#1 mojombo/github-flavored-markdown#1 Typing an @ symbol, followed by a username, will notify that person to come and view the comment. This is called an “@mention”, because you’re mentioning the individual. You can also @mention teams within an organization.
Any URL (like http://www.github.com/) will be automatically converted into a clickable link.
Any word wrapped with two tildes (like ~~this~~) will appear crossed out.
GitHub supports emoji!
To see a list of every image we support, check out the Emoji Cheat Sheet.
<title>Mastering Issues</title> http://guides.github.com/features/issues/ Mon, 07 Apr 2014 00:00:00 +0000 http://guides.github.com/features/issues/index.mdIssues 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 Issues, and has its own section in every repository.
For example, let’s take a look at Bootstrap’s Issues section:
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:
-
A title and description describe what the issue is all about.
-
Color-coded labels help you categorize and filter your issues (just like labels in email).
-
A milestone acts like a container for issues. This is useful for associating issues with specific features or project phases (e.g. Weekly Sprint 9/5-9/16 or Shipping 1.0).
-
One assignee is responsible for working on the issue at any given time.
-
Comments allow anyone with access to the repository to provide feedback.
Once you’ve collected a lot of issues, you may find it hard to find the ones you care about. Milestones, labels, and assignees are great features to filter and categorize issues.
You can change or add a milestone, an assignee, and labels by clicking their corresponding gears in the sidebar on the right.
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.
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:
-
Beta Launch — 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.
-
October Sprint — 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.
-
Redesign — File issues related to redesigning your project. A great way to collect ideas on what to work on.
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.
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.
By using @mentions and references inside of Issues, you can notify other GitHub users & 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 GitHub Flavored Markdown.
If you’d like to learn more, have a look at Mastering Markdown.
Notifications 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.
There are two ways to receive notifications: via email, and via the web. You can configure how you receive notifications in your settings. If you plan on receiving a lot of notifications, we like to recommend that you receive web + email notifications for Participating and web notifications for Watching.
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.
You can access your notifications through the notifications 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 ? on the page to see which shortcuts are available.
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.
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).
@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.
We like to use the /cc syntax (an abbreviation for carbon copy) to include people in issues:
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?
/cc @kneath @jresig
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 browser-bugs under the @acmeinc organization, you can reference the team with @mentions:
/cc @acmeinc/browser-bugs
This will send notifications to every member of the browser-bugs team.
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.
Hey @kneath, I think the problem started in #42
When you do this, we’ll create an event inside of issue #42 that looks something like this:
Issue in another repository? Just include the repository before the name like kneath/example-project#42.
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.
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.
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.
At the very top of each page is a search box that lets you search through issues.
You can scope search results by:
-
Keyword, such as, all issues mentioning the sidebar
-
State, such as, all issues mentioning the sidebar that are closed
-
Assignee, such as, all issues mentioning the sidebar that were assigned to @mdo
Our Help article on searching Issues can show you other ways to search: using created/updated dates, labels, authors, comment counts, by repository owner, and more.
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.
If you’re looking for a broader listing of all of your issues across many projects, the Issues Dashboard can be a great tool. The dashboard works very similar to the issues section, but collects issues differently:
- All issues in repositories you own and collaborate on
- Issues assigned to you
- Issues you’ve created
If you use organizations, each one has its own Issues dashboard that separates out Issues within the organization.
Underneath each repository is a section called Pulse — Pulse is a snapshot of everything that’s happened in the repository in the past week (or day, or past 3 months, etc).
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.
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:
-
Request for recipes (maybe you have a good gluten-free pizza dough recipe?)
Now congratulate yourself — 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.
<title>Getting Started with GitHub Pages</title> http://guides.github.com/features/pages/ Sun, 01 Dec 2013 00:00:00 +0000 http://guides.github.com/features/pages/index.mdGitHub 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.
Once you’ve signed in, you’ll create a new repository to get started.
On the new repository screen, you need to give this repository a special name to generate your website.
Your website’s files will live in a repository named username.github.io (where “username” is your actual GitHub user name). To begin setting up your site, you have to open the Settings tab
If you scroll down on the settings page, you’ll see the GitHub Pages section near the bottom. Click the Choose a theme button to start the process of creating your site.
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 Select theme 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.
Here’s where you’ll write your own content (You can keep the default content for now, if you’d like).
Once you’re finished editing, scroll down to the bottom of the page and click Commit changes.
GitHub does all the work to direct visitors to username.github.io 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!
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: master.
View the _config.yml file by navigating to it in the Code tab. You can edit the file by clicking on the pencil icon.
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.
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”
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.
When you’re done, click Commit changes and your updates will go live in just a few seconds!
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:
<title>Git Handbook</title> http://guides.github.com/introduction/git-handbook/ Mon, 25 Sep 2017 00:00:00 +0000 http://guides.github.com/introduction/git-handbook/index.mdA 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:
- Which changes were made?
- Who made the changes?
- When were the changes made?
- Why were changes needed?
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.
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.
According to the latest Stack Overflow developer survey, 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, with significant benefits for individuals, teams and businesses.
-
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.
-
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.
-
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.
A repository, or Git project, 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 commits, and the commits exist as a linked-list relationship, and can be organized into multiple lines of development called branches. 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.
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.
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.
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 GitHub Desktop or Git Kraken. Here are some common commands for using Git:
-
git initinitializes 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. -
git clonecreates a local copy of a project that already exists remotely. The clone includes all the project’s files, history, and branches. -
git addstages 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. -
git commitsaves 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 withgit addwill become a part of the snapshot withgit commit. -
git statusshows the status of changes as untracked, modified, or staged. -
git branchshows the branches being worked on locally. -
git mergemerges 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. -
git pullupdates 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. -
git pushupdates the remote repository with any commits made locally to a branch.
Learn more from a full reference guide to Git commands.
For a detailed look at Git practices, the videos below show how to get the most out of some Git commands.
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.
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.
The GitHub flow is a lightweight, branch-based workflow built around core Git commands used by teams around the globe—including ours.
The GitHub flow has six steps, each with distinct benefits when implemented:
- Create a branch: Topic branches created from the canonical deployment branch (usually
master) allow teams to contribute to many parallel efforts. Short-lived topic branches, in particular, keep teams focused and results in quick ships. - Add commits: Snapshots of development efforts within a branch create safe, revertible points in the project’s history.
- Open a pull request: Pull requests publicize a project’s ongoing efforts and set the tone for a transparent development process.
- Discuss and review code: 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.
- Merge: 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.
- Deploy: 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.
Developers can find more information about the GitHub flow in the resources provided below.
For developers new to the command line, the GitHub Training team has put together a series of tutorials on Git commands to guide the way. Sometimes, a series of commands can paint a picture of how to use Git:
# download a repository on GitHub.com to our machine git clone https://github.com/me/repo.git # change into the `repo` directory cd repo # create a new branch to store any new changes git branch my-branch # switch to that branch (line of development) git checkout my-branch # make changes, for example, edit `file1.md` and `file2.md` using the text editor # stage the changed files git add file1.md file2.md # take a snapshot of the staging area (anything that's been added) git commit -m "my snapshot" # push changes to github git push --set-upstream origin my-branch First, you will need to create a new repository on GitHub. You can learn how to create a new repository in our Hello World guide. Do not initialize the repository with a README, .gitignore or License. This empty repository will await your code.
# create a new directory, and initialize it with git-specific functions git init my-repo # change into the `my-repo` directory cd my-repo # create the first file in the project touch README.md # git isn't aware of the file, stage it git add README.md # take a snapshot of the staging area git commit -m "add README to initial commit" # provide the path for the repository you created on github git remote add origin https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git # push changes to github git push --set-upstream origin master # 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 # change into the `repo` directory cd repo # update all remote tracking branches, and the currently checked out branch git pull # change into the existing branch called `feature-a` git checkout feature-a # make changes, for example, edit `file1.md` using the text editor # stage the changed file git add file1.md # take a snapshot of the staging area git commit -m "edit file1" # push changes to github git push There are two primary ways people collaborate on GitHub:
With a shared repository, 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.
For an open source project, or for projects to which anyone can contribute, managing individual permissions can be challenging, but a fork and pull 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 Forking Projects Guide for more information.
The GitHub team has created a library of educational videos and guides to help users continue to develop their skills and build better software.
- Beginner projects to explore
- GitHub video guides
- GitHub on-demand training
- GitHub training guides
- GitHub training resources
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.
<script type="text/javascript" src="flow.js"></script>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.
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 master 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.
Branching is a core concept in Git, and the entire GitHub flow is based upon it. There's only one rule: anything in the master branch is always deployable.
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., refactor-authentication, user-content-cache-key, make-retina-avatars), so that others can see what is being worked on.
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.
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.
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.
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.
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.
Pull Requests are useful for contributing to open source projects and for managing changes to shared repositories. If you're using a Fork & 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.
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.
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.
Pull Request comments are written in Markdown, so you can embed images and emoji, use pre-formatted text blocks, and other lightweight formatting.
With GitHub, you can deploy from a branch for final testing in production before merging to master.
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.
Now that your changes have been verified in production, it is time to merge your code into the master branch.
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.
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 Closes #32 would close issue number 32 in the repository. For more information, check out our help article.