_{Cover photo from Unsplash by Pankaj Patel}

Git is probably the most used source code versioning system. It's supported by GitLab and GitHub, and it's often hosted by the companies at which you work. Even if you know the Git commands, you can still end up following some bad practices. Let's see some of them.

Not Starting a Repository from the Start

Every time I start a sample project or a proof of concept, I make sure I initialize a local Git repository. It's just a matter of running a basic command:

git init

If you forget to do that, you may have the following error:

fatal: not a git repository (or any of the parent directories): .git

To fix fatal: not a git repository error message, there's no need to set up a remote URL. This is just to keep a local history (it just initializes a .git folder) to leverage all the Git advantages from day one. If the project is to be kept, I can push it with all the history included.

Committing IDE, Editor Files, or Build Files

It's common to see some editor files included at the source repositories, like .idea, .vscode, or build folders. It's not the end of the world, but it's a bad practice. Regarding editor files, it assumes everyone will use the same editor and shared configurations. Regarding build (or similar) folders, it's just "trash" because it generates a lot of noise when you're analyzing the Git history or just browsing the project in GitHub—it's like a cluttered user interface.

The source control should avoid anything that can be generated (there are exceptions like package-lock.json or go.sum files). To ignore files/folders from thereon, create a .gitignore file at the project's root and add one row per ignored file or folder. Here's an example:

.idea
.vscode
build

Committing Sensitive Data

Passwords and similar kinds of sensitive data should not be in source control because it means you're sharing them with GitHub. Even if the repository is private, it's still a bad practice.

One solution is to use encrypted files. The other is to rely solely on environment variables because passwords are a deployment concern. Using environment variables makes it easy to vary data per environment (e.g., test, staging, production). If you need to centralize the management of sensitive data, you need something like Vault (which can be integrated with your deployment process).

If you committed sensitive data without pushing it, you can amend the last commit. Remove the sensitive data and do:

git add file/with/sensitive.data

git commit --amend -m "Commit message"

If you push the commit with sensitive data, you need to rewrite the Git history.

Force Pushing

Force pushing is not recommended because someone else might have pushed some changes. If you have to do it, at least use ‘force with lease’:

git push --force-with-lease

This will ensure that the push will fail if it is going to overwrite someone else's changes. It’s a safeguard. It's also a good practice to ensure that you're only affecting the current branch when (force) pushing. You just need to do this once:

git config --global push.default current

Writing Technical Messages

The Git history can be a good source of the project's documentation. Of course, the project should not rely on it to be understood, but it can still provide valuable information. I don't like to think of too many rules when writing commit messages. Regarding the first line, besides the obvious (keep it small and concise), I only follow two essential rules of thumb.

The first rule is to always start with a verb like you were giving an order (imperative). For example "show user status", "delete feature flag", or "optimize homepage performance".

The second rule is to refrain from messages with technical things (i.e., mentioning the files or technologies). For example, avoid "add column indexes", "change input validation", "update test-users.json". Instead, use messages that speak in business/user language. For example: "enforce username validation", "add back button", "create details page", and "fix product auto-refresh ability".

In a perfect world, the commit messages are very close to the user stories' titles, which should also not be technical. In short, focus on the 'what' and not the 'how' (the 'how' is available in the committed files). A good Git history is like a story that’s easy to understand when you do git log.

Making Commits That Are Too Big or Too Small

Sometimes it's hard to define the balance of the commit size. Are 10 files too much? Are 200 added rows too much? Don't focus on the number of files or lines. Instead, focus on having an "atomic commit". What is an atomic commit? It's the smallest set of changes that makes sense for itself—it works and tests are passing.

Avoid commits that break the build or are incomplete. Even if the feature is not finished, at least the commit should be self-contained. On the other extreme, don't commit multiple self-contained changes. For example, a refactor and a feature should be kept apart, as both are supposed to be green and atomic. This rule promotes a healthy and balanced Git history. It also helps to navigate Git history.

Conclusion

The above-mentioned points include some of the most common poor habits that coders adopt, which can cause them to harm Git history. Avoiding these bad practices can promote a healthy Git repository that is easy to navigate and understand.