June 2014 / 10 minutes / Best Practices / Tim Slavin

Github Basics

While the act of programming is mostly done alone at your computer, building software applications is often a group activity. People divide up the programming work, then work to pull all the code together. Github is an online service designed to help coders work by themselves and with others to complete projects. Lots of open source software projects also are on Github and the service offers an easy way for people to contribute code.

This article describes how you can join Github and begin to use it for your projects and help others with their projects. There are Github tutorials of all kinds online, as well as articles on how to get the most from this service. Github also provides a YouTube channel with dozens of videos to demonstrate features. And Lynda.com has a great introductory online course for web designers (translation: people who are often non-technical).

What is Github?

It’s an online service to make it easy to track, store, and modify code the same way people use Git and other version control software. Instead of using terminal software on your computer, typing in obscure commands to manage your code, you can use your web browser and a standalone application offered free by Github. Real coders still use terminal software to send files back and forth to Github. But you’re not forced to do so if you want the ability to create and manage different versions of your code.

Once you sign up for Github, you can do several things:

  • Create repositories to store your code. These are either private, spaces you invite people to share with you, or public and easily found by others.
  • Fork (copy) other code repositories. You can update code in your fork then upload your changes to the master repository. This is how people contribute code to open source software projects. Forking sometimes is called cloning.
  • Send pull requests to ask the owner of a code repository to include your changes in the master repository. Not all changes are accepted, of course.
  • Subscribe to watch projects and be notified of changes.
  • Assign issues to fix in the code and manage your contributions to fix issues.

Github also gives you a home page, typically http://github.com/yourusername. From there, you and others can view your activity, follow you, follow your project(s), add pull requests, and more. When you return to the main Github page once logged in, at the top you’ll see four boxes to help you learn about their service.

Repositories are a key part of Github and any software version control process. There is a master repository stored at Github and coders can make any number of copies (clones or forks) of the master. Once you have a copy of the code repository on your local machine, then you create branches to modify code. While you could make changes to your copy of the master repository, things can go horribly wrong. If you have a change to make, it is much easier to create a branch, make your changes, then send your branch upstream to be incorporated into the master repository.

How to Use Github

To work with Github, you use either Git with terminal software or the Github software downloaded to your computer. I recommend the latter if you’re new to Github and software development. It’s easy enough to make time later to learn how to do the same things with Git and terminal software. Starting out, however, learning Git and Github would be more complicated. Especially if you only want to fork (copy) a code repository to play with on your computer.

The Github software is intuitive to use and looks like this screenshot from their site:

Sample screen shot of Github software app
Sample Github Software Screen

This view displays once you are in a repository, a folder with files that contain code as part of a project. Notice the History, Changes, Branches, and Settings icons on the far left, as well as the Sync Branch button on the top right corner. Also notice the Repositories label at the top left of the screen: clicking the label takes you to a list of all your repositories.

Here are some practical first steps to demonstrate common Github tasks:

  • Create a new repository
  • Add a file to the new repository
  • Add a new branch then add a second file and merge with your repository
  • Add a new branch from the master branch which now includes your second file.
  • Clone (fork) a project then pull it to your local machine to work on the project locally.

These are common everyday tasks. They’re fairly easy to do with the Github software. However, your initial goal should be simple: become familiar with the ideas of repositories, branches, merges, and other parts of the version control process.

I debated whether to document these steps with screenshots or not. Screenshots often get in the way, especially with more than 3-5 steps. Instead, I recommend you print out this page and work through the tasks, checking off each step as you complete them.

Create Your First Repository on Github

First we’ll connect your Github account to Github software on your local machine.

  1. Sign up for a Github account.
  2. Download then install the Github software. You will be prompted to use your Github account username and password.
  3. Select the My Repositories folder on the top left side of the Github software.
  4. Click the + button at the bottom of the Github software then select Create New Repository.
  5. Type a Name, Description, and local path to your new Github project. Use dash or underscore instead of spaces for repository name. Check the box next to Push to Github?. I named my project Test-Project.
  6. Click the Create Repository button.
  7. Refresh your Github home page to see your new test project repository. Note there are no files in your repository.

Add a File to Your Repository

Next we add a file to the master repository. Do not create a branch for this change.

  1. Select the My Repositories folder on the top left side of the Github software.
  2. Right mouse-click over your test project and select Open in Finder.
  3. Use a text editor to create a text file in your test project folder.
  4. Return to the Github software and select the My Repositories folder on left side.
  5. Double-click the test project repository name. Your new text file should be listed and pre-selected as NEW.
  6. In the Uncommited Changes box between the left side icons and the text file on the right, enter a summary of this change and a short description.
  7. Click the Commit button. Your commit will appear as an Unsynced Commit in the center column.
  8. Click the Sync Branch button at top right of the Github software to push your changes to Github.
  9. On your Github home page, click your test project repository link to display the repository home page. You should see your test file.

Add a File to a New Branch then Merge File into Your Repository

