Using GitHub

Here are some ways to use GitHub to your advantage.

Pull Requests

Pull requests are requests to merge the work you've done with another repository. This is the core of GitHub. There are two things you can do: request a pull/push, or confirm a pull/push.

1. Click on the "Pull Request" button for your repository on the GitHub website (next to the "Watch", "Star", and "Fork" buttons). This takes you to a new page.
2. The head repo & branch is the one being merged into the body repo & branch. If the two have "differences", then you will get a form asking you for some info.
3. Give a description and request the pull/push.
4. You should be redirected to a comment thread, which includes the pull request you just made.
5. If you have permission to merge, do so. If you don't, wait for someone that has permission to do it.

Branches

Branches are a way to organize your commits. Ideally, your "master" branch should always be ready to deploy. I organize my branches like so:

• master
  • Deployable code that's been thoroughly tested, with minimal bugs.
• development
  • This is where most of your commits should be.
• features
  • This includes specific large-scale features you're working on.
  • An example is my "encapsulation" branch.
• lint
  • Minor changes, such as more commenting, or improved algorithms.
• gh-pages
  • Includes the HTML files for the project's homepage. You shouldn't need this branch.

To add a branch, open your repository with the GitHub client, and click on the menu with branches on it (next to the "tools" menu). Type the name of your new branch. Before making changes, the branch should be published (the button in place of the "sync" button). Voila! You can now commit to your new branch.

Now you can send pull requests between branches (your own, or someone else's). When choosing the head/base repository to pull from/to, be sure to select the correct branch.

Another point: when you switch branches (same menu as creating a new one), the files in the folder on your machine get replaced with the ones in the branch. So close all editors before switching branches, or you could get some nasty errors. Make sure you're working on the right branch!

Markdown

GitHub uses Markdown extensively. If you don't know markdown, here's a nice guide at Daring Fireball. If you prefer to learn by example, here's a source document, and here's the rendered output.

Markdown files have the extension .md, and can be created with any text editor (Notepad, Notepad++, Vim, Vi, etc.)

One common problem is formatting code: you must use backticks, not apostrophes. The backtick key is usually near the top left corner of the keyboard, near the Esc key.