GitHub Guides

Hello World

Thu, 07 Apr 2016 00:00:00 +0000

The 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

What is GitHub?

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.

No coding necessary

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.

Step 1. Create a Repository

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.

To create a new repository

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. :tada:

Step 2. Create a Branch

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 master branch
A new branch called feature (because we’re doing ‘feature work’ on this branch)
The journey that feature takes before it’s merged into master

Have you ever saved different versions of a file? Something like:

story.txt
story-joe-edit.txt
story-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.

To create a new branch

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.

Step 3. Make and commit changes

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.

Make and commit changes

Click the README.md file.
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.

Step 4. Open a Pull Request

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.

Open a Pull Request for changes to the README

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.
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.

Step 5. Merge your Pull Request

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.

Celebrate!

By completing this tutorial, you’ve learned to create a project and make a pull request on GitHub! :tada: :octocat: :zap:

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 :octocat:

Tip: Check out our other Guides, YouTube Channel and On-Demand Training for more on how to get started with GitHub.

Contributing to Open Source on GitHub

Fri, 04 Apr 2014 00:00:00 +0000

A great way to get involved in open source is to contribute to the existing projects you’re using. GitHub is home to more than 5 million open source projects. There are projects for every skill set like recipes, HTML/CSS, Ruby, Astrophysics and many more. This guide will cover what you might find in a typical project and how to make a great contribution.

Find Projects

We recommend that you start by finding a project that you’re already (or are interested in) using. Here are a few great places to look:

GitHub Explore: Popular and trending projects.
GitHub Stars: Projects starred by other people.
GitHub Showcases: A way to discover related repositories.
Designer News: Front-end development and design projects.

A Typical Project

Below are some elements you’re likely to come across in an open source project on GitHub.

The Community

Projects often have a community around them, made up of other users in different (formal or informal) roles:

Owner is the user or organization that created the project has the project on their account.
Maintainers and Collaborators are the users primarily doing the work on a project and driving the direction. Oftentimes the owner and the maintainer are the same. They have write access to the repository.
Contributors is everyone who has had a pull request merged into a project.
Community Members are the users who often use and care deeply about the project and are active in discussions for features and pull requests.

The Docs

The what’s-what of common files in projects.

Readme

Nearly all GitHub projects include a README.md file. The readme provides a lay of the land for a project with details on how to use, build and sometimes contribute to a project.

Contributing

Projects and project maintainers vary, so the best way to contribute will also vary. Keep your eye open for a doc labeled CONTRIBUTING. Contributing docs detail the specifics about how a project’s maintainer would like to see patches or features contributed. This can include what tests to write, code syntax style or areas to focus on for patches.

License

A LICENSE file, well, is the license for the project. An open source project’s license informs users what they can and can’t do (e.g., use, modify, redistribute), and contributors, what they are allowing others to do. There are many ways to license and open source project, you can read more about what each license means at choosealicense.com.

Documentation and Wikis

Many larger projects go beyond a readme to give instructions for how people can use their project. In such cases you’ll often find a link to another file or a folder named ‘docs’ in the repository.

Alternatively, the repository may instead use the GitHub wiki to break down documentation.

Contributing to a Project

Now that you’ve found the material for understanding the project, here is how you can take action.

Create an Issue

If you find a bug in a project you’re using (and you don’t know how to fix it), have trouble following the documentation or have a question about the project – create an issue! There’s nothing to it and whatever issue you’re having, you’re likely not the only one, so others will find your issue helpful, too. For more information on how issues work, check out our Issues guide.

Issues Pro Tips