In this example, we create a branch, make changes, then work with the Github site to merge our changes into the master repository. This is the normal workflow process most developers follow.

  1. Click the Branches icon on the left side of the Github software. The master repository should be displayed.
  2. Click the + button at far right of the repository name. Type in the name of a new branch. Click the Branch button to save new branch. Your new branch should be selected with a check mark to the left of the branch name.
  3. Use a text editor to create a text file in your test project folder. This time I created a file with the name readme with no file extension.
  4. Return to the Github software and select the Changes icon on left side. The new file should be listed and pre-selected as NEW.
  5. Click the square + button to immediate left of Commit button. The Commit button changes to Commit & Sync. Click the Commit & Sync button.
  6. In the Uncommited Changes box between the left side icons and the text file on the right, enter a summary of this change and a short description.
  7. On your Github home page, click your test project repository link to display the repository home page. You should see your branch name with a green rectangular Compare and Pull Request button. Click the button.
  8. An add pull request page displays. Click the green Send pull request button.
  9. The pull request page displays. Click the green Merge pull request button. Click the green Confirm merge button. Your new pull request to add a readme file is now part of the master repository. If needed, you can delete the branch you created.
  10. Click the Sync Branch button at top right of the Github software to pull your changes from Github. Your second file will now be part of the master repository on your local machine.

Create a Second Branch and Merge with Repository

While these steps repeat those in the previous process, the key here is to create your branch from your updated local master repository. Do not start from the last branch you worked in, the one merged into the master repository. You want to be certain every change you make is part of a unique branch, whether the change is a small copy edit or adding dozens of files.

  1. Click the Branches icon on the left side of the Github software. The master repository should be displayed.
  2. Click the down arrow, directly below the + button, at far right of the master repository name. Select Switch to This Branch. This selects your master repository as the start point to create a new branch where you will add files or make changes.
  3. Click the + button at far right of the repository name. Type in the name of a new branch. Click the Branch button to save new branch. Your new branch should be selected with a check mark to the left of the branch name.
  4. Use a text editor to create a text file in your test project folder.
  5. Return to the Github software and select the Changes icon on left side. The new file should be listed and pre-selected as NEW.
  6. Click the square + button to immediate left of Commit button. The Commit button changes to Commit & Sync. Click the Commit & Sync button.
  7. In the Uncommited Changes box between the left side icons and the text file on the right, enter a summary of this change and a short description.
  8. On your Github home page, click your test project repository link to display the repository home page. You should see your branch name with a green rectangular Compare and Pull Request button. Click the button.
  9. An add pull request page displays. Click the green Send pull request button.
  10. The pull request page displays. Click the green Merge pull request button. Click the green Confirm merge button. Your new pull request to add a readme file is now part of the master repository. If needed, you can delete the branch you created.
  11. Click the Sync Branch button at top right of the Github software to pull your changes from Github.

Clone a Remote Project to Your Local Machine

Finally, you can clone (or fork) a copy of a project on Github. These steps clone your repository. But you can click the Fork icon on other Github projects (assuming you are logged in, of course) then follow these steps to clone a local copy on your computer.

  1. On your Github home page, click the Repositories tab in the top center. You should see your repositories listed.
  2. Click the green New button to create a new repository.
  3. Type in your Repository name and a Description. Select whether the project is public or private. Click the green Create repository button.
  4. In the Github software on your computer, click the Repositories name at the top of the screen. Select your Github.com username to display your repositories.
  5. Click the round arrow icon at the bottom of the interface to refresh the repository list from Github. You should see your new project created on the Github website.
  6. Click the Clone to Computer button to the right of your new repository.
  7. Right mouse click over the new repository name and select Show in Finder.
  8. Use a text editor to create a new text file in the new repository folder on your local machine.
  9. Return to the Github software and select the Changes icon on left side. The new file should be listed and pre-selected as NEW.
  10. Click the square + button to immediate left of Commit button. The Commit button changes to Commit & Sync. Click the Commit & Sync button.
  11. In the Uncommited Changes box between the left side icons and the text file on the right, enter a summary of this change and a short description.
  12. On your Github home page, click your test project repository link to display the repository home page. You should see your branch name with a green rectangular Compare and Pull Request button. Click the button.
  13. An add pull request page displays. Click the green Send pull request button.
  14. The pull request page displays. Click the green Merge pull request button. Click the green Confirm merge button. Your new pull request to add a readme file is now part of the master repository. If needed, you can delete the branch you created.
  15. Click the Sync Branch button at top right of the Github software to pull your changes from Github.

While Github might appear complex, it is easy to learn if you use Github on a regular basis. The Help link at the top of Github pages has lots of support. And they have a YouTube channel with training. There also are lots of tutorials, as noted below.

I’ve written an overview article about version control software like Git in an earlier issue of this magazine.

Learn More

Github

https://github.com
https://help.github.com/
https://help.github.com/articles/set-up-git

Github Software

https://mac.github.com/
https://mac.github.com/help.html
https://windows.github.com/
https://windows.github.com/help.html

Github Guides Tutorials (YouTube)

https://www.youtube.com/user/GitHubGuides
https://www.youtube.com/playlist?list=PLg7s6cbtAD15G8lNyoaYDuKZSKyJrgwB-

Github for Web Designers (Lynda.com)

www.lynda.com/GitHub-tutorials/GitHub-Web-Designers/162276-2.html

Github Tutorials

https://learn.sparkfun.com/tutorials/using-github/all
http://www.kobashicomputing.com/a-github-tutorial

Github for Web Designers (Lynda.com)

Requires a monthly fee but there are many great courses to make the cost worthwhile, including this course.
http://www.lynda.com/GitHub-tutorials/GitHub-Web-Designers/162276-2.html

Understanding Github

A good overview of how non-coders can use Github. Because there are command line software bits which some might consider advanced, this might be a good start for learning how to command line Git instead of Github software.
http://readwrite.com/2013/09/30/understanding-github-a-journey-for-beginners-part-1
http://readwrite.com/2013/10/02/github-for-beginners-part-2