Skip to content

Instantly share code, notes, and snippets.

@letanure
Forked from dmglab/git_bible.md
Created January 31, 2017 10:48
Show Gist options
  • Save letanure/cf1289eedaf1fff3d8387daf4f291d9f to your computer and use it in GitHub Desktop.
Save letanure/cf1289eedaf1fff3d8387daf4f291d9f to your computer and use it in GitHub Desktop.
how to git

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

allowed prefixes

  • feat (feature)
  • fix (bug fix)
  • hotfix (workaround)
  • docs (documentation)
  • style (formatting, missing semi colons, �)
  • refactor
  • test (when adding missing tests)
  • chore (maintain)
  • improve (improvement, e.g. enhanced feature)

How to commit on your own branch

How to keep your branch up to date

initial situation

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 git pull

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.

initial situation

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

Use following template (source for further reading):

<prefix of your branch>(<scope>): <subject>

<body>

<footer>

the scope

try to get a feeling for scopes in your awesome software project. if you need some inspiration:

  • init
  • config
  • frontend
  • backend

the body

  • 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

the footer

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.

troubleshooting

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


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment