The document discusses 5 principles for managing complexity in git commit histories: 1. Make atomic commits that are self-contained and focused on one change. 2. Write good commit messages with a short title, description of the change, and context for why it was made. 3. Revise commit history before sharing using rebase to clean up and reorganize commits. 4. Use single purpose branches to isolate different pieces of work. 5. Keep the commit history linear by rebasing and merging with --no-ff to make the history easier to follow.

1. Telling stories through your
commits
BY JOEL CHIPPINDALE AT LRUG IN JANUARY 2015
CC BY-SA 4.0

2. Not about Ruby

3. Not even about git

4. Managing complexity
by Cory Doctorow (CC BY-SA)

5. Your commit history is…

6. Kept forever

7. Always up to date

8. Searchable

9. $ git log --grep='Commit contents'

10. $ git log -S 'Diff contents'

11. $ git blame

13. “Every line of code is always
documented”
- Mislav Marohnić
from http://mislav.uniqpath.com/2014/02/hidden-documentation/

14. 5 Principles
by Umberto Rotundo (CC BY)

15. 1. Make atomic commits
by lupusphotos (CC BY)

16. $ git log --shortstat
commit: [REDACTED]
Author: [REDACTED]
Date: [REDACTED]
bug fixes and wp 4.0.1 update
1377 files changed,
175405 insertions(+),
248 deletions(-)

17. What if this commit had
been split up?

18. 21dfe89 Fix category page redirects
e275479 Fix deletion of author avatars
d824e02 Fix H2 headers on mobile
f8e36d4 Fix footer floating bug
d972537 Fix blog author avatar upload
d26e788 Remove unused author pages
7b91091 Fix blog feed
2f05036 Fix mixed content warnings
ed21e18 WordPress 4.0.1 update

19. Minimum viable commit

20. Avoid ‘and’ in commit messages

21. Make atomic commits
so that you can
make sense of your commits

22. 2. Write good commit messages
by Ginny (CC BY-SA)

23. What does good look like?

24. Short one line title
Longer description of what the change
does (if the title isn’t enough).
An explanation of why the change is
being made.
Perhaps a discussion of context and/or
alternatives that were considered.

25. Short one line title
Longer description of what the change
does (if the title isn’t enough).
An explanation of why the change is
being made.
Perhaps a discussion of context and/or
alternatives that were considered.

26. Short one line title
Longer description of what the change
does (if the title isn’t enough).
An explanation of why the change is
being made.
Perhaps a discussion of context and/or
alternatives that were considered.

27. Short one line title
Longer description of what the change
does (if the title isn’t enough).
An explanation of why the change is
being made.
Perhaps a discussion of context and/or
alternatives that were considered.

28. Short one line title
Longer description of what the change
does (if the title isn’t enough).
An explanation of why the change is
being made.
Perhaps a discussion of context and/or
alternatives that were considered.

29. Correct the colour of FAQ link in course notice footer
PT: https://www.pivotaltracker.com/story/show/84753832
In some email clients the colour of the FAQ link in the
course notice footer was being displayed as blue instead of
white. The examples given in PT are all different versions
of Outlook. Outlook won't implement CSS changes that
include `!important` inline[1]. Therefore, since we were
using it to define the colour of that link, Outlook wasn't
applying that style and thus simply set its default style
(blue, like in most browsers). Removing that `!important`
should fix the problem.
[1] https://www.campaignmonitor.com/blog/post/3143/
outlook-2007-and-the-inline-important-declaration/

30. Write good commit messages
(including why and the context)
so that you can
make sense of your commits

31. 3. Revise history before sharing
by hoodedfang (CC BY-NC)

32. $ git rebase --interactive

33. Remove, reorder, edit,
merge and split commits

34. 324d079 Fix typo in "Add Foo"
ab2189d Remove Bar
2a11e7d Add Foo

35. $ git rebase --interactive master

38. 1bd241c Remove Bar
773e345 Add Foo

39. Rewrite history before sharing
so that your collaborators can
make sense of your commits

40. 4. Use single purpose branches
by Jon Bennet (CC BY)

41. When you take a diversion
move the work off the branch

42. Use single purpose branches
so that you can
make sense of your current work

43. 5. Keep your history linear

45. Rebase before you merge

47. $ git merge --no-ff

48. Keep your history linear
so that you can
make sense of it

49. 1. Make atomic commits
2. Write good commit messages
3. Revise history before sharing
4. Use single purpose branches
5. Keep your history linear

50. by beglen (CC BY)

51. Questions?
@joelchippindale
joel.chippindale@futurelearn.com
futurelearn.com/blog
CC BY-SA 4.0