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
infinity
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
workflows
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 flow
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
95. to review
95 — 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