Table of contents

Reading Time: 4 minutes

In this blog post, I’ll be sharing with you the 10 commandments for doing GIT right. Let’s get to it!

1. The KISS principle – Keep It Simple Silly!

Commits should be small, clear and precise. For e.g., two different bugs should have two different commits. If there is a task that requires touching multiple files, break those changes into small logical commits with neat titles so that each commit has a minimum but logical file changes.

commit 96471f14d7940ce5d7bfa5f60baba4b930ad3763 Author: Pankhurie Gupta Date: Sun Jan 14 00:14:31 2018 +0530

Task-1 | Updated file2 for task-1

commit 42a181456cef548c85294cc911f2ba1710779149
Author: Pankhurie Gupta
Date: Sun Jan 14 00:13:05 2018 +0530

Task-1 | Updated file1 for task-1

2. Small conflicts daily are better than one big messy conflict at the end of the week!

Synchronization with the develop branch should be done as often as possible to avoid conflicts. For e.g., in most cases, when multiple developers are working on one repository, their branches are merged from time to time to the develop branch (refer git-flow). So when you work on a feature, you branch out from the develop branch and start working on it. But, there is a high possibility that whilst you are working on your branch, other developers also touch the same files as you, and their code gets merged to develop. So now, not only your branch doesn’t have the latest changes that are present in develop, but also, your branch is now in conflict with develop as they have different changes on the same files. Therefore, it is your responsibility that while you are working on a feature branch, keep taking a pull from the develop branch at least twice a day, and resolve any conflicts regularly if they arise, to (a) make sure your branch is up to date with the latest changes that are being committed by other developers working on the same code, and (b) avoid accumulating conflicts.

3. Each commit is a checkpoint. Keep’em error-free!

Avoid committing partial work. If the feature you are working on is quite large, then instead of committing incomplete code every day, split the feature’s implementation into logical chunks (with no compilation errors). This makes sure that if at any point in time, you trace back to a commit, you are looking at a piece of code that was working. Although, if your work is incomplete by the end of the day, do not incline towards committing it. Instead, use git stash to stash the incomplete work, and use git stash apply to get back to this work in progress when you return.

4. Test before you commit!

Resist the temptation to commit something that you “think” is completed. Test it thoroughly to make sure it really is completed and has no side effects (as far as one can tell).

5. Write clear and precise commit messages.

The commit message must contain all the information required to fully understand & review the patch for correctness. Less is not more. More is more.

Do not assume the reviewer understands what the original problem was.
Do not assume the reviewer has access to external web services/site.
Do not assume the code is self-evident/self-documenting.
Describe why a change is being made.
Read the commit message to see if it hints at improved code structure.
Ensure sufficient information to decide whether to review.
The first commit line is the most important.
Describe any limitations of the current code.
Do not include patch set-specific comments.

If there is any ticket number associated with your change, mention the same in your commit. For e.g.:

commit 85b62070db309b374a1af2b23ca5cc2a5e51ac8b Author: Pankhurie Gupta Date: Sun Jan 14 00:38:03 2018 +0530

JIRA-1234 | Service version upgraded from 1.0.0 to 1.0.1

6. Prevention is better than cure!

Don’t misunderstand version control as a backup system. Avoid relying on rollbacks and resets.

7. Think before you leap!

Check the changes before committing by hitting git diff and git status. If there are any unintended changes (like whitespace or newline) added in the otherwise untouched files, remove them. Only the files that have actual changes should appear in the output of git status.

8. Don’t ignore .gitignore!

Make sure to include all auto-generated and workspace-specific files in .gitignore. Usually, when multiple developers are working on a repository, they may have different operating systems and different IDEs. We don’t want our workspace preferences to affect another developer’s workspace preferences, right? Neither do we want to unnecessarily track the auto-generated target files. Additionally, tracking of unnecessary files may also lead to environmental issues for different workspaces.

9. Clean up the mess

Run git gc on your repository periodically. Not many developers do this, but Running this command runs a number of housekeeping tasks within the current repository, such as compressing file revisions (to reduce disk space and increase performance) and removing unreachable objects which may have been created from prior invocations of git add. It speeds up many operations and shrinks the space consumed on disk by your .git directory. And with several dozen developers working on several dozen projects each checking in 2-3 times a day, you might even want to run it nightly.

10. United we stand, divided we fall.

Agree on a Workflow. Git lets you pick from a lot of different workflows: long-running branches, topic branches, merge or rebase… Which one you choose depends on a couple of factors: your project, your overall development and deployment workflows and (maybe most importantly) on your and your teammates’ personal preferences. However you choose to work, just make sure to agree on a common workflow that everyone follows.

All the above are a must do when you are working with git-flow. Some of them, I learned the hard way! Anyway, like and share if you found this helpful. Cheers. 🙂