Note: this is a summary of different git workflows putting together to a small git bible. references are in between the text
How to Branch
try to keep your hacking out of the master and create feature branches. the feature-branch workflow is a good median between noobs (i have no idea how to branch) and git veterans (let's do some rocket sience with git branches!). everybody get the idea!
Basic usage examples
- I need a new feature in my awesome software project:
git checkout -b feature-better-than-before
- I found a bug! i need 2 fix that (regular)
git checkout -b fix-weird-error
- I found a bug! i must do a workaround (hotfix)
git checkout -b hotfix-weird-error
- Let's migrate my project's awesome-lib v1 to v2
git checkout -b chore-migrate-awesome-lib
- feat (feature)
- fix (bug fix)
- hotfix (workaround)
- docs (documentation)
- style (formatting, missing semi colons, �)
- test (when adding missing tests)
- chore (maintain)
- improve (improvement, e.g. enhanced feature)
How to commit on your own branch
- Keep your first commit line short (about 50 chars)
- and the other lines, too! this will help you to improve vim
- use imperative update instead of updated
- use familiar keywords such as:
add, update, remove, fix, refactor
How to keep your branch up to date
master *---*---*---* \ my branch *---*---*
Do not merge! We hate merge bubbles
think, before you pull changes from origin or you're getting into trouble.
stop using the standardized merge strategy for
this is wrong
master *---*---*---*---* \ / my branch *---*---*
if you need an update from master or any other branch, try to rebase your branch instead of merging. try to keep your branch history separated from master, so others can easily follow one straight line of commits.
this is what we want to do
master *---*---*---* \ my branch --> *---*---*
So, if you want to pull, try
git pull --rebase
if you want to update your work with stuff from master
git fetch -a && git rebase master
use merge if rebasing is wasting too much time
if you're running into thousand of merge conflicts, try to merge, but do not merge in case of laziness!
if all hope is gone, use cherry pick as your last hope to get back to work. but use with wisdom! this is only for advanced users: further reading: cherry-pick vs. merge workflow
if you finished rebasing, push before somebody else does
if you try to push your rebased branch, your remote will reject your command, because you changed the history of your branch. you need to do a force push and this is not exactly brilliant. if other people work on that branch too, inform them about your rebase and check, before pushing. be patient to your programmer mates!
I'm done with my work
merge your stuff into master with no fast forwarding
this will force a new commit message and keep your master branch clean.
other branch *---* / \ master *---*-------*---* \ my branch *---*---*
git checkout master && git merge master feature-better-than-before --no-ff
other branch *---* / \ master *---*-------*---*-----------* \ / my branch *---*---*
How to write a merge commit
keep your first line significant! walk through the internet and look for changelogs of other software projects. keep in mind, that each changelog line is the first line of your git commit
- Keep your first commit line short
- and the other lines, too! this will help you
- use imperative update instead of updated
Use following template (source for further reading):
<prefix of your branch>(<scope>): <subject> <body> <footer>
try to get a feeling for scopes in your awesome software project. if you need some inspiration:
- includes motivation for the change and contrasts with previous behavior
- add references (e.g. comments, api, docs, etc.)
- favor classy over cute. Act more like a human
reference your issuess for your ticket system (github, gitlab, atlassin etc.)
Closes #123, #245, #992
stop signing off your commit...
...if there is no reasonable doubt of trust!
If you still want to sign off your commits please use a GPG Key to ensure your authentication.
you cannot destroy anything (if you do not remove or manipulate your .git)
if you lost one of your commits, try use
git log and find your straying commit.
if your commit is still unrecoverable, use the lost+found feature of git