Check existing issues for your issue. Duplicating an issue is slower for both parties so search through open and closed issues to see if what you’re running into has been addressed already.
Be clear about what your problem is: what was the expected outcome, what happened instead? Detail how someone else can recreate the problem.
Link to demos recreating the problem on things like JSFiddle or CodePen.
Include system details like what the browser, library or operating system you’re using and its version.
Paste error output or logs in your issue or in a Gist. If pasting them in the issue, wrap it in three backticks: ` ``` ` so that it renders nicely.

Pull Request

If you’re able to patch the bug or add the feature yourself – fantastic, make a pull request with the code! Be sure you’ve read any documents on contributing, understand the license and have signed a Contributor Licence Agreement (CLA) if required. Once you’ve submitted a pull request the maintainer(s) can compare your branch to the existing one and decide whether or not to incorporate (pull in) your changes.

Pull Request Pro Tips

Fork the repository and clone it locally. Connect your local to the original ‘upstream’ repository by adding it as a remote. Pull in changes from ‘upstream’ often so that you stay up to date so that when you submit your pull request, merge conflicts will be less likely. See more detailed instructions here.
Create a branch for your edits.
Be clear about what problem is occurring and how someone can recreate that problem or why your feature will help. Then be equally as clear about the steps you took to make your changes.
It’s best to test. Run your changes against any existing tests if they exist and create new ones when needed. Whether tests exist or not, make sure your changes don’t break the existing project.
Include screenshots of the before and after if your changes include differences in HTML/CSS. Drag and drop the images into the body of your pull request.
Contribute in the style of the project to the best of your abilities. This may mean using indents, semi colons or comments differently than you would in your own repository, but makes it easier for the maintainer to merge, others to understand and maintain in the future.

Open Pull Requests

Once you’ve opened a pull request a discussion will start around your proposed changes. Other contributors and users may chime in, but ultimately the decision is made by the maintainer(s). You may be asked to make some changes to your pull request, if so, add more commits to your branch and push them – they’ll automatically go into the existing pull request.

If your pull request is merged – great! If it is not, no sweat, it may not be what the project maintainer had in mind, or they were already working on it. This happens, so our recommendation is to take any feedback you’ve received and go forth and pull request again – or create your own open source project.

Be Social

Thu, 23 Jan 2014 00:00:00 +0000

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.

Follow a Friend

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 the Explore page.

Step 1: Pick a friend.

Why not follow one of these cool people from GitHub:

jlord

charliesome

benbalter

tekkub

muan

mdo

Step 2: Follow that friend

Once you are on someone’s profile, click the “follow” button.

Congratulations! You are now following a friend.

Watch a Project

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 on that project. You can choose to have notifications for this project 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 project called Hello World that we’d like to watch.

Once you are on the project 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 project. If the Octocat updates it, you will see what happened in your dashboard or receive a notification.

More Things You Can Do

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:

Stargazing

If you’re interested in some of the projects 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!

Explore / Newsletter

The Explore page has projects 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.

Celebrate

Congratulations! You are quite the socialite. Check out some of these next steps:

Forking Projects

Thu, 23 Jan 2014 00:00:00 +0000

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 and the GitHub Desktop application. To download the desktop application, head over to https://desktop.github.com.

Fork the repository

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.

Clone your fork

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 for Desktop application, this process is a breeze. On your fork of Spoon-Knife, navigate over to the bottom of the right hand side bar and click Clone in Desktop. Once we click this, it’ll ask us if we want to launch our desktop application to clone the repository, and where we want to save it. Pick a location on your computer that you feel comfortable with creating files and folders.

Making and pushing changes

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, type up a commit summary in GitHub for Desktop, and click Commit.

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, click on the Sync button, which is right above your list of changes.

Making a Pull Request

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!

Huzzah!

You’ve successfuly forked and contributed back to a repository. Go forth, and contribute some more!

Making Your Code Citable

Sat, 01 Oct 2016 00:00:00 +0000

Digital 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.

Choose your 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.

Login to Zenodo

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.

Pick the repository you want to archive

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.

Check repository settings

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.

Create a new release

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.

Checking everything has worked

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.

Minting a DOI

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!

Finishing up

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.

Mastering Issues

Mon, 07 Apr 2014 00:00:00 +0000

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 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.

Milestones, Labels, and Assignees

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

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

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.

Assignees

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.

Notifications, @mentions, and References

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

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

@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.

References

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.

Search

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.

Overviews & Reports

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.

The Issue Dashboard

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.

Pulse

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.

Other Uses for Issues

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:

Bug tracker for your house including such gems as the door being hung incorrectly
Bug tracker for your open source projects
Request for recipes (maybe you have a good gluten-free pizza dough recipe?)

Fin

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.

Getting Started with GitHub Pages

Sun, 01 Dec 2013 00:00:00 +0000

GitHub Pages are public webpages hosted and easily published through GitHub. The quickest way to get up and running is by using the Automatic Page Generator to create some starter HTML and CSS for us. You can then modify our GitHub Pages’ content and style remotely via the web or locally on our computer.

Create Your Website

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 HTML and CSS will all live in a repository named username.github.io (where “username” is your actual GitHub user name). To get an initial set of HTML and CSS, you have to open the Settings tab and enable the Automatic Page Generator

If you scroll down on the settings page, you should see the Automatic Page Generator button near the bottom. By clicking this button, you start the process of generating your content automatically.

Once you’ve clicked the button, you’ll be directed to the first step of the generation: The Content. You can keep this default content for now and make changes to it later. Let’s go ahead and click Continue to Layouts at the bottom of the page to continue.

Now, you pick your theme. This part requires a bit more thought because it’s easier to choose a theme now than to update your theme later. When you’ve looked at some of the options at the top of the page and found one that you love, click Publish to finish.

Once you click Publish, 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!

Making Changes

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.

If you click on the index.html file to navigate into that file, you can make edits to it by clicking Edit.

Let’s find in this file where it says username.github.io and change this to a friendlier title. For the Octocat, I’m going to change it to “Welcome to the Octocat’s homepage!”. Feel free to do the same, except for your own username. Under this title, you should add a message about the purpose of the page and describe what you want people to do while they’re here.

After you’re done making this small change, scroll to the bottom of the page to make your first 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 change should go live in just a few seconds!

Next Steps

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:

Documenting your projects on GitHub

Fri, 15 Jul 2016 00:00:00 +0000

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.

Creating your README

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.

Formatting your README

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 naviagte 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)[https://help.github.com/articles/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.

Creating your wiki

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.

Adding content

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.

Adding pages

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.

Syntax highlighting

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’re done!

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.

Mastering Markdown

Wed, 15 Jan 2014 00:00:00 +0000

Markdown 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

What is Markdown?

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 .md or .markdown extension

Examples

It's very easy to make some words **bold** and other words *italic* with Markdown. You can even [link to Google!](http://google.com)

It's very easy to make some words bold and other words italic with Markdown. You can even link to Google!

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:

![Image of Yaktocat](https://octodex.github.com/images/yaktocat.png)

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

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

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! :sparkles: :camel: :boom:

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! :sparkles: :camel: :boom:

Syntax guide

Here’s an overview of Markdown syntax that you can use anywhere on GitHub.com or in your own text files.

Headers

# This is an <h1> tag
## This is an <h2> tag
###### This is an <h6> tag

Emphasis

*This text will be italic*
_This will also be italic_

**This text will be bold**
__This will also be bold__

_You **can** combine them_

Lists

Unordered

* Item 1
* Item 2
  * Item 2a
  * Item 2b

Ordered

1. Item 1
2. Item 2
3. Item 3
   * Item 3a
   * Item 3b

Images

![GitHub Logo](/images/logo.png)
Format: ![Alt Text](url)

Links

http://github.com - automatic!
[GitHub](http://github.com)

Blockquotes

As Kanye West said:

> We're living the future so
> the present is our past.

Inline code

I think you should use an
`<addr>` element here instead.

GitHub Flavored Markdown

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.

Syntax highlighting

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

Task Lists

- [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!

Tables

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

SHA references

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

Issue references within a repository

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

Username @mentions

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.

Automatic linking for URLs

Any URL (like http://www.github.com/) will be automatically converted into a clickable link.

Strikethrough

Any word wrapped with two tildes (like ~~this~~) will appear crossed out.

Emoji

GitHub supports emoji! :sparkles: :camel: :boom:

To see a list of every image we support, check out the Emoji Cheat Sheet.

Getting your project on GitHub

Wed, 15 Jan 2014 00:00:00 +0000

Software is at the heart of GitHub—and code is the DNA of software. Chances are if you’re joining, you’ve got some code that you might want to push to GitHub. And that’s a fantastic idea!

Here are some great reasons to push projects to GitHub:

Version Control — Everything on GitHub is stored in Git, the best version control system around. Version control allows you to experiment and make mistakes in code without messing up your final product.
Keep your code in one place — Whether you work on multiple computers or just want to get some old projects off your computer, GitHub is the perfect place to store your projects online.
Collaboration — Once your code is on GitHub, you can invite others to work on your code with you. Send them a link to help you debug a problem.

Once your project is on GitHub, we provide a URL for every file in your project. For example, this is Mike Bostock’s popular d3 project for creating data-driven documents with JavaScript.

We use the words Git and GitHub a lot in this article, so let’s clarify what they mean.

Git — The version control tool that GitHub is built on top of.
GitHub — Our company and the name of our software. We build software and websites to help you interact with Git repositories in a nice way.
GitHub.com — The website you log into to view repositories online.
GitHub Desktop — An application that you can install on your computer to help you synchronize local code with GitHub.com.

GitHub Desktop

GitHub Desktop is the easiest way to get code on GitHub.com. You won’t need to learn any command-line instructions, SSH keys, or complicated Git terminology. All you’ll need is your Mac or Windows computer and a GitHub.com account.

You can download GitHub Desktop for Mac and Windows. Once you install GitHub Desktop, a short set up wizard will walk you through some basic configuration and will help you connect GitHub Desktop with your GitHub.com account.

Set up your project in GitHub Desktop

The easiest way to get your project into GitHub Desktop is to drag the folder which contains your project files onto the main application screen.

If you are dragging in an existing Git repository, you can skip ahead and push your code to GitHub.com.

If the folder isn’t a Git repository yet, GitHub Desktop will prompt you to turn it into a repository. Turning your project into a Git repository won’t delete or ruin the files in your folder—it will simply create some hidden files that allow Git to do its magic.

Your first commit

All Git repositories are based on commits—snapshots of your code at a point in time. You need to make at least one commit before you can push your code up to GitHub.com.

Navigate to the Changes tab and click Commit to create your first commit. You’ll need to create a new commit every time you change files. Creating a commit is like saving a file—you are telling Git that you’d like to remember this point in history.

Make as many commits as you like locally. No one but you can see those commits until you push them to GitHub.com.

Push your code to GitHub.com

Click the “Publish” button in the upper-right corner and GitHub Desktop will ask you what kind of repository to create:

Public repository — Anyone can see a public repository, but you choose who can commit (make changes) to it. You can create as many public repositories as you want on GitHub.com for free.
Private repository — By default, only you can see a private repository. You choose who can see and commit to this repository by adding collaborators. Private repositories require a paid subscription on GitHub.com.

Now that you’ve published the repository, you have it in two places:

Local repository on your computer — You can work on this repository without an Internet connection using GitHub Desktop. This is where you edit files and make changes to your project.
Remote repository on GitHub.com — You can send people links to your repository on GitHub.com so they can see your code and use all of GitHub’s other features (like Issue management and Pull Requests).

Each time you make changes to your local repository, you’ll need to sync your changes (by clicking the button in the upper-right corner of GitHub Desktop) to make sure they show up online.

Getting code from GitHub.com

If you want to get some code from GitHub.com onto your computer or synchronize changes between multiple computers, you’ll need to either pull changes or clone a repository:

Pull changes — Click the “Sync” button in the upper-right corner of GitHub Desktop to bring code from an online repository (for example, changes that your co-worker pushed up) onto your computer. Note: This will also push changes you haven’t pushed yet.
Clone a repository — Click the “Clone in Desktop” button on GitHub.com to create a new copy of a repository on your computer.

Celebrate!

Now you know the basics of setting up projects on GitHub!

Download and use GitHub Desktop.
Make commits every time you accomplish a goal or want to save your progress.
Sync changes with GitHub.com to push your new commits and pull commits from others.

And you’re done! Here’s a bunch of awesome things you can do with repositories.

Understanding the GitHub Flow

Thu, 12 Dec 2013 00:00:00 +0000

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.

Create a branch

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.

ProTip

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.

Add commits

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.

ProTip

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.

Open a Pull Request

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.

ProTip

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.

Discuss and review your code

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.

ProTip

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

Deploy

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.

Merge

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.

ProTip

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.