photo: https://cdn.pixabay.com/photo/2014/10/01/17/59/
my-little-pony-468916960720.jpg
logs are magic!
john sj anderson | @genehack | openwest 2017 | salt lake city
1 — Logs Are MAGIC — OpenWest 2017 — @genehack
photo: https://cdn.pixabay.com/photo/2014/10/01/17/59/
my-little-pony-468916960720.jpg
why git workflows
& commit structure
should matter to you
john sj anderson | @genehack | openwest 2017 | salt lake city
2 — Logs Are MAGIC — OpenWest 2017 — @genehack
hi, i’m john.
a/k/a @genehack
3 — Logs Are MAGIC — OpenWest 2017 — @genehack
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
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
I liked CVS...
cvs6 — Logs Are MAGIC — OpenWest 2017 — @genehack
I liked SVN a bit more...
svn7 — Logs Are MAGIC — OpenWest 2017 — @genehack
Hell, I even liked RCS
rcs8 — Logs Are MAGIC — OpenWest 2017 — @genehack
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
And now we have git
git10 — Logs Are MAGIC — OpenWest 2017 — @genehack
I love git. Git makes me happy
i ❤ git
11 — Logs Are MAGIC — OpenWest 2017 — @genehack
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
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
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
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
So what is this talk about then?
what this
talk is16 — Logs Are MAGIC — OpenWest 2017 — @genehack
Opinionated commentary on some aspects of using
revision control systems...
some
opinions
17 — Logs Are MAGIC — OpenWest 2017 — @genehack
...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
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
...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
maybe more
relevant for
coding projects
21 — Logs Are MAGIC — OpenWest 2017 — @genehack
but also
applicable for
doc or config repos
22 — Logs Are MAGIC — OpenWest 2017 — @genehack
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
...but first, weʼre going to talk about ways to make better
history
making
better
history24 — Logs Are MAGIC — OpenWest 2017 — @genehack
For all these things, there are a few common elements
prerequisites
25 — Logs Are MAGIC — OpenWest 2017 — @genehack
For maximum value, youʼre going to want to apply them
consistently
consistency
26 — Logs Are MAGIC — OpenWest 2017 — @genehack
Make them into habits
habits
27 — Logs Are MAGIC — OpenWest 2017 — @genehack
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
...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
or even better, if youʼre the right kind of twisted...
even
better30 — Logs Are MAGIC — OpenWest 2017 — @genehack
...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
so, moving on to how to make better history
how to make
better
history32 — Logs Are MAGIC — OpenWest 2017 — @genehack
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
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
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
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
some
notable
antipatterns37 — Logs Are MAGIC — OpenWest 2017 — @genehack
squashed
branches
38 — Logs Are MAGIC — OpenWest 2017 — @genehack
fast
forward
merges39 — Logs Are MAGIC — OpenWest 2017 — @genehack
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
all
destroy
history41 — Logs Are MAGIC — OpenWest 2017 — @genehack
all
destroy
history
needlessly
42 — Logs Are MAGIC — OpenWest 2017 — @genehack
a linear
commit
history
is a lie43 — Logs Are MAGIC — OpenWest 2017 — @genehack
a linear
commit
history
is a lie
(probably)
44 — Logs Are MAGIC — OpenWest 2017 — @genehack
instead
45 — Logs Are MAGIC — OpenWest 2017 — @genehack
some good
patterns46 — Logs Are MAGIC — OpenWest 2017 — @genehack
branch
47 — Logs Are MAGIC — OpenWest 2017 — @genehack
branch
for
errythang48 — Logs Are MAGIC — OpenWest 2017 — @genehack
(specifics
will vary)49 — Logs Are MAGIC — OpenWest 2017 — @genehack
have a
release
branch50 — Logs Are MAGIC — OpenWest 2017 — @genehack
release may be master
release may be another branch
51 — Logs Are MAGIC — OpenWest 2017 — @genehack
(again,
specifics
will vary)
52 — Logs Are MAGIC — OpenWest 2017 — @genehack
merging to
the release
branch is
a release53 — Logs Are MAGIC — OpenWest 2017 — @genehack
(ideally,
automatically)
54 — Logs Are MAGIC — OpenWest 2017 — @genehack
make all
merges
non-FF55 — Logs Are MAGIC — OpenWest 2017 — @genehack
an aside
56 — Logs Are MAGIC — OpenWest 2017 — @genehack
~/.gitconfig
57 — Logs Are MAGIC — OpenWest 2017 — @genehack
git config --global merge.ff false
git config --global pull.ff only
58 — Logs Are MAGIC — OpenWest 2017 — @genehack
[merge]
ff = false
[pull]
ff = only
59 — Logs Are MAGIC — OpenWest 2017 — @genehack
maximal
historical
information60 — Logs Are MAGIC — OpenWest 2017 — @genehack
keep it
clean61 — Logs Are MAGIC — OpenWest 2017 — @genehack
another aside
62 — Logs Are MAGIC — OpenWest 2017 — @genehack
~/.gitconfig
aliases
63 — Logs Are MAGIC — OpenWest 2017 — @genehack
[alias]
br = branch
ci = commit -v
co = checkout
st = status
64 — Logs Are MAGIC — OpenWest 2017 — @genehack
aliases have
many
uses…65 — Logs Are MAGIC — OpenWest 2017 — @genehack
66 — Logs Are MAGIC — OpenWest 2017 — @genehack
back to keeping it clean…
67 — Logs Are MAGIC — OpenWest 2017 — @genehack
clean up
remote branches
68 — Logs Are MAGIC — OpenWest 2017 — @genehack
git push origin :<branch>
69 — Logs Are MAGIC — OpenWest 2017 — @genehack
added in 1.7, early 2010
git push origin --delete <branch>
70 — Logs Are MAGIC — OpenWest 2017 — @genehack
nuke = push origin --delete
71 — Logs Are MAGIC — OpenWest 2017 — @genehack
clean up
orphaned
remote-tracking
branches72 — Logs Are MAGIC — OpenWest 2017 — @genehack
git remote prune origin
73 — Logs Are MAGIC — OpenWest 2017 — @genehack
prune = remote prune origin
74 — Logs Are MAGIC — OpenWest 2017 — @genehack
find
unmerged
branches75 — Logs Are MAGIC — OpenWest 2017 — @genehack
git branch --no-merged master
76 — Logs Are MAGIC — OpenWest 2017 — @genehack
git branch --no-merged --remote master
77 — Logs Are MAGIC — OpenWest 2017 — @genehack
unmerged = branch --no-merged
unmerged-remote = branch --no-merged --remote
78 — Logs Are MAGIC — OpenWest 2017 — @genehack
keep it
clean79 — Logs Are MAGIC — OpenWest 2017 — @genehack
one final
note on
branches80 — Logs Are MAGIC — OpenWest 2017 — @genehack
branch
names81 — Logs Are MAGIC — OpenWest 2017 — @genehack
a branch
equals
a ticket82 — Logs Are MAGIC — OpenWest 2017 — @genehack
the ticket id
should be in
the branch name
83 — Logs Are MAGIC — OpenWest 2017 — @genehack
along with
something
for the
humans84 — Logs Are MAGIC — OpenWest 2017 — @genehack
put the number
at the end of
the branch name
85 — Logs Are MAGIC — OpenWest 2017 — @genehack
good:
fix-login-864
86 — Logs Are MAGIC — OpenWest 2017 — @genehack
meh:
fix-864
87 — Logs Are MAGIC — OpenWest 2017 — @genehack
bad:
864-crap
88 — Logs Are MAGIC — OpenWest 2017 — @genehack
!!!:
foobar
89 — Logs Are MAGIC — OpenWest 2017 — @genehack
just.
don’t.
90 — Logs Are MAGIC — OpenWest 2017 — @genehack
when merging
include the
branch name91 — Logs Are MAGIC — OpenWest 2017 — @genehack
default message
works nicely
92 — Logs Are MAGIC — OpenWest 2017 — @genehack
Merge branch <name>
93 — Logs Are MAGIC — OpenWest 2017 — @genehack
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
to review
95 — Logs Are MAGIC — OpenWest 2017 — @genehack
don’t squash
96 — Logs Are MAGIC — OpenWest 2017 — @genehack
don’t fast forward
97 — Logs Are MAGIC — OpenWest 2017 — @genehack
don’t rebase before merge
98 — Logs Are MAGIC — OpenWest 2017 — @genehack
don’t destroy your history
99 — Logs Are MAGIC — OpenWest 2017 — @genehack
use branches
100 — Logs Are MAGIC — OpenWest 2017 — @genehack
use a release branch
101 — Logs Are MAGIC — OpenWest 2017 — @genehack
use no-ff to make merge commits
102 — Logs Are MAGIC — OpenWest 2017 — @genehack
keep your repo clean
103 — Logs Are MAGIC — OpenWest 2017 — @genehack
let’s get
more
granular
104 — Logs Are MAGIC — OpenWest 2017 — @genehack
structuring
individual
commits105 — Logs Are MAGIC — OpenWest 2017 — @genehack
a commit
equals
one “change”106 — Logs Are MAGIC — OpenWest 2017 — @genehack
important:
at each commit
the software
must work107 — Logs Are MAGIC — OpenWest 2017 — @genehack
who has heard of git bisect?
who has used git bisect?
<explain git bisect>
git bisect
108 — Logs Are MAGIC — OpenWest 2017 — @genehack
when in doubt…
smaller >> bigger
109 — Logs Are MAGIC — OpenWest 2017 — @genehack
whitespace
& formatting
110 — Logs Are MAGIC — OpenWest 2017 — @genehack
always
go in
distinct commits111 — Logs Are MAGIC — OpenWest 2017 — @genehack
remember!
112 — Logs Are MAGIC — OpenWest 2017 — @genehack
revision
is also a
thing113 — Logs Are MAGIC — OpenWest 2017 — @genehack
what you
eventually
push114 — Logs Are MAGIC — OpenWest 2017 — @genehack
!=115 — Logs Are MAGIC — OpenWest 2017 — @genehack
your
commits
while
working
116 — Logs Are MAGIC — OpenWest 2017 — @genehack
develop a habit of using checkpoint commits instead of the
stash
savepoints
117 — Logs Are MAGIC — OpenWest 2017 — @genehack
every
working
micro
step
118 — Logs Are MAGIC — OpenWest 2017 — @genehack
single “change”
10-15 commits
119 — Logs Are MAGIC — OpenWest 2017 — @genehack
who has heard of the --patch option?
who uses this?
git add --patch
120 — Logs Are MAGIC — OpenWest 2017 — @genehack
git add -p
121 — Logs Are MAGIC — OpenWest 2017 — @genehack
git commit --amend
122 — Logs Are MAGIC — OpenWest 2017 — @genehack
editor
support123 — Logs Are MAGIC — OpenWest 2017 — @genehack
magit
fugitive
github.atom.io124 — Logs Are MAGIC — OpenWest 2017 — @genehack
magit
125 — Logs Are MAGIC — OpenWest 2017 — @genehack
don’t push
first drafts
126 — Logs Are MAGIC — OpenWest 2017 — @genehack
tell a
story
127 — Logs Are MAGIC — OpenWest 2017 — @genehack
interactive
rebasegit rebase -i
128 — Logs Are MAGIC — OpenWest 2017 — @genehack
sometimes
may be useful to
preserve dead ends
129 — Logs Are MAGIC — OpenWest 2017 — @genehack
photo credit https://pbs.twimg.com/media/
CPlr0tQWcAAZPjf.jpg
...as a
warning
for others
130 — Logs Are MAGIC — OpenWest 2017 — @genehack
commit
messages131 — Logs Are MAGIC — OpenWest 2017 — @genehack
ticket
numbers
in the subject
132 — Logs Are MAGIC — OpenWest 2017 — @genehack
(at the end)
133 — Logs Are MAGIC — OpenWest 2017 — @genehack
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
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
you can customize
the template for
the commit message
136 — Logs Are MAGIC — OpenWest 2017 — @genehack
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
subjects only
commit
message
examples138 — Logs Are MAGIC — OpenWest 2017 — @genehack
that's 46 characters, by the way
good:
make login form use POST instead of GET [#864]
139 — Logs Are MAGIC — OpenWest 2017 — @genehack
meh:
fixed form [#864]
140 — Logs Are MAGIC — OpenWest 2017 — @genehack
bad:
846 fix
141 — Logs Are MAGIC — OpenWest 2017 — @genehack
!!!:
foo
142 — Logs Are MAGIC — OpenWest 2017 — @genehack
( °□°
143 — Logs Are MAGIC — OpenWest 2017 — @genehack
this
is why
daddy drinks
144 — Logs Are MAGIC — OpenWest 2017 — @genehack
to review
145 — Logs Are MAGIC — OpenWest 2017 — @genehack
1 commit == 1 change
146 — Logs Are MAGIC — OpenWest 2017 — @genehack
photo credit https://imgs.xkcd.com/comics/git_commit.png
and https://xkcd.com/1296/
commit
messages
matter!
147 — Logs Are MAGIC — OpenWest 2017 — @genehack
when in doubt make it
smaller
148 — Logs Are MAGIC — OpenWest 2017 — @genehack
(make the commit smaller
NOTthe commit message)
149 — Logs Are MAGIC — OpenWest 2017 — @genehack
segregate
formatting
changes150 — Logs Are MAGIC — OpenWest 2017 — @genehack
use
checkpoint
commits
as savepoints
151 — Logs Are MAGIC — OpenWest 2017 — @genehack
don’t push
first drafts
152 — Logs Are MAGIC — OpenWest 2017 — @genehack
revise to
tell a
story153 — Logs Are MAGIC — OpenWest 2017 — @genehack
or at least make yourself look
smart154 — Logs Are MAGIC — OpenWest 2017 — @genehack
using
history
better155 — Logs Are MAGIC — OpenWest 2017 — @genehack
jfri156 — Logs Are MAGIC — OpenWest 2017 — @genehack
<tell jesse story about reading history & talk inspiration>
just
friggin’
read
it157 — Logs Are MAGIC — OpenWest 2017 — @genehack
~/.gitconfig
(again)
158 — Logs Are MAGIC — OpenWest 2017 — @genehack
color
support159 — Logs Are MAGIC — OpenWest 2017 — @genehack
[color]
branch = auto
diff = auto
grep = auto
interactive = auto
showbranch = auto
status = auto
ui = auto
160 — Logs Are MAGIC — OpenWest 2017 — @genehack
[color "status"]
added = green bold
changed = red bold
untracked = cyan bold
161 — Logs Are MAGIC — OpenWest 2017 — @genehack
git diff
162 — Logs Are MAGIC — OpenWest 2017 — @genehack
git diff -w
163 — Logs Are MAGIC — OpenWest 2017 — @genehack
git diff --word-diff
164 — Logs Are MAGIC — OpenWest 2017 — @genehack
git diff --word-diff=color
165 — Logs Are MAGIC — OpenWest 2017 — @genehack
blame
166 — Logs Are MAGIC — OpenWest 2017 — @genehack
git blame
167 — Logs Are MAGIC — OpenWest 2017 — @genehack
-w ignores whitespace
-M tracks lines moved within a file
git blame -w -M
168 — Logs Are MAGIC — OpenWest 2017 — @genehack
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
i will
buy
this tee shirt
hashtag justsayin’
170 — Logs Are MAGIC — OpenWest 2017 — @genehack
editorintegration171 — Logs Are MAGIC — OpenWest 2017 — @genehack
M-x git-blame-for-line
172 — Logs Are MAGIC — OpenWest 2017 — @genehack
git blame -L <line>,<line> <file>
git log -L <line>,<line>:<file>
173 — Logs Are MAGIC — OpenWest 2017 — @genehack
git blame -L 1,1 index.html
174 — Logs Are MAGIC — OpenWest 2017 — @genehack
git blame -L 10,50 index.html
175 — Logs Are MAGIC — OpenWest 2017 — @genehack
git blame -L 20,+10 index.html
176 — Logs Are MAGIC — OpenWest 2017 — @genehack
git log -L 1,1:index.html
177 — Logs Are MAGIC — OpenWest 2017 — @genehack
git log -L 10,50:index.html
178 — Logs Are MAGIC — OpenWest 2017 — @genehack
git log -L 20,+10:index.html
179 — Logs Are MAGIC — OpenWest 2017 — @genehack
git log -S <string>
180 — Logs Are MAGIC — OpenWest 2017 — @genehack
git lg
181 — Logs Are MAGIC — OpenWest 2017 — @genehack
log --graph --abbrev-commit --date=relative --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset'
182 — Logs Are MAGIC — OpenWest 2017 — @genehack
183 — Logs Are MAGIC — OpenWest 2017 — @genehack
--graph
184 — Logs Are MAGIC — OpenWest 2017 — @genehack
--abbrev-commit
185 — Logs Are MAGIC — OpenWest 2017 — @genehack
--date=relative
186 — Logs Are MAGIC — OpenWest 2017 — @genehack
SHA in red,
branch name (if any) in yellow,
commit subject,
date,
author
--pretty=format:
'%Cred%h%Creset
-%C(yellow)%d%Creset
%s
%Cgreen(%cr)
%C(bold blue)<%an>%Creset'
187 — Logs Are MAGIC — OpenWest 2017 — @genehack
188 — Logs Are MAGIC — OpenWest 2017 — @genehack
takeaways!
189 — Logs Are MAGIC — OpenWest 2017 — @genehack
history
is
important190 — Logs Are MAGIC — OpenWest 2017 — @genehack
it’s probably
worth more
of your time191 — Logs Are MAGIC — OpenWest 2017 — @genehack
both
creating it
and
using it
192 — Logs Are MAGIC — OpenWest 2017 — @genehack
don’t just stop
when the
software
works193 — Logs Are MAGIC — OpenWest 2017 — @genehack
software
development
is hard194 — Logs Are MAGIC — OpenWest 2017 — @genehack
be kind
to others195 — Logs Are MAGIC — OpenWest 2017 — @genehack
be kind
to your
future
self196 — Logs Are MAGIC — OpenWest 2017 — @genehack
thank you!
197 — Logs Are MAGIC — OpenWest 2017 — @genehack
198 — Logs Are MAGIC — OpenWest 2017 — @genehack
GIMME YR TALKS
Oct 6-7
CFP OPEN NOW!
seagl.org
199 — Logs Are MAGIC — OpenWest 2017 — @genehack
please give me
feedbackhttps://joind.in/talk/0f066
200 — Logs Are MAGIC — OpenWest 2017 — @genehack
questions?
FEEDBACK → https://joind.in/talk/0f066
201 — Logs Are MAGIC — OpenWest 2017 — @genehack
202 — Logs Are MAGIC — OpenWest 2017 — @genehack

Logs Are Magic: Why Git Workflows and Commit Structure Should Matter To You