Git best practices

Always work on a feature branch

Whatever you do, always create a feature branch first.

Until you create an MR, there is no expectation that the code in the feature branch be perfect, or even work.

This means that you can't break anything by pushing a feature branch to the remote server.

On the other hand, if you work directly on the main development branch , or even worse, on the main production branch, you cannot commit until you have fully tested your changes. And until then, your code is local only, where it is not safe (see below).

Commit and push frequently

Source code is precious! Source code on your local computer is of zero value to anyone. Hard drives crash, computers get stolen. You don't want to lose several days' work (or even 10 minutes' work, for that matter) because you forgot to save your source code on the server . Source code is safe once it's on the git remote server.

It's easy enough to commit and push at frequent intervals. Since you should be working on a feature branch, there is no risk in pushing that branch to the remote server.

Rebase your feature branch

It is generally considered a bad practice to have too many commits for a given feature. The reason is that it makes the repo tree too "bushy" and can make it confusing to understand the history of changes.

Some go as far as advocating 1 single commit per ticket. In our opinion, this is too extreme, and unjustified. It is also , of course, in contradiction with the previous best practice to commit nad push frequently.

The solution is to rebase your feature branch before pushing it.

In addition, when creating your MR, specify that the commits should be squashed.

Conventional commits

The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

Examples

docs: correct spelling of CHANGELOG

fix: fix reset-password

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Use a global gitignore

Inside a repo (and even inside each directory of the repo), a .gitignore file tells git which files should not be under version control.

The repo's .gitignore file MUST not be polluted with irrelevant entries, such as those related to your OS, your choice of IDE, etc. All these should instead go into your global gitignore file.

Do NOT follow the advice from most tutorials on the web, which generally tell you to add entries such as .DS_Store (OSX only) or .idea/workspace.xml (Webstorm IDE only).

Your global gitgnore file follows the same format as the repos' .gitignore file, and should be saved under your home directory. You need to configure git to recognize it:

git config --global core.excludesFile '~/.gitignore_global'