git best practices

img
We said #git, then. How to use git as efficiently as possible in #modernhw ? We know the answer, using a front end. Right, but then ? Following a set of simple principles and best practices that will make your life simpler. Follow me on this trip.

read a couple of good references

Pragmatic Version Control Using Git, Version Control with Git, 3rd Edition and Pragmatic guide to git are good examples, but there are many more around. Use them as a reference and as a starting point, and try to go beyond following your needs.
Check the official doc. And remember you have man git-log, man git-config, etc. at your disposal.

use a front end

Yes, again.
Avoid the #cli. And try to make your text editor and your front end as good friends as possible.

coding

Format your code properly, otherwise, diffing becomes useless, and your code diffs will be hidden by formatting diffs. Even worst, people you collaborate with will be unable to read your history. Comply to language standards.

changes

If possible, ask your text editor to have some kind of visual hints on what you have changed, added or removed.
Learn how to inspect diffs between working copy and staging area, between working copy and last commit, and the contents of a commit. Learn how to discard changes.

commits

Commits are lightweight diffs. A commit has one or two parent commits, and is identified by a unique hash.
Stage your changes first, commit them then. Learn how to stage chunks of changes, not all of them.
Remember to commit early, commit often: git is a CVS, not an archival, not a backup system. Never commit binaries (except artifacts: pdf, etc.).
Authentify who authors your developments and gpg-sign your commits.
Group changes in meaningful commits, and remember git history must be read as a novel: write meaningful commit messages. Consider that people spend much more time reading git history than writing it.

branches, tags and releases

A branch is a pointer to a commit, and if your remove the pointer to a commit, you won’t be able to access it anymore. Branches are free (as in beer !), so branch as much as your need.
Tags are fix pointers (labels) to commits (aliases) They identify stages, or important hints in development.
Remember to always store your work hash/tag along with your results, you’ll know what you’re doing, you’ll know which version of your submodules you’re using, and you’ll be able to compare your results.
Releases are numbered tags, identifying accomplishments. Be familiar with semantic versioning
Before merging branches, understand the differences between fast-forward (advance the pointer) and non fast-forward (keep branch history in a feature branch). And learn how to resolve merge conflicts with your frontend !

logs

Check frequently where you are in the log history, you may get backwards in history by just moving a pointer.
Learn to search (and filter searches) in the log messages

workflows

Remember local is decoupled from remote, and that git doesn’t impose any workflow, so everything is possible.
Learn the advised workflow in collaborative development: gitflow, and consider merge / pull requests are just artificial standards of a #gitforge.
At a minimum, use:

main, stable branch (releases only)
devel, working branch (commit here)
feature, topic-specific branch (spin-off)

locally

Everything may be fixed while working locally.
Use .gitignore., locally at $GITDIR/info/exclude and at global level at ./.gitignore. For lazy people you have gitignore.io
git-config your environment before anything else, globally at ~/.gitconfig, at project local at $GITDIR/config.
You’ll find more details about all the previous here.