Best Practices for Working with Git
Introduction
At its simplest Git is a tool for simply checking in files seeing the changes and making sure you know what changed. It can be so much more when you are collaborating. Its a story or history of events that helps future generations understand the what, why, where and how of a solution. Its not uncommon to see a piece of code that is causing problems and thinking who is the idiot who wrote this, and then discover that it was you!
You can make it easy or hard to understand. I like to think of a package of code you work on as a story. The commits you make are each chapter titles that that explain what is happening in that chapter. Together the chapters tell the reader how you got things done in digestable chunks.
Who are we thinking about when we write code
Computers and Automated Systems
Normally when we commit code we want it to be executed by the machines and do something.
Code Reviewer
When we write things we make mistakes, or make things more complicated than they need to be. When we write code and commit it if we keep the code reviewer in mind we get better code reviews.
Separate Machine Generated Code and Human Customization
It's pretty commmon place to run a command to generate a project or template. Such calls may generate dozens of files. If that is the case then commit them all in a single commit. The message could be Autogenerate code by running tools x.. It tells the reader that there is nothing special here that you may have messed up yet and they can likely skip over this complex set of files.
When you start to customize the files with your own changes those should be separate commits so that the reader can see how your changes overlaid atop the template. If you combined them into a single step that informaton would be lost. The reader wouldn't know where the autogenerated code stopped and where your custom code began and therefore would need to read it all. OUCH!
Break Your Work into Clear, Understandable Commits
People can only process so much information at a time. If you give someone a commit with 10,000 lines of changes good luck getting them to understand it. Just like breaking up machine and human code helps. If we can provide smaller chunks people can go through them 1:1 and understand what is happening. They can visualize how you are building from foundational commits.
Why It Matters
Breaking your work into clear, understandable commits helps maintain a clean project history. It makes it easier for others (and your future self) to understand the changes made and the reasons behind them.
How to Do It
- Single Responsibility: Each commit should have a single responsibility. Avoid bundling multiple changes into one commit.
- Descriptive Commit Messages: Write commit messages that clearly describe what the commit does. Avoid vague messages like "fix" or "update".
Example
#### Good commit message
git commit -m "Add user authentication feature"
#### Bad commit message
git commit -m "Misc changes"Don't commit things that robots can generate
When we are developing we typically use package manager tools like NPM, Composer, Go Packages, Terraform Plugins, etc. Running a command like npm install may install tens of thousands of files. Commiting them is a headache. Patching them is a nightmare. Which ones have patches applied? Which ones need them? How do I code review it?
Instead commit the manifest file which includes your patches along with any lock file. Any changes to those 2 files are typically pretty easy to follow and review.
Then use a CI/CD system like GitHub Actions, Circle CI, or TravisCI to run npm install for you and build a deployment artifact with your custom code AND the robot downloaded or compiled pieces!