.git-commit-template

# If applied, this commit will...

# Why is this change needed?
Prior to this change, 

# How does it address the issue?
This change

# Provide links to any relevant tickets, articles or other resources

README.md

Git Tips

If you haven't used git before (or any distributed source code management tool) then you should start with a tutorial, for instance: https://try.github.io/levels/1/challenges/1

Tip: Use a git commit template

Take some time to think about what consitutes a quality commit messages:

• https://chris.beams.io/posts/git-commit/
• https://wiki.openstack.org/wiki/GitCommitMessages
• https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/

Download this template and place it in a config directory within you home directory: .git-commit-template

To install the template:

git config --global commit.template $path-to-git-commit-template

Sticking to the simple guidelines in this template will dramatically increase the quality of your commit messages (worked for me and my team). A good commit message can make a world of difference when trying to understand a piece of code (even if your the original author)!

Also, in go projects consider: https://github.com/edsrzf/gofmt-git-hook

In NPM projects consider adding the code coverage report to the message template with a prepare-commit-msg hook:

#!/usr/bin/env bash
 
COMMIT_MSG_FILE=$1
COMMIT_SOURCE=$2
SHA1=$3
 
case "$COMMIT_SOURCE,$SHA1" in
 message,)
    env npx nyc npm test && ( ( echo; env npx nyc -r text-summary report ) >> "$COMMIT_MSG_FILE" )
    ;;
 ,|template,)
    COMMIT_TPL_FILE=$(env git config commit.template)
    LINE_COUNT=$(env wc -l < "$COMMIT_TPL_FILE")
    env npx nyc npm test && env sed -i.bak ${LINE_COUNT}r<(env npx nyc -r text-summary report) "$COMMIT_MSG_FILE"
    ;;
 *) ;;
esac

Tip: Always work from a branch

Avoid pushing to a branch that someone else is working on by creating a branch; really, it's just common decency. Working from a branch that you own affords you the luxury of pushing early. Don't be afraid push 'WIP' commits (they can always be squashed later on and/or removed with a force push) as they provide extra transparency for the rest of the team.

Branch naming conventions

When naming your branch use a multiple segments separated with a forward slash, with the following segments:

• An optional single word category, in lowercase, e.g. experimental, release, hotfix, etc.
• The issue reference (if known)
• A short (3 to 5 word) summary of the issue, in lower kebab case.

Examples:

fix/116/introduce-crypt-service
experimental/glorious-new-feature
release/0.6.0

Use rebase workflow

It is a personal preference of mine to rebase branches as opposed to merging them. This leads to a cleaner history and is easier to use in the long run; it places an emphasis on logical order over chronological order. For some background to rebasing, read: https://www.atlassian.com/git/tutorials/merging-vs-rebasing. If you've had bad experiences with rebasing in the past take a look at this post: https://nathanleclaire.com/blog/2014/09/14/dont-be-scared-of-git-rebase/. If you like you can make it the default: https://coderwall.com/p/yf5-0w/like-git-pull-rebase-make-it-default

git config --global branch.autosetupmerge true
git config --global pull.rebase true

The above will not effect existing cloned repositories.

Tip: Use describe --dirty

The describe subcommand is very useful for tagging docker images or producing version strings, but be sure to use the dirty option. In particular if you are on a different branch to the branch of the closest tag then git will consider your tree as dirty (because it's not mainline). So consider using one of these bash commands to describe your working tree:

git describe --dirty=-$USERNAME
git describe --dirty=-$(git rev-parse --abbrev-ref HEAD)
git describe --dirty=-$(git rev-parse --abbrev-ref HEAD)-$USERNAME