Chapter 3. Managing Version History with Git

In this book, starting from Chapter 4, Setting Up Development Tools, we're going to be building a very simple user directory, which we've randomly namedhobnob. We need a way for us to keep a versioned history of our code, so that if we've made some mistakes along the way, we can simply revert back to the last known good version and start again from there. This is known as version control (VC).

The simplest way to implement version control is to copy the entire codebase into date-stamped directories; however, this is tedious and may take up a lot of disk space. Instead, we can use a Version Control System (VCS) that'll manage these versions for us. We simply have to instruct the VCS when to create a snapshot of our code, and it will keep that version.

There have been many implementations of VCS, starting in 1972 with Source Code Control System (SCCS), which was superseded by Revision Control System (RCS, released in 1982), Concurrent Versions System...

Setting up Git

First, we must install Git.

Note

Most installation instructions depend on your hardware architecture and operating system. It would be impractical for us to outline instructions for all of them. So, for this book, we'll assume you're running Ubuntu 16.04 / 18.04 on a 64-bit machine, using a user with sudo privileges. We will provide URL links to the documentation whenever possible, so that you can find installation instructions specific to your machine. However, due to the dynamic nature of the internet, URL addresses change and pages may get moved. If the link we provide appears to be dead, simply search for the instructions using a search engine.

Git is available for macOS, Windows, and Linux. You can find download instructions for Git at https://git-scm.com/downloads. Since we are using Ubuntu, the git package will be available from our distribution's package manager, Advanced Packaging Tool (APT). We should run sudo apt update to ensure that the list of repositories available...

Learning the basics

The primary purpose of Git is to keep a history of changes, or revisions. To illustrate this, let's create a simple file and commit it to the history of the repository.

Committing to history

First, let's confirm our repository's Git history by running git log, which shows a history of past commits:

$ git log
fatal: your current branch 'master' does not have any commits yet

The error correctly informs us that there are currently no commits. Now, let's create a short README.md file, which represents the first change we want to commit:

$ cd ~/projects/hobnob/
$ echo -e "# hobnob" >> README.md

We've created our first file and thus made our first change. We can now run git status, which will output information about the current state of our repository. We should see our README.md file being picked up by Git:

$ git status
On branch master
Initial commit
Untracked files: (use "git add <file>..." to include in what will be committed)
 README.md
nothing added to commit but...

Branching and merging

So far, we have been adding changes sequentially to the repository, resulting in a history with a linear structure. But what if you, or your team, want to work on different features/multiple tasks at the same time? If we continue with our current workflow, the Git commit history is going to look disjointed:

Here, we have commits relating to bug fixes interleaved between commits relating to features. This is not ideal. Git branches were created to deal with this issue.

Git branches

As we've briefly mentioned, the default branch is called master, and we've been adding commits to this branch up to this point.

Now, when we develop a new feature or fix a particular bug, rather than adding those commits directory to master, we can instead create a branch from a certain commit from master. Any new commits to these bug fix and/or feature branches will be grouped together in a separate branch in the history tree, which does not affect the master branch. If and when the fix or feature...

Releasing code

We now have a sizable chunk of features that we can release. We should create a release branch from dev. This release branch should be named after the version of the release, prefixed by release/, such as release/0.1.0. The code to be released should then be deployed to a staging server, where automated UI testing, manual testing, and acceptance testing should be conducted (more on these later). Any bug fixes should be committed on the release branch and merged back into the dev branch. When the release branch is ready, it can then be merged into master.

Note

No new features should be added to the release branch except bug fixes and hotfixes. Any new features, non-critical bug fixes, or bug fixes that are unrelated to the release should be committed to a bug-fix branch.

So, the first question is how do we name/version our releases? For this project, we'll use semantic versioning, or semver.

Semantic versioning

In semver, everything is versioned with three digits, MAJOR.MINOR.PATCH...

Hotfixes

The last thing we need to cover for our Git workflow is how to deal with bugs we discover in production (on our master branch). Although our code should have already been thoroughly tested before being added to master, subtle bugs are bound to slip through, and we must fix them quickly. This is call a hotfix.

Working on a hotfix branch is very similar to working on a release branch; the only difference is that we are branching off master instead of dev. Like with release branches, we'd make the changes, test it, deploy it onto a staging environment, and perform more testing, before merging it back into master, dev, and any current release branches:

So, first we make the fix:

$ git checkout -b hotfix/user-schema-incompat master
$ touch user-schema-patch.txt # Dummy hotfix
$ git add -A
$ git commit -m "Patch user schema incompatibility with social login"

Then, we merge it into master:

$ git checkout master
$ git merge --no-ff hotfix/user-schema-incompat

As we have added something new to...

Working with others

So far, we've outlined how to manage our Git repository when developing by ourselves; however, more often than not, you'll work as part of a team. In those instances, your team must work in a way that allows your colleagues to get the updates you have done, as well as update others on their own changes.

Fortunately, Git is a distributed VCS, which means any local repository can act as the remote repository for someone else. This means your colleagues can pull your changes onto their machine, and you can pull their changes onto yours:

 

 

However, this would mean you'd have to pull from everybody's machine regularly to get all the latest changes. Furthermore, where there are merge conflicts, one person might resolve them differently to another.

So while it is technically possible to follow this distributed workflow, most teams elect a single repository that they consider to be the central one.

 

By convention, this remote repository is called origin:

When you want to update your...

Summary

In this chapter, we outlined how to manage your project's version history using Git. We started by understanding the different states in Git and practicing some basic Git commands, and using them to commit, branch, and merge our changes. We then set up a remote repository on GitHub, which allowed us to share our code and collaborate with others.

The workflow and conventions used here are opinionated, and you may come across different patterns in your workplace. There is no right way to use Git, only wrong ways, and the rules we used here are not perfect. For example, in the Driessen model, once a feature is merged into dev, it will be hard to extract it. Therefore, we have to be careful not to merge in features that are not meant for the current release. Therefore, the most important takeaway from this chapter is to establish a set of conventions with your team, and stick to it consistently.

In the next chapter, we will start writing our first lines of code, setting up our development...