Introducing GitHub, 2nd Edition

Chapter 1. Introduction

In this chapter I’ll start by introducing Git and GitHub. What are they, what is the difference between them, and why would you want to use them? I’ll then introduce some other common terms that you’ll often hear mentioned when people are discussing GitHub. That way you’ll be able to understand and participate in discussions about your projects more easily.

What Is Git?

Git is a version control system. A version control system is a piece of software designed to keep track of the changes made to files over time. More specifically, Git is a distributed version control system, which means that everyone working with a project in Git has a copy of the full history of the project, not just the current state of the files.

What Is GitHub?

GitHub is a platform where you can upload a copy of your Git repository (often shortened to repo), hosted either on GitHub.com, by your company on a cloud provider (like Azure, AWS, or IBM Bluemix), or on your company’s own servers behind its firewall. But more than just uploading your Git repositories, it allows you to collaborate much more easily with other people on your projects. It does that by providing a centralized location to share the repository, a web-based interface to view it, and features like forking, Pull Requests, Issues, Projects, and GitHub Wikis that allow you to specify, discuss, and review changes with your team more effectively.

Why Use Git?

Even if you’re working on your own, if you are editing text files, there are a number of benefits to using Git, including the following:

The ability to undo changes

If you make a mistake, you can go back to a previous point in time to recover an earlier version of your work.

A complete history of all the changes

If you ever want to see what your project looked like a day, week, month, or year ago, you can check out a previous version of the project to see exactly what the state of the files was back then.

Documentation of why changes were made

Often it’s hard to remember why a change was made. With commit messages in Git, it’s easy to document for future reference why you’re making a change.

The confidence to change anything

Because it’s easy to recover a previous version of your project, you can have the confidence to make any changes you want. If they don’t work out, you can always get back to an earlier version of your work.

Multiple streams of history

You can create different branches of history to experiment with different changes to your content or to build out different features independently. You can then merge those back into the main project history (master branch) once they’re done, or delete them if they end up not working out.

Working on a team, you get an even wider range of benefits when using Git to keep track of your changes. Some of the key benefits of Git when working with a team are:

The ability to resolve conflicts

With Git, multiple people can work on the same file at the same time. Usually Git will be able to merge the changes automatically. If it can’t, Git will show you what the conflicts are and you will hopefully be able to easily resolve them.

Independent streams of history

Different people working on the project can work on different branches, allowing them to work on separate features independently and then merge the features when they’re done.

Why Use GitHub?

GitHub is much more than just a place to store your Git repositories. It provides a number of additional benefits, including the ability to do the following:

Document requirements

Using issues, you can either document bugs or specify new features that you’d like to have your team develop.

Collaborate on independent streams of history

Using branches and pull requests, you can collaborate on different branches or features.

Review work in progress

By looking at the list of pull requests, you can see all of the different features that are currently being worked on; by clicking any given pull request you can see the latest changes and all of the discussions about the changes, check the status of an integration like a Continuous Integration (CI) server, or even add your own review to approve changes before they are accepted.

See team progress

Skimming the pulse or looking through the commit history allows you to see what the team has been working on.

Key Concepts

There are a number of key concepts that you’ll need to understand to work effectively with Git and GitHub. Here is a list of some of the most common terms, with a short description of each and an example of how they might be used in conversation:

Commit

Whenever you save your changes in one or more files, you can create a new commit in Git. A commit is like a snapshot of your entire repository at that point in time, not just of one or two files. So naturally, after you change those files, you will want to update the repository by taking a new snapshot. Example usage: “Let’s commit these changes and push them up to GitHub.”

Commit message

Every time you make a commit, you need to supply a message that describes why the change was made. That commit message is invaluable when trying to understand later why a certain change was implemented. Example usage: “Make sure to include Susan’s comment about the new SEC guidelines in the commit message.”

Branch

A branch is an independent series of commits off to one side that you can use to try out an experiment or create a new feature. Example usage: “Let’s create a branch to implement the new search functionality.”

master branch

Whenever you create a new Git project, there is a default branch created called master. This is the branch that your work should end up on eventually, once it’s ready to push to production. Example usage: “Remember never to commit directly to master.”

Feature (or topic) branch

Whenever you’re building a new piece of functionality, you’ll create a branch to work on it. That is called a feature branch. Example usage: “We’ve got way too many feature branches. Let’s focus on getting one or two of these finished and into production.”

Release branch

If you have a manual QA process or have to support old versions of your software for your customers, you might need a release branch as a place to make any necessary fixes or updates. There is no technical difference between a feature or release branch, but the distinction is useful when talking about a project with your team. Example usage: “We’ve got to fix the security bug on all of our supported release branches.”

Merge

A merge is a way to take completed work from one branch and incorporate it into another branch. Most commonly you’ll merge a feature branch into the master branch. Example usage: “Great job on the ‘my account’ feature. Could you merge it into master so we can push it to production?”

Tag

A tag is a reference to a specific historic commit. Tags are most often used to document production releases so you know exactly which versions of the code went into production and when. Example usage: “Let’s tag this release and push it to production.”

Checkout

Checking out enables you to go to a different version of the project’s history and see the files as of that point in time. Most commonly you’ll check out a branch to see all of the work that has been done on it, but any commit can be something you check out. Example usage: “Could you check out the last release tag? There’s a bug in production that I need you to replicate and fix.”

Pull request

Originally, a pull request was used to request that someone else review the work you’d completed on a branch and then merge it into master. Now, pull requests are often used earlier in the process to start a discussion about a possible feature. Example usage: “Go create a pull request for the new voting feature so we can see what the rest of the team thinks about it.”

Issue

GitHub has a feature called Issues that can be used to discuss features, track bugs, or both. Example usage: “You’re right, the login doesn’t work on an iPhone. Could you create an issue on GitHub documenting the steps to replicate the bug?”

Wiki

Originally developed by Ward Cunningham, wikis are a lightweight way of creating web pages with simple links between them. GitHub projects often use wikis for documentation. Example usage: “Could you add a page to the wiki to explain how to configure the project to run on multiple servers?”

Clone

Often you’ll want to download a copy of a project from GitHub so you can work on it locally. The process of copying the repository to your computer is called cloning. Example usage: “Could you clone the repo, fix the bug, and then push the fix back up to GitHub later tonight?”

Fork

Sometimes you don’t have the necessary permission to make changes directly to a project. Perhaps it’s an open source project written by people you don’t know, or a project written by another group at your company that you don’t work with much. If you want to submit changes to such a project, first you need to make a copy of the project under your user account on GitHub. That process is called forking the repository. You can then clone it, make changes, and submit them back to the original project using a pull request. Example usage: “I’d love to see how you’d rewrite the home page marketing copy. Fork the repo and submit a pull request with your proposed changes.”

Don’t worry if all the terminology seems overwhelming at first. Once you start working with some real projects, it’ll all make a lot more sense! In the next chapter we’ll look at the various elements of a GitHub project and how you can use them to get a sense of progress on a project.