A Primer on Git

Published in

Around the App in 365 days

9 min readFeb 23, 2018

(From https://www.atlassian.com/git/tutorials/using-branches)

It is easy to shoot your foot off with Git, but also easy to revert to a previous foot and merge it with your current leg.
Jack William Bell

A little history first

When creating software, especially as part of a team, you need to store the source code somewhere.

People in your team need to be able to contribute to the source code, at the same time as you are, sometimes on the same files, without stepping on your toes and with the ability to revert any mistake… not easy to do without a tool!

Before version control was invented, people could put their source code on a shared network drive, make regular backups (manually or automatically), and work directly on the files there.

Soon, your development folder would look like this:

I’m pretty sure you can see how inefficient and prone to mistakes that is, and this is why, as early as 1972, Marc Rochkind invented SCSS (Source Code Control System) at Bell Labs (yet another invention from Bell Labs!).

Nowadays, the de facto winner of all the various VCS (Version Control Systems) is Git, by far.

(From https://rhodecode.com/insights/version-control-systems-2016)

Git was created by Linus Torvalds (who also created the Linux kernel), and its main benefit is that it’s distributed.

What does it mean you might ask? Well, it means that the entire source code, along with its complete history (any changes that occurred at any point in time) is stored locally on your computer. You can commit, revert, merge, all of that locally until you synchronise (or “push”) these changes to the remote repository.

It gives great flexibility and power to the developer, who can work anywhere, and doesn’t have to be connected to the Internet to commit any change or revert its code to a previous version.

Enough of history lesson for today though.

GitHub

Well not quite. Let’s have a brief history of GitHub:

GitHub is not even 10 years old, but has become the de facto solution for open source projects. Even Microsoft publishes their (1,600!) open-source projects on GitHub.

If your project is open-source and public, using GitHub is free and this is what we are going to use for our project.

Some vocabulary

To master Git, you will need to master a few Git keywords:

Commit: this is the action to store your changes in Git, so they become part of the file history. You can always revert a file to the state it was when you committed it. Usually, you commit multiple files at the same time, and provide a description (a commit message) of the changes you’ve made.
Pull: this is the action of retrieving the changes made by others on the remote repository. You do that when you want to synchronise your local code base with the latest changes other peoples in your team made.
Push: this is the opposite of pull: you will synchronise your latest commits, which were done locally, to the remote repository so other people in your team can retrieve (“pull”) them.
Clone: this is the action of copying an entire (remote, on GitHub for example) repository to your computer. This is the first step when working on an existing code base (i.e. not created by you).
Master: Git has this concept of branches, allowing people to work on different features independently without stepping on each other feet. By convention, the main branch of a project is usually called the master branch. Sometimes, the “day to day” main branch is the develop branch, and the master branch is only merged to on releases (and only contains stable code).
Branch: when working on a new feature (say you are tasked with creating a new page on some app), you will branch out of the master branch (or develop), do you work there, commit, push, and only merge back to the main branch (master or develop) once it’s all working and possibly reviewed by peers.
Fork: this is the action of taking an open-source project, and copying it into your own repository so you can start modifying it. You can now push to the forked project, now in your own GitHub account, without messing with the “official” project. If you want to contribute to the official one, which means merging your changes to it, you need to create a Pull Request which will be reviewed by the maintainers of the official project and merged by them if they are happy with the change.

You can find more definitions in this helpful glossary on GitHub.

Let’s learn the basics

This is a crash course, you’ll find a few links at the end of this article if you want to go deeper.

At this point, you should have a Git command line client installed, if you followed the previous articles on either Mac or Windows.

To make sure you do, enter the following command in your terminal:

git --version

If you get a version number, you are good to go.

Initialising a new Git repository

First, create an empty directory on your file system, cd into it, and make it a Git repository by typing the following:

git init

Working in the master branch

The master branch is, by convention, the default branch of any new Git repository.

Except for very small projects, people tend to never work directly on the master branch, only merging production-ready code to it, to ensure that the code in this branch is always in a stable state.

For this tutorial however, we are going to add some files to it.

First, we will create a new file, and add some text to it, in the root directory of the project:

The first command adds the string “Hello world” to a file named first.txt. We then display the list of files to show that this file is indeed now there.

Once we have made some changes, we need to tell Git about it, in two stages:

You add the modified files to the Staging Area, using `git add`
And then you commit all the changes using `git commit`.

On the above screenshot, we can see that when issuing the `git status` command, Git tells us that one file was modified, but is not yet tracked.

Then we add this file to the staging area, using the `git add first.txt` command, and then on trying `git status` again we can see that the file is now in the list of the changes to be committed (the staging area).

We are now ready to commit:

Committing is actually pretty easy: you call the `commit` command, and specify a commit message explaining what is in that commit (what is the reason for the changes).

Once it’s committed, your changes are safe. You can go back in time to any commit, you can make other changes, make mistakes, and be safe in the knowledge that you can always go back to your previous commit.

Branching

In a project, even when working on it by yourself, you will want to use branches.

Branches will isolate a single unit of work, a feature, while you are working on it, without impacting the main branch (master). Once your feature is complete, you can merge your branch (i.e. merge all your changes, all the commits in that branch) to the main branch.

Let’s have an example:

In this screenshot, we did a few things:

We created a branch called feature1
We called `git status`: this shows that we are still on branch master: it’s important to note that creating a branch doesn’t switch automatically to that branch.
We then switch to the newly created branch by doing `git checkout feature1`
We then list the files, they should all be there as before, when creating a new branch nothing should have changed.

Let’s now make some changes:

Here, we created a new “second.txt” file, we staged it, committed it, and switched to the master branch. As you can see, that file is gone: it was indeed created on the feature1 branch, and would not exist on the master branch.

We are now going to merge that file, this new “feature”, into the master branch:

Merging is also pretty simple, if there isn’t any conflict (we’ll come to that in a minute): you must be switched to the branch you want to merge to (master in this case), and you issue the `git merge` with the branch you want to merge from (feature1 in this case).

Let’s talk about conflicts

The previous example was pretty straightforward: if you add (or modify) a file in a branch, and that file is not changed on any other branch, merging will be automatic and simple.

Now, on a decent sized project, multiple people will work on it at the same time and could modify the same file, at the same time, on two different branches. This is when trouble happens.

Let’s see a practical example:

In the following screenshot, we will create a new branch, add a line to the “first.txt” file, commit the change, switch to master and add a different line to that same file.

Now, the feature2 branch and the master branch both have a different modification made to the same file, on the same line, with a different content.

We are now going to try and merge the feature2 branch into master.

As you can see below, Git tells us that the “first.txt” file in in conflict, and that the automatic merge failed.

If we display the content of the file, you will see the two set of changes:

<<<<<<< HEAD
Adding a conflicting line
=======
Adding a second line
>>>>>>> feature2

It tells you have to chose between two versions, the first one being the one on HEAD (which is the latest commit on your current branch, master) and the other one being the one on the feature2 branch.

To solve that problem, you’ll need to edit the file and remove everything except the lines you want to keep. Below, as an example, we are using the Vim command-line text editor, but of course you can use any text editor such as Visual Studio Code.

Once the conflicts are resolved (you can have more than one file in conflict of course), you can then proceed by adding the modified files to the staging area (doing `git add .`) and then commit.