Git-ting it Right : Best Practices for your Git Repository
27 June, 2020 - 5 min read
Over the years, I've worked on multiple software development projects, consisting of anywhere from 2 to over 30+ active software developers working on the same repository. It takes very little time to go from wonderfully written code to an absolute wreckage - both in terms of your code base and your repository.
In this article, I dive into some git best practices that I've learned on the job and actively use while working. I expect this list to grow and I'll add those points as and when I can.
1. Use multiple branches
There are few very reasons to exclusively use the main branch. Let's see what they are:
- You're the only developer working on a repository
- You love chaos
The solution to avoiding absolute anarchy is pretty easy - use other branches.
Many organizations create the following branches apart from the ones mentioned in the Point #2:
The Main branch typically contains your code that is safe to deploy to production. You would ideally never commit directly to this branch, and code is to be only added via pull-requests here.
Development or Dev
This branch is where code that is being actively developed and worked on would reside. It may have some bugs that are being fixed. If you're working on a feature, you'd ideally create a new feature branch(more on this below) from the development branch, and merge this back into the development branch.
Production and Pre-Production
Larger companies may have a separate Production and Pre-Production/Staging branch to release their code onto internal or public networks. These are typically hooked up to plugins that automatically deploy your code when a new commit is made.
Similarly, the Test branch may be used for releases onto a test network or test devices.
2.Follow a Branch Naming Convention ( and stick to it )
As your product grows, you're going to want to add new features and in the process fix bugs in your code. Some of these bugs will have your team on their toes.
It's important to distinguish what kind of code you're merging into your working branch, primarily to allow you to track changes in the future. This is where branch naming conventions help.
I typically use these three the most, but I've also seen some teams use the test branch for any QA or review related purposes.
Let's say you're working on a sparkling new feature to allow users to save a post they see on their feed. You can name your branch along the lines of :
feature/save-post-from-feed feature/save-newsfeed-post feature/what-does-the-feature-do
While there's nothing stopping you, I'd refrain from naming it along the lines of:
Using just verbs with hyphens helps easily read and understand the task being carried out.
Let's say you're fixing a bug that isn't extremely crtical. The feature you built to save a post has an issue with the button and you're working on a fix. With Bugfixes, I personally like to reference the issue number on the repository to see a detailed explanation of what is being fixed.
bugfix/button-change-for-save-post-#388 bugfix/save-post-#388 bugfix/what-does-it-fix
Don't forget to write in the pull-request, what your fix does.
Finally, for those fixes that are absolutely critical in terms of their severity and need to be fixed immediately, you would use the hotfix branches.
Using these distinctions allows for some traceability when working on a larger code base.
3. Write Commit Messages (or atleast try)
Okay, we've all been guilty of this. Especially when it is 3am, and you honestly don't care what the commit message says. Don't forget to add a commit message that covers the important information. Here's a sample
git commit -m "Moved chartData from Statistics.js to Redux Chart State"
You can also link issues to pull requests with your commit message. I'd highly recommend this link on linking a pull request to issues.
4. Use Commit Hooks
If you aren't familiar with what commit hooks are, that's not a problem. Think of them as scripts that run before, during or after you perform any function with git.
There are a couple of use-cases for running commit hooks
- You want to automatically indent your code before a commit is made
- You want to check for code quality before a pull request is made
- You want to send an email after a pull request is made
I personally use pre-commit hooks the most to automatically format and indent my code with a lot of help from husky. If you'd like to learn more about commit hooks, I'd recommend checking out Git Hooks.
5. Automate your Deployment
Continuous Integration/Continous Delivery(CI/CD) is a topic in itself, but setting up a workflow that let's you write code and at the push of a button deploys to a server of your choice is an incredible feeling.
For this website, I use Netlify to automatically build my website the moment a new commit is pushed to my Main branch. All Netlify requires is access to your repository and a few more instructions regarding which build command to run and what directory to serve from. For larger projects, you definitely want to check out Docker and a tool like TravisCI or CirleCI.
And that's about it!