Git best practices 2016
5 likes2,709 views
This document provides best practices and guidelines for using Git version control. It discusses topics such as why version control is important, how to write good commit messages, reviewing code changes, using branches, and more. The key recommendations are to focus commit messages on the why rather than what changed, get code reviews on the master branch, and never force push to master to avoid diverging versions.
Git best practices 2016
- 1. Git best practices AKA Let's write history
- 2. Git / t/ɡɪ ”A silly,incompetent,stupid, annoying or childish person.” http://en.wiktionary.org/wiki/git
- 3. "I'm an egotistical bastard,so I name all my projects after myself. First Linux,now Git” Linus Torvalds,PC World.2012-07-14
- 4. Git popularity according to OpenHub.net
- 5. Git popularity according to Google Trends git svn
- 6. Why do we use git and version control at all? Because history matters.In societies,and in software projects too.History teaches where we came from and where we are going.
- 7. Software is built patch by patch
- 8. When a patch is committed to version control,it becomes a permanent part of history. Understanding the nature of a patch is required to make good git commits.
- 9. A patch -attributes the author -has a title -may have a message -describes the lines added,removed and modified -the change is complete and self standing -e.g.fixes a defect or extends functionality
- 10. You must master reading history before you can master writing it.If you think you can master writing history directly,you did not understand the nature of history at all.
- 11. Browsing GitHub,Gitlab,git-web et cetera is good,but inspecting your local copy directly is best.
- 13. git show e413c6e
- 14. gitk --all
- 15. gitk --all
- 16. Note the existing style.You need to write in the same language to be understood. Some universal rules apply,though.
- 17. Universal git commit rules: -Start the title line with a capital letter just like in email -Don't end with a dot -Keep title under 72 characters (the Github limit) -Title is followed by one empty line,and then comes the description -The message part contains full sentences with ending dots etc -Use imperative format (Not 'Cleaned'but 'Clean up')
- 18. Commit titles must look good in'git log --oneline' and complete the sentence'This change will..'
- 19. Focus on describing WHY the change was made. The revision history diff will always show WHAT was changed.If your code is reviewed,the reviewer will focus on judging the rationale of the WHY and compare it to the WHAT to verify that they match. If it is later discovered that your code had a bug,the contents will be updated (WHAT) but the purpose of what it does will remain (WHY).
- 20. The best and permanent place for code documentation is in inline comments.Don't repeat inline comments in the commit message. The commit message should focus on why the change was needed,while the inline comment documents the current version of the code.
- 21. Is the change related to an issue or discussion available somewhere else? Include issue numbers and URLs in the commit message. Use trigger words like "Closes #123"to enable Github to make automatic links and update issues statuses.
- 22. Work-in-progress commits Few people write the correct code in one go.Thus writing the correct git commit right away might not be possible. While developing,title the commits WIP,WIP2,WIP3 etc. When you are done,rebase and squash the changes into the final commits that constitute logical steps. git rebase -i master
- 23. Other important tools to write history: git cherry-pick e413c6e git citool git citool --amend
- 24. My favourite: git citool You can also spend all day writing code and at the end of the day save your work with 'git citool',where you can pick the hunks or lines that go together to form the commits.
- 25. Are you committing somebody else's code? Mark authorship correctly: git commit -a --author "Dieter Adriaenssens <[email protected]>" git commit --amend --author="James Cowgill <[email protected]>" git apply --author="Andreas Beckmann <[email protected]>"/tmp/andreas.patch
- 26. Branches A series of commits.The purpose of branches is to allow different versions of the software to exists in parallel. Typically there is a development master branch and a relase branch v1,which can evolve in separate directions. The master branch may become release v2 while the v1 branch may become release v1.1.
- 27. All developers branch from master and then merge back. New releases branch from master. Support releases branch from release branch. Image source: http://tleyden.github.io/blog/2014/04/09/a-suc cessful-git-branching-model-with-enterprise-su pport/
- 28. The holy master principle: Never break the master branch! All developers working to create new features or fix bugs use the current master branch as the base of their work. If the master is already broken,it will be difficult to fix the bug the developer intended to spend time fixing,or a new feature cannot be made to be functional if the starting point wasn't functional either.
- 29. Git is a distributed version control system Every copy of the repository is a branch in itself.To share branches with others before they are merged to master, label the branch with a separate name. git checkout master git pull master git checkout -b feature-automatic-renewals git citool ... git push origin feature-automatic-renewals
- 30. Apply the changes made by a collaborator: git pull http://people.debian.org/~sthibault/tmp/mariadb-10.0 feature-hurd After this your feature-hurd branch will have the same contents,and you can continue improving it. Many prefer to publish and pull via GitHub,but any server you can push files on with SSH and pull via SSH or HTTP will do.
- 31. The holy QualityAssurance principle: all commits on master should go via review GitHub "Pull Requests"facilitate this. Gerrit and Gerrithub for more formal teams.
- 32. Review principles: -Give feedback,even nitty gritty,to perfection the code (and documentation!). -Let the submitter fix it themselves,thus keeping authorship and commitment to maintaining the code. -Reviewing as an opportunity to learn.Both for the reviewee and reviewer!
- 33. Review stalls (often,unfortunately): -Reviewer does not agree on the motivation to the change -Reviewer does not understand the contents of the changes -Poor documentation,unlogical commits -Lack of QA,no testcases,no external verification -Unfit change for the upcoming release,lack of time, wrong reviewer
- 34. The holy history principle: never force push on master Except if you are really quick and sure that nobody made a git pull in between. If the rule is broken,developers and systems will have diverged versions of master,and everybody will need to do manual merges or dangerous force pulls.
- 35. Remember: good outcomes require a lot of work Don't feel frustrated.The devil is often in the details and the nature of high quality code and reliable systems require diligent review. All big stable systems grew our of very small stable systems. Do not sacrifice stability for development velocity, otherwise it will just collect debt and require twice as much work later and grind development velocity to a full stop.
- 36. The hotfix principle If you have blinking lights and sirens yelling, you can and should do whatever you need to.
- 37. Beginner tips Learn the basics: http://try.github.com/ SSH-keys: https://help.github.com/articles/generating-ssh-keys/ Keep branch name visible in the bash prompt: https://github.com/ottok/tooling/blob/master/bashrc/bashrc.git
- 38. Contact Seravo if you need experts in Linux,Git or other open source software Open seravo.fi See our blog for in-depth tips