Git best practices
Use feature branches
Develop new features in a feature branch. Once you are done, rebase the feature branch, merge it into master and delete your feature branch.
Rationale: This keeps all changes done for a feature together. For other people it is easier to cherry-picking the changes.
Meaningful commit messages
Use the first line as subject, if possible add key-words in brackets
[CMake]. Leave the second line blank and use the
following lines (3 ff) for details describing your commit.
Rationale: The first line will be shown in the Git history. Having it meaningful makes life so match easier. For merges the first lines will be used to indicate which commits are part of the merge.
Create and apply patches
Patches are a handy way to share new code or bug fixes, especially if commit rights are lacking. You can email patches to the mailing list or attach them them to GitLab issues.
- Pull to most recent version, that prevents conflicts while merging the patch later
- Commit your changes
git format-patch -k origin/masterIf necessary replace the name of the remote or branch. This will create a patch file per commit.
- Accord these patches to the developers with commit rights.
- Pull to most recent version, that prevents conflicts while pushing the patch later
git am -k <patchfile>Be aware that if the commit message starts with
[Patch]or similar, the creator of the patch omitted
-kin his command, do the same for
git amas the flags suppresses this tag. You don’t have to commit explicitly.
- Push the changes.
Do not use merge for simple commits
Someone committed while you were doing your stuff. If you want to push, Git automatically merges the new head with your changes. Please make a Git rebase first, to avoid the unnecessary merge.
> $> git commit
> $> git pull
> (ok, something changed, you have to merge and commit this merge. Now come you:)
> $> git rebase origin/master
> (merge vanishes)
> $> git push
> (et voilà, you just got rid of the merge)
Rationale: The merge is an extra commit which clutters the commit history. It makes it more difficult to follow the changes as sometimes many changes are in-between and the diff of the merge becomes large.
Use feature and private branches
The development in feature branches triggers commit emails. This way fellow developers will notice and might comment your work. Private branches are for experimental stuff. It will not bother others with commit emails but interested parties can still check it out.
Rationale: If people are aware of your development, they can join in or help you with comments.
Remove no longer used branches
As branches are a handy feature of Git, they have to be removed if the are no longer necessary. Otherwise the repository gets cluttered with dozens of outdated, bit-rotting branches. Deleting branches with Git:
git push origin --delete <branchName>
Git offers the possibility to list all branches that have been already merged:
git branch -a --merged
These branches can safely be removed. This works also for non-merged
The list of branches is cached locally and may contain outdated entries. The list can be updated by
git remote update origin --prune
Referring to a commit by its hash
All commits can be identified by a hash which is a 40 digits log hex-decimal number (contains 0-9 and a-f). You can view a commit with
git show <hash>
that gives you the commit message and the full diff. Often it is enough to shorten the full hash to the first seven or eight digits, but it must stay unique. You can check that a shortened hash is unique by
git rev-parse --short --verify <short-hash>
Rationale: The full hash is sometimes cluttered, with the first 7-8 digits everybody should be happy.