GitHub for beginners

Using git and GitHub can be intimidating for people who don’t spend most of their time in the command line, or who haven’t used a collaborative version control system (VCS) before.

The intent of this post is to get newcomers to GitHub familiar with the basic concepts of working collaboratively with engineers on a GitHub project.

There are many tasks that aren’t related to pushing code that knowledge of how to contribute to a repo can be useful for.

This guide is for:

• Designers who can work with html & css, who normally would give static files to a developer. Everyone saves time if they can directly contribute to a repo.
• PMs who want more granular understanding of the process between concept and pushing the code. Even knowing the vocabulary can help PMs effectively communicate with the teams they’re working with.
• Copywriters or other non-technical roles (recruiters, etc) who may want to make small changes to text or links without flagging down an engineer or adding an issue to someone’s workload.
• Beginning software engineers who want to get their feet wet with git and/or github. Git can be a challenging roadblock when just getting started. This guide will get git out of your way so you can continue learning.

Note that the flow covered in this post is the github flow. There are many ways to use git, far more than I could ever cover. Your team’s flow may differ slightly from the one described in this post, but for the most part if you’re using github, the concepts will be similar.

This guide is meant to be read the first time straight through — some of the concepts may seem difficult to understand. Don’t worry, a lot of this post is vocabulary and may need to be read again once you understand the entire flow.

Near the end this post is a step-by-step list of how to contribute to a project. Feel free to skip there if you just want to start pushing code. However, I recommend reading this guide at least once, so you’ll understand the concepts behind the flow.

Lastly, this guide assumes you’ll be doing most of your git interaction with the GitHub Desktop app. If you don’t have it already, Download it here.

The Basics

Git is essentially a tool for making sure everyone can see the same copy of a folder and make changes to it, without overwriting each other. The folder that the files you’ll be changing in is called a repo. Each repo has a .git folder in it, where git stores it’s changes. You’ll probably never have to edit anything inside of this folder.

One can obtain a copy of a repo by cloning it. If you’re on github.com, you can easily clone a repo by clicking the Clone in Desktop button:

Git is a Distributed Version Control System. There are a lot of technicalities around what this really means, but the most important initial concept to understand is that in git, there is no single source of truth. The version of the repo that exists on github’s servers is functionally identical to the one on your machine.

To make sure everyone sees the same code in git, it is necessary to perform pulls and pushes. When you perform one of these operations, you’ll be performing it against a remote.

A remote is a different version of the git repo that your version can sync with. In our case, we’ll be working with a single remote, called origin. When you clone a repo from GitHub, it automatically configures origin to point to github's copy of the repo.

When you push to a remote, you’re just telling it that you want the history of that repo to match the history of yours. It will then take the changes you’ve made, and add them to the remote repo.

This relationship is bi-directional, which is what makes git so good for collaboration. If there are changes on GitHub that you want to have locally, you’ll perform the inverse, and pull from origin. This will make it so that your local repository matches the one you see on github.com.

In a practical example:

• When we want to publish something to github so others can see our changes online, we’ll push to origin.
• When we want to update our local repo to match the changes we see on github.com, we’ll pull from origin.

Git history and merging

In git, it is sometimes necessary to merge your changes with the changes on a remote. To understand why this is necessary, it’s important to grasp the concept of git history:

When you make a local change and want to sync it with the server, git looks at both of the repos and makes sure that the remote version doesn’t contain any changes that the local one doesn’t have. If the remote has changes the local doesn’t, git will refuse the pull, and demand that you pull the history to your local repo first:

To get git to allow us to push, we could pull from the remote, which will in turn create a merge. Then, since local and origin have the same commits (but local has new changes), git will let us push again.

Git merges are a complex subject (don’t worry, you don’t need to understand them to follow this guide), but the general idea is that git wants to apply the changes that exist on the remote along side our local changes in the order they happened. Once this is done, we can push to the remote, and they will once again contain the same set of changes.

GitHub makes the process of keeping our local and remote changes in sync much easier, by adding two concepts on top of git that are specific to GitHub: Pull Requests, and syncing.

But before we talk about those additions, there is one last git concept you’ll want to be familiar with:

Branches

A branch is a set of git history that you can name, and switch back and forth between. When you checkout a branch, you replace all the current files with a different version of the repo. A branch is like a remote, in that it has it’s own history that can be added to and can differ from other branches. Each copy of the repo can have any number of branches, which can be pushed and pulled to other copies.

This can be a hard concept to grasp, but essentially branches are local copies of the entire repo in a specific state. We’ll talk more about branches below, but they allow you to isolate a set of changes (such as a copy change, new feature, or bug fix) away from the main history, so that it can later be merged back to the main history when the changes are complete and tested.

If you still don’t understand branches (or any of the concepts so far), that’s perfectly ok. GitHub does a great job of letting us focus on our work by abstracting a lot of the git concepts away with the desktop app. Branches are essential, but their use becomes more obvious once we start to work with github flow.

GitHub Flow

