How to not f- up your local files with Git part 2

This article is a continuation of part 1, while you can learn and enjoy this one without reading the first, I recommend you to take a look back on the etiquette of branches and workflow as I’ll use the same concepts from the first one.

Scope of this article

Commits are the bread and butter of Git and Github, they organize all your code, you should make them easy to understand for other developers so they can see what you changed and how the project and your code is progressing.
Part 2 will focus on commits etiquette and how to manage pushes and pulls.


As before, we will just use the Git client and Visual Studio Code for the awesome Git integration.


First of all, what are commits used for? They save code, that’s kind of right but they do far more than that: Commits organize your code into small bits that can be easily understood and categorized.

Good developers use commits after they have been published to understand how things have been done and which files were modified. Think of your application as a really good book.

Chapters are the equivalent of commits (kind of, not literally) if you want to know where in the book Alice falls into the rabbit hole you will find that it does so in the chapter called “Down the Rabbit-Hole”, your commits should follow the same rules.

The labyrinth of intricate and non-descriptive commits no one wants to deal with.

What should a good commit contain

The single most important thing about commits is what they contain. As simple as this may seem it’s often hard for developers to follow.

You fix some grammar on the FAQ while you are working on your react navbar component? Put that into it’s own commit. The previous article explains how to save single file into a commit with VSCode.

Every commit has a theme, you have to remember that commits get used a lot. To make yours and everyone else job easier you need to make them small with only “one” kind of change. For example, changing React.PropTypes (react < 15.5) to prop-types (react ≥15.5) for 5 different files can be only one commit, but if you want to change a Redux action that’s another commit, don’t mix different things.

With this method you will have far more commits and they will all be meaningful, you can boast your git contribution while being praised as a good dev, isn’t that awesome?

Commit title

$ git commit -m "Fix case sensitivity for email input"

Capitalize the first letter not much to explain, Grammar 101.

Under 72 chars and around 50 average you don’t want your commit message to be broken into two parts (the famous three dots). This is how good commits present themselves.

Don’t do this!

Keep it short and clear this means that your commit text should be a brief explanation of what it does, the commit above is neither clear nor short, it contains a fix for a route with /:username being evaluated before /logout, this meant that it always considered logout to be a username and it tried to retrieve a profile from the database called logout. A simple issue of routes priority. What would be a better name for this commit?

$ git commit -m "Fix routes priority"

Short and straight to the point, if you want more information about what the commit does, you can open up the commit and inspect the changes in the code, it is a good habit to have as you grow as a developer.

But I want to be more specific than that in my commit, how can I do it in 50 chars?

Commit body

There is not much to say about this, the commit body can be as descriptive as you want but remember it should describe the code, not be a substitute of it.

Luckily there’s an easy and fast way to write body messages from the console without using vim that everyone loves.

$ git commit -m "My commit title" -m "My commit body message"

Commit using VSCode

This is mostly taken from the previous article, if you are interested on how it works in detail please have a read.

Once you have staged your changes from the sidebar source control tab just add a title and save the commit.

Just click the V and you are done.

It is useful to keep you focused on the editor while doing a big job as you can keep modifying your code while you commit it as you progress.

How to push your awesome commits without destroying everything

This section uses and requires you to follow the etiquette set in the previous article to fully understand it’s content.

Now we have perfect commits in our perfect branches, how to we push all this awesomeness?

Let’s set some habits.

After you finished working on your code you should always update your branch from the base branch it was based on. My routine usually is as follows:

// we start from branch fix/my-branch
$ git checkout development
$ git pull
$ git checkout fix/my-branch
$ git merge development

Let’s explain in details what is going on here.

First of all git pull does the same as git fetch + git merge and this comes with less control and more side effects, we will not go into details here, I prefer to use both methods and here’s my reasoning.

The development branch purpose is to serve us as base for all the other branches we create to write new code, it is clean since before merging the working branches you and your team will have extensively tested them.

Since you are not working on the development branch it is always clean. We can use git pull without worrying about side effects. Keeping this branch updated frequently will be helpful to reduce the number of merge conflicts in the new branches you create.

Once updated we can switch to our working branch, merging from here should almost always be safe if we follow the git etiquette.

If merging goes without issues

Just push your working branch and make a pull request against development, wait for a review (and this is when your commit etiquette will shine since your fellow developers will be able to review your changes better, faster, and painlessly.

After merging your request and follow the standard etiquette from there, you are done, give yourself a pat on the back!

If merging encounters conflicts

I know, I know it happens all the time.

It’s not hard to solve. Trust me! Let’s start from the beginning and do it manually to make sure everything is working as intended. Since we do not build production on these branches and every branch targets a specific area our conflicts will always be small and easy to solve.

Goddamit git, why?

As you can see the console already helps us by giving us the name of the file where conflicts have occurred, let’s open that file.

Visual Studio being helpful as always.

This is what we see on Visual Studio opening the “corrupted” file, lets start from the left sidebar.

( C ) ← in purple tells us which files have conflicts (we can see this on the console too but here is easier to visualize).

On the file itself there is the conflict, in this example it is a simple text change that identifies clearly where these changes comes from. The top part is the current working branch while bottom is development.

You can choose which one to accept by using the handy menu over the conflict itself or manually delete the old code and keep the new.

Once you resolved all the conflicts commit the result. If you want to test it again just run the above commands to pull and merge from the development branch again and once you are sure there are no more conflicts just push the branch and pull request against development branch, voilà you are done!

Conclusion or TLDR

Make good commits, boast your commit history, be the developer everyone loves to review, don’t fall victim to conflicts, drink at least 6 glasses of water every day and go for a walk every once in a while.

You can find part 3 of this series here and if you havent read the first one, you can read it here.

Javascript developer @streamroot