Git is a powerful, critical, yet poorly understood tool that virtually all Open Source developers use. One of the key features that git provides is a powerful and comprehensive log that displays the history of all the changes that have happened in a project, including potential developments that weren't ever merged, details about former versions of software that can inform future development, and even such mundane details as whether development on feature A started before or after development of bugfix B.
Despite the power and utility of git's log, few developers take full advantage of it. Worse, some common practices that developers have adopted in the name of convenience (or just plain cargo culting) can actually destroy this useful information. Moreover, if developers are following the common exhortation to "commit often", they may end up with logs full of uninteresting noise, as all the details of debugging attempts and experiments are inadvertently recorded.
This talk will:
* detail the potential benefits of having informative and well structured logs
* discuss common developer habits that can make logs less useful
* explain techniques to preserve informative development history
4. In my day job, IΚΌm the VP of Technology for Infinity, a small
IT consultancy.
vp, technology
inο¬nity
interactive
4 β Logs Are MAGIC β OpenWest 2017 β @genehack
5. I wanted to give this talk because I love revision control. IΚΌve kept my home directory under
revision control for over a decade, I maintain a Perl git wrapper module, and I wrote this thing
called GitGot to automate batch ops across multiple Git repos (but thatΚΌs a different talk)
i β€
revision
control5 β Logs Are MAGIC β OpenWest 2017 β @genehack
7. I liked SVN a bit more...
svn7 β Logs Are MAGIC β OpenWest 2017 β @genehack
8. Hell, I even liked RCS
rcs8 β Logs Are MAGIC β OpenWest 2017 β @genehack
9. Actually, thatΚΌs a lie -- I donΚΌt think
anybody liked RCS.
Anybody here remember RCS?
Anybody still using RCS?
rcs9 β Logs Are MAGIC β OpenWest 2017 β @genehack
10. And now we have git
git10 β Logs Are MAGIC β OpenWest 2017 β @genehack
11. I love git. Git makes me happy
i β€ git
11 β Logs Are MAGIC β OpenWest 2017 β @genehack
12. How many people have used git at least once?
How many people feel comfortable in git?
How many people would call themselves git
βexpertsβ?
quick
poll!
12 β Logs Are MAGIC β OpenWest 2017 β @genehack
13. So, if youΚΌre not at least a little familiar with git, this talk is probably not going to that
interesting -- most of the stuff IΚΌm going to talk about does apply to all revision control
systems, but my examples and recommendations are all git-based
what this
talk isnβt13 β Logs Are MAGIC β OpenWest 2017 β @genehack
14. IΚΌm also not going to be claiming to dispense any universal
truths in this talk...
no
universal
truths14 β Logs Are MAGIC β OpenWest 2017 β @genehack
15. IΚΌm not even going to try to convince you that anything IΚΌm telling you is a βbest practiceβ.
Pretty much anything I advocate in here, IΚΌm sure people will be able to come up with an
example where IΚΌd say, βyeah, for that, donΚΌt do itβ
not even
βbest
practicesβ15 β Logs Are MAGIC β OpenWest 2017 β @genehack
16. So what is this talk about then?
what this
talk is16 β Logs Are MAGIC β OpenWest 2017 β @genehack
17. Opinionated commentary on some aspects of using
revision control systems...
some
opinions
17 β Logs Are MAGIC β OpenWest 2017 β @genehack
18. ...based on things IΚΌve seen over the past mumble years making
extensive use of revision control on personal, open source, and
commercial software projects
photo modified from http://i2.kym-cdn.com/photos/images/original/
001/044/247/297.png
backed up with
experience
18 β Logs Are MAGIC β OpenWest 2017 β @genehack
19. Some of this stuff may be more important for larger projects
with multi-person teams ...
maybe more
important for
larger projects
19 β Logs Are MAGIC β OpenWest 2017 β @genehack
20. ...but itΚΌs also important if youΚΌve just started a project that youΚΌre thinking might grow into
something bigger. Having a solid project history from the get-go can make it a lot easier
for contributors to come on board and start pitching in
but also good for projects
that aspire to be
bigger20 β Logs Are MAGIC β OpenWest 2017 β @genehack
23. Eventually weΚΌre going to talk about how to make better use
of the history in your repos ...
making better
use of history
23 β Logs Are MAGIC β OpenWest 2017 β @genehack
24. ...but first, weΚΌre going to talk about ways to make better
history
making
better
history24 β Logs Are MAGIC β OpenWest 2017 β @genehack
25. For all these things, there are a few common elements
prerequisites
25 β Logs Are MAGIC β OpenWest 2017 β @genehack
26. For maximum value, youΚΌre going to want to apply them
consistently
consistency
26 β Logs Are MAGIC β OpenWest 2017 β @genehack
27. Make them into habits
habits
27 β Logs Are MAGIC β OpenWest 2017 β @genehack
28. TheyΚΌre pretty much all the type of thing that if you do them
all the time...
do it all
the time28 β Logs Are MAGIC β OpenWest 2017 β @genehack
29. ...you eventually will just do them without thinking too much
about it
then you
donβt have
to think
about it29 β Logs Are MAGIC β OpenWest 2017 β @genehack
30. or even better, if youΚΌre the right kind of twisted...
even
better30 β Logs Are MAGIC β OpenWest 2017 β @genehack
31. ...youΚΌll automate things. for example, i periodically run some scripts to find repos in a
βdirtyβ state, or that have local commits that havenΚΌt been pushed to a remote, and then
clean them up
automate
it31 β Logs Are MAGIC β OpenWest 2017 β @genehack
32. so, moving on to how to make better history
how to make
better
history32 β Logs Are MAGIC β OpenWest 2017 β @genehack
33. if youΚΌre going to talk about git, you almost have to talk about workflows. potentially one
of the more contentious aspects of starting a new project is deciding what your workflow
is going to be
workο¬ows
33 β Logs Are MAGIC β OpenWest 2017 β @genehack
34. workflows can range from the very simple -- just a single branch in
a local-only repo, just adding commits onto the HEAD of that branch
photo credit: modified by https://www.flickr.com/photos/appleboy/
5488984566/in/photostream/
no remote
no branches
master only
34 β Logs Are MAGIC β OpenWest 2017 β @genehack
35. or you can have that basic setup, but with a remote that you push things to every so
often. this is basically the simplest possible branching workflow -- when you have
local commits you havenΚΌt pushed to the remote yet, thatΚΌs (if you squint, a bit) a
branch
photo credit: modified from https://www.flickr.com/photos/appleboy/5488387469/in/
photostream/
local master
no branches
& periodic pushes
35 β Logs Are MAGIC β OpenWest 2017 β @genehack
36. all the way up to fairly complicated workflows like git
flow, where you have multiple branches in flight at any
given point.
anybody using git flow, or anything equivalent?
photo credit: https://www.flickr.com/photos/appleboy/
5488984404/in/photostream/
git ο¬ow
36 β Logs Are MAGIC β OpenWest 2017 β @genehack
40. this is basically doing extra work to mimic what a fast
forward merge probably would have done
rebase
before
merge40 β Logs Are MAGIC β OpenWest 2017 β @genehack
94. you need to include the branch name here so that once the branch
has been deleted, you'll still be able to tell what the branch name was
maximal
historical
information94 β Logs Are MAGIC β OpenWest 2017 β @genehack
133. (at the end)
133 β Logs Are MAGIC β OpenWest 2017 β @genehack
134. less than 80 chars
git's idea of a commit message was modeled on an email message
the first line of the commit is the subject of the message. just like
you can occasionally get away with sending an email message
with only the subject line filled in, and a completely blank body,
you occasionally have a git commit that doesn't need much more
than that. a whitespace cleanup commit is a good example
keep the
subject
short134 β Logs Are MAGIC β OpenWest 2017 β @genehack
135. most commits, however, deserve at least a paragraph of body text in the commit message. depending on exactly what work
you di, what decisions you made, etc., influences how much you might want to put in there. good things to include may be
benchmarkign work you did to decide what algorithm to use, other alternative approaches you considered -- basically
anything that's going to help somebdody doing code review, or somebody staring at the commit in six months going WTAF
commit
message
bodies135 β Logs Are MAGIC β OpenWest 2017 β @genehack
136. you can customize
the template for
the commit message
136 β Logs Are MAGIC β OpenWest 2017 β @genehack
137. if you get to this point, youΚΌre also going to want to script
the repo setup process
git config --local commit.template ./.template
# edit .template to add whatever you want...
137 β Logs Are MAGIC β OpenWest 2017 β @genehack
160. [color]
branch = auto
diff = auto
grep = auto
interactive = auto
showbranch = auto
status = auto
ui = auto
160 β Logs Are MAGIC β OpenWest 2017 β @genehack
161. [color "status"]
added = green bold
changed = red bold
untracked = cyan bold
161 β Logs Are MAGIC β OpenWest 2017 β @genehack
168. -w ignores whitespace
-M tracks lines moved within a file
git blame -w -M
168 β Logs Are MAGIC β OpenWest 2017 β @genehack
169. who has run git blame and found out the thing that bugged
them, they committed?
[alias]
praise = blame
169 β Logs Are MAGIC β OpenWest 2017 β @genehack
170. i will
buy
this tee shirt
hashtag justsayinβ
170 β Logs Are MAGIC β OpenWest 2017 β @genehack