After we saved a kitten by writing clean code, I’ll give you some insights on how to save a puppy by creating clean and healthy Git repositories.
All the tips that I’ll be giving can be used on both short and long term projects. These tips have been created by combining online best practices with personal experience and have delivered many healthy projects over the years.
Tip 1: Sensible commit messages
Keep your commits short and start with something that refers to a ticket in your project management system. This will allow you to have an easy reference to the related info about this commit.
For us this is JIRA, and we use the JIRA-ticket prefix in our commits. Our Gitlab is linked to JIRA and visa versa.
This has many great benefits:
- We can click in our prefix and go straight to the ticket
- In JIRA we get a list of all commits for this ticket
Tip 2: Gitflow aka ‘stick to the plan’
I won’t be giving you a full rundown on Gitflow and how it works. For that you can visit the Atlassian tutorial.
What I will tell you is that Gitflow helps you stick to the plan, regardless of how small or big your project is. By always using the same convention other people will have an easier time catching up on your code.
One of the main reasons we introduced this was to keep an overview of which code was available on which environment. We’ve all been to a point where someone wanted to do a hotfix, created a branch, deployed that branch to the production environment and never cleaned it up.We have an awesome Service and Maintenance team who take care of small requests or fixes in delivered projects. They couldn’t keep track of which project had which branch deployed and why. By introducing Gitflow we now force people to always deploy the master to the production environment AND tag the new version explaining what has been done.
Tip 3: Merge requests
Merge request aka pull requests are an easy way to let your teammates know your feature is ready. Via Gitlab you’ll be able to select the person you want to notify and choose many more options.
The general idea is to have a social moment in which you and your peers can discuss the feature and the code you wrote for it.
Another big plus is this: by always letting someone else merge your code, you divide the knowledge and responsibility concerning that feature.
Check out the Atlassian tutorial here.
Tip 4: A clean environment
To prevent a commit history like this example, you can use a range of GIT commands. I’ll dive into the 2 commands that I use the most: “Git commit –amend”and “Git rebase”
Git commit –amend
This command is an easy way to modify the last commit. This lets you combine your new changes with the previous commit instead of creating an entirely new commit.
Check out the Atlassian tutorial here.
Git rebase
Rebasing allows you to keep your feature branch in the same path as the master branch, as demonstrated below. This will prevent your branch from running away from the other branches causing enormous merge conflicts.
Check out the Atlassian tutorial here.
Heads up!
The previously discussed Git commands will rewrite Git history and could cause major problems when working with multiple people. This is because a rebased branch can’t be fast forwarded when pushed to remote as there are commits inserted in between other existing commits. Resulting in the need of a forced push to overwrite the state of the remote branch.
If someone else has pushed commits you do not have locally, you will overwrite those commits. Those commits could potentially be lost. To reduce the risk we recommend the use of --force-with-lease instead of --force when pushing. Doing this will result in an error when the remote branch has been modified by someone else and thus reduce the risk of overwriting someone else’s commits.
Avoid force pushing, but if needed, good communication is key if you work in a team and will avoid useless frustration!
Tip 5: Versioning
For versioning we use Semantic Versioning as a basic best practice.
This can be explained as followed:
v Major.Minor.Patch (Example: v3.5.2)
- Major update: This number should only change if you deem this as a new Major update for your application
- Minor update: This number can change as often as your release cycle goes. This usually contains general maintenance and other minor changes that happen as the project continues.
- Patch update: This number should only be used when a release had something critical broke and you’ve decided to patch this issue.
Below you can see an example of a project I’ve worked on. In version 3.3 we released a feature called Test module. After our Minor release for the new feature, we applied 4 patches: 1 security update, 1 privacy update and 2 hotfixes.
Pro tip:
File naming(core.ignorecase)
For some reason Mac OS has a default case-insensitive filesystem. This has caused many pains over the years.
For example: HelloController.php vs helloController.php
Both files will work fine on Mac OS, you’ll commit it and Git will say everything is fine. Once you try load the file on another filesystem you’ll get an error “HelloController.php not found”.
You can resolve this by renaming your file but Git won’t see it as a change. Why not? Because default Git is configured to ignore case-sensitivity.
You can turn this off globally by running the following command:
git config --global core.ignorecase false
File mode (core.fileMode)
While Git ignores case-sensitivity by default, it does keep track of file modes. So when you change your file permissions for whatever reason, Git will show changes although there are no actually lines changed in the files.
You can turn this off globally by running the following command:
Git config –global core.fileMode false
Grumphp
To enforce people to use our standard we use GrumPHP on all our projects. This is a tool that will run all code changes through a set of test and check if they meet the requirements you set up for the project.
Summary
You’ve made it, puppies have been saved and hopefully you’ve learned some new tips and tricks to keep your Git history nice and clean.
These are all steps we’ve learned throughout years of experience at Intracto. Not all of them might be applicable in your case but knowing they exist and what they do will help you be a better judge in the next case you have to decide on.