When collaborating with others via github, we’ll want a set of easy to understand processes that will make sure we don’t break or overwrite our colleagues’ work, and allow high visibility into the changes we make. GitHub flow is a set of steps that helps us make sure we always have a stable version of the code, and it’s clear what we change when we change things.

Here’s how it works:

• You create a new branch, named after the changes you’re making.
• You edit your local copy, adding and removing things.
• You commit your changes with a message. A commit is just a set of changes (additions and deletions), with a message attached.
• Repeat steps 2 and 3 as many times as you like, adding commits (sets of changes, each set with a message about what you’re changing) to your branch
• You sync your local branch with the remote. Syncing is specific to the GitHub app, and is just the action of either creating or updating the remote branch with your local one. Because you’ll always be the only person working on this branch, you never have to worry about pulling this branch — which means that syncing is very easy. Just make the remote match your local code!
• When you’re satisfied with the set of commits you’ve made, you file a Pull Request on github.com. A pull request is another GitHub specific concept — it’s essentially a discussion thread that allows your team mates to discuss your set of changes specifically, before it is approved, and merged to the stable version of the code (which lives on a branch called master)
• Once everyone is happy with the changes, you can push the merge button on GitHub, and the changes will now be ready to deploy to your live site.
• After each PR is merged, you’ll want to sync again, because when a Pull Request is merged, the remote master branch has changes that your local master does not. In this case, the sync is performing a pull from the remote master branch to your local master branch. Because you'll never change the local master branch, this transaction will also be smooth.

Whenever you start a new branch, you’ll branch from master, meaning that you’ll be adding changes on top of the current stable version.

The GitHub desktop app is designed specifically for this flow, and makes this process very simple. Here’s what the above steps look like, using the GitHub app:

Create a new Branch — click the branch icon on the top right. Be sure that ‘master’ is selected as the branch you’re branching from.

Commit your changes — make any changes you like (add or remove files, change files), then go back to the github app. It automatically shows you what you changed. Just type in the box labeled ‘Summary’, and optionally add a more detailed description below it (this is usually unnecessary unless you’re changing a ton of stuff). Once you’ve entered your message, press the Commit button.

You’ll see the app do a nice little animation, indicating that you’ve added this commit to the history of this branch.

When you’re satisfied with this set of commits, press the “pull request” button. A drawer will slide out where you can type a description of the pull request. This is similar to your commit description, except it is usually used to describe multiple commits or a more abstract concept than the commit message. For instance, if you were fixing bug number 227, you could set the title to “Fix #227”, and the description to something like “users experienced a crash when clicking on the bubble icon. This PR fixes that crash.”.

After you’re done entering your message, click the “Send Pull Request” button. A link will show up with the URL to the pull request on github.com. Click it to go to the PR in your browser, where you can discuss the PR with your colleagues.

Teams differ at this point in terms of process, but generally someone else will be required to review your changes to decide if they need any more work or if they sufficiently complete the task they were intended to complete.

Once the review is finished, the reviewing team member will press the “Merge pull request” button, which will merge this PR to master.

This will also close this PR as completed, and you can safely delete that branch if you wish.

If you look at master now, you’ll see that it contains both the commits inside of the PR, as well as a “merge commit”, indicating that PR #1 was merged to master:

Now you can head back to your github app, and switch it back to master. Click on the branch name next to the new branch button, and select “master”:

The app is generally smart enough to automatically sync when master is updated. However, just to be sure, it’s always a good idea to hit the sync button on the top right before creating your next branch. You can also see in the history diagram that our merge commit has been added to the history.

Congratulations, you’re now ready to successfully push code using git and GitHub flow!

More resources

This is very much just the tip of the iceberg — just enough to get you collaborating. Experience is the best teacher, but reading up doesn’t hurt either. Here are a few helpful links to read once you’re ready for more.

Feel free to post questions or feedback in the comments, and I’ll do my best to help when I can!

• Try Git — this is an interactive tutorial about git on the command line. Once you’re ready to level-up to some more complex git techniques, this is the best place to go next.
• Git Conflicts — this tutorial from githowto.com is a nice primer to git conflicts, something that you’ll inevitably experience but isn’t covered in this guide. If you encounter a conflict, read this before attempting to resolve the merge, or better yet, grab a team mate and have them help you resolve the conflict.
• Introducing GitHub: A Non-Technical Guide — this book is quite possibly aimed at an even less technical usage than this blog post. If you’re interested in learning more about the features on github.com, or using github for team visibility (as a PM, for example) this book is a must-read.
• Github Flow — this is the official guide from github about github flow. It has some handy tips and an easy to follow diagram for quick reference.
• Github Flow Blog Post — this is the original blog post about github flow and the reasoning behind it. If you want to know more about why this flow exists, this is a good resource for some background.
• Official Git Website — this is a great site for reading git documentation about the git tool itself.
• Pragmatic Guide to Git (Pragmatic Guides) — Pragmatic Programmers publish some of my favorite books. This book is a purely technical guide about git — once you’re comfortable enough to move your git flow to the command line, this book may come in handy.

Originally published at jesseditson.com on September 27, 2015.