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

photo: https://
cdn.pixabay.com/photo/
2014/10/01/17/59/my-little-
pony-468916960720.jpg
logs are magic!
john sj anderson | @genehack | #kcdc2018

photo: https://
cdn.pixabay.com/photo/
2014/10/01/17/59/my-little-
pony-468916960720.jpg
why git workﬂows
& commit structure
should matter to you
john sj anderson | @genehack | #kcdc2018

TITANIUM SPONSORS
Platinum Sponsors
Gold Sponsors

hi, i’m john.
a/k/a @genehack
4 — Logs Are MAGIC • #kcdc2018 • @genehack

In my day job, Iʼm the VP of
Technology for Infinity, a
custom
software development and
technology consultancy firm
vp, technology
inﬁnity
interactive

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
control6 — Logs Are MAGIC • #kcdc2018 • @genehack

I liked CVS...
cvs7 — Logs Are MAGIC • #kcdc2018 • @genehack

I liked SVN a bit more...
svn8 — Logs Are MAGIC • #kcdc2018 • @genehack

Hell, I even liked RCS
rcs9 — Logs Are MAGIC • #kcdc2018 • @genehack

Actually, thatʼs a lie -- I donʼt
think anybody liked RCS.
Anybody here remember
RCS?
Anybody still using RCS?
rcs10 — Logs Are MAGIC • #kcdc2018 • @genehack

And now we have git
git11 — Logs Are MAGIC • #kcdc2018 • @genehack

I love git. Git makes me happy
i ❤ git

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!13 — Logs Are MAGIC • #kcdc2018 • @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’t14 — Logs Are MAGIC • #kcdc2018 • @genehack

Iʼm also not going to be
claiming to dispense any
universal truths in this talk...
nouniversal truths15 — Logs Are MAGIC • #kcdc2018 • @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”

So what is this talk about
then?
what this
talk is17 — Logs Are MAGIC • #kcdc2018 • @genehack

Opinionated commentary on
some aspects of using revision
control systems...
some
opinions

...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

Some of this stuff may be
more important for larger
projects with multi-person
teams ...
maybe more
important for
larger projects20 — Logs Are MAGIC • #kcdc2018 • @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
bigger21 — Logs Are MAGIC • #kcdc2018 • @genehack

maybe more
relevant for
coding projects

but also
applicable for
doc or conﬁg repos

Eventually weʼre going to talk
about how to make better use
of the history in your repos ...
making better
use of history

...but first, weʼre going to talk
about ways to make better
history
making
better
history25 — Logs Are MAGIC • #kcdc2018 • @genehack

For all these things, there are a
few common elements
prerequisites

For maximum value, youʼre
going to want to apply them
consistently
consistency

Make them into habits
habits

Theyʼre pretty much all the
type of thing that if you do
them all the time...
do it all
the time29 — Logs Are MAGIC • #kcdc2018 • @genehack

...you eventually will just do
them without thinking too
much about it
then you
don’t have to
think
about it30 — Logs Are MAGIC • #kcdc2018 • @genehack

or even better, if youʼre the
right kind of twisted...
even
better31 — Logs Are MAGIC • #kcdc2018 • @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
it32 — Logs Are MAGIC • #kcdc2018 • @genehack

so, moving on to how to make
better history
how to make
better

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

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

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

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

regardless of workflow, there
are some things you should
avoid
some
notable
antipatterns38 — Logs Are MAGIC • #kcdc2018 • @genehack

squashed
branches

fast
forward
merges40 — Logs Are MAGIC • #kcdc2018 • @genehack

this is basically doing extra
work to mimic what a fast
forward merge probably would
have done
rebase
before
merge41 — Logs Are MAGIC • #kcdc2018 • @genehack

all
destroy

all
destroy
history
needlessly

a linear
commit history
is a lie44 — Logs Are MAGIC • #kcdc2018 • @genehack

a linear
commit history
is a lie
(probably)

instead

some good
patterns47 — Logs Are MAGIC • #kcdc2018 • @genehack

branch

branch
for
errythang49 — Logs Are MAGIC • #kcdc2018 • @genehack

(speciﬁcs
will vary)50 — Logs Are MAGIC • #kcdc2018 • @genehack

have a
release
branch51 — Logs Are MAGIC • #kcdc2018 • @genehack

release may be master
release may be another branch

(again, speciﬁcs
will vary)

merging to
the release branch
is
a release54 — Logs Are MAGIC • #kcdc2018 • @genehack

(ideally,
automatically)

make all
merges
non-ff56 — Logs Are MAGIC • #kcdc2018 • @genehack

an
aside57 — Logs Are MAGIC • #kcdc2018 • @genehack

~/.gitconfig

git config --global merge.ff false
git config --global pull.ff only

[merge]
ff = false
[pull]
ff = only

maximal
historical
information61 — Logs Are MAGIC • #kcdc2018 • @genehack

keep it
clean62 — Logs Are MAGIC • #kcdc2018 • @genehack

another
aside63 — Logs Are MAGIC • #kcdc2018 • @genehack

~/.gitconfig
aliases64 — Logs Are MAGIC • #kcdc2018 • @genehack

[alias]
br = branch
ci = commit -v
co = checkout
st = status

aliases have
many
uses…66 — Logs Are MAGIC • #kcdc2018 • @genehack

back to keeping it
clean…68 — Logs Are MAGIC • #kcdc2018 • @genehack

clean up
remote branches

git push origin :<branch>

added in 1.7, early 2010
git push origin --delete <branch>

nuke = push origin --delete

clean up
orphaned
remote-tracking
branches73 — Logs Are MAGIC • #kcdc2018 • @genehack

git remote prune origin

prune = remote prune origin

ﬁnd
unmerged

git branch --no-merged master

git branch --no-merged --remote master

unmerged = branch --no-merged
unmerged-remote = branch --no-merged --remote

keep it
clean80 — Logs Are MAGIC • #kcdc2018 • @genehack

one ﬁnal
note on

branch
names82 — Logs Are MAGIC • #kcdc2018 • @genehack

a branch is
a ticket83 — Logs Are MAGIC • #kcdc2018 • @genehack

the ticket id
should be in
the branch name

along with
something for
the humans85 — Logs Are MAGIC • #kcdc2018 • @genehack

reminder

we are humans
working with humans
to develop software
for the beneﬁt of humans.

put the number
at the end of
the branch name

ok:
fix-login-864

meh:fix-86490 — Logs Are MAGIC • #kcdc2018 • @genehack

bad:
864-crap91 — Logs Are MAGIC • #kcdc2018 • @genehack

!!!
foobar!!!

maybe.
just.
don’t.93 — Logs Are MAGIC • #kcdc2018 • @genehack

include the
branch name
in the commit
when merging

the default message
works nicely

Merge branch <name>

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
information97 — Logs Are MAGIC • #kcdc2018 • @genehack

to review

don’t
squash99 — Logs Are MAGIC • #kcdc2018 • @genehack

don’tfast forward100 — Logs Are MAGIC • #kcdc2018 • @genehack

don’trebase before merge

don’tdestroy your history

douse branches103 — Logs Are MAGIC • #kcdc2018 • @genehack

dohave a release branch104 — Logs Are MAGIC • #kcdc2018 • @genehack

do
use --no-ff
to make merge commits

keep your
repo clean

let’s get
more
granular

structuring
individual
commits108 — Logs Are MAGIC • #kcdc2018 • @genehack

one commit
=one “change”109 — Logs Are MAGIC • #kcdc2018 • @genehack

important:
at each commit
the software
must work110 — Logs Are MAGIC • #kcdc2018 • @genehack

who has heard of git bisect?
who has used git bisect?
<explain git bisect>
git bisect

when in doubt…
smaller >> bigger

whitespace
& formatting

always
go in
distinct commits114 — Logs Are MAGIC • #kcdc2018 • @genehack

remember!

revision
is also a
thing116 — Logs Are MAGIC • #kcdc2018 • @genehack

what you end up pushing for
review117 — Logs Are MAGIC • #kcdc2018 • @genehack

doesn't need to
match118 — Logs Are MAGIC • #kcdc2018 • @genehack

the commits initially made while you’re
working

develop a habit of using
checkpoint commits instead of
the stash
savepoints

every
working
micro
step

single “change”
10-15 commits

who has heard of the --patch
option?
who uses this?
git add --patch

git add -p

git commit --amend

editor
support126 — Logs Are MAGIC • #kcdc2018 • @genehack

magit
fugitive
github.atom.io127 — Logs Are MAGIC • #kcdc2018 • @genehack

magit

don’t push
ﬁrst drafts

tell a
story

interactive
rebasegit rebase -i

sometimes
it may be useful to
preserve dead ends

photo credit https://
pbs.twimg.com/media/
CPlr0tQWcAAZPjf.jpg
…as a
warning
for others

commit
messages134 — Logs Are MAGIC • #kcdc2018 • @genehack

ticket numbers
in the subject

(at the end)

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
short137 — Logs Are MAGIC • #kcdc2018 • @genehack

most commits, however, deserve at least a
paragraph of body text in the commit message.
depending on exactly what work you did, what
decisions you made, etc., influences how much you
might want to put in there. good things to include
may be benchmarking 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
bodies138 — Logs Are MAGIC • #kcdc2018 • @genehack

you can customize
the template for
the commit message

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...

subjects only
commit
message
examples142 — Logs Are MAGIC • #kcdc2018 • @genehack

that's 46 characters, by the
way
good:
make login form use POST instead of GET [#864]

meh:fixed form [#864]

bad:846 fix145 — Logs Are MAGIC • #kcdc2018 • @genehack

!!!
foo!!!

( °□°

this
is why
daddy drinks

to review

1 commit → 1 change

photo credit https://
imgs.xkcd.com/comics/
git_commit.png and https://
xkcd.com/1296/
commit
messages
matter!

when in doubt make it
smaller

(make the commit smaller
NOTthe commit message)

segregate
formatting
changes154 — Logs Are MAGIC • #kcdc2018 • @genehack

use
checkpoint
commits
as savepoints

don’t push
ﬁrst drafts

revise to
tell a
story157 — Logs Are MAGIC • #kcdc2018 • @genehack

or at least make yourself look
smart158 — Logs Are MAGIC • #kcdc2018 • @genehack

using
history
better160 — Logs Are MAGIC • #kcdc2018 • @genehack

jfri161 — Logs Are MAGIC • #kcdc2018 • @genehack

<tell jesse story about reading
history & talk inspiration>
just
friggin’
read
it162 — Logs Are MAGIC • #kcdc2018 • @genehack

~/.gitconfig
(again)

color
support164 — Logs Are MAGIC • #kcdc2018 • @genehack

[color]
branch = auto
diff = auto
grep = auto
interactive = auto
showbranch = auto
status = auto
ui = auto

[color "status"]
added = green bold
changed = red bold
untracked = cyan bold

git diff

git diff --word-diff

blame

git blame

-w ignores whitespace
-M tracks lines moved within a
file
git blame -w -M

who has run git blame and
found out the thing that
bugged them, they
committed?
[alias]
praise = blame

i will
buy
this tee shirt
hashtag justsayin’

editorintegration175 — Logs Are MAGIC • #kcdc2018 • @genehack

M-x git-blame-for-line

git blame -L <line>,<line> <file>
git log -L <line>,<line>:<file>

git blame -L 1,1 index.html

git blame -L 10,50 index.html

git blame -L 20,+10 index.html

git log -L 1,1:index.html

git log -L 10,50:index.html

git log -L 20,+10:index.html

git log -S <string>

git lg

log --graph --abbrev-commit --date=relative --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset'

--graph

--abbrev-commit

--date=relative

SHA in red,
branch name (if any) in yellow,
commit subject,
relative date in green,
author in bold blue
--pretty=format:
'%Cred%h%Creset
-%C(yellow)%d%Creset
%s
%Cgreen(%cr)
%C(bold blue)<%an>%Creset'

takeaways!

history is
important197 — Logs Are MAGIC • #kcdc2018 • @genehack

it’s probably
worth more
of your time198 — Logs Are MAGIC • #kcdc2018 • @genehack

both
creating it
and
using it

don’t just stop
when the
software
works200 — Logs Are MAGIC • #kcdc2018 • @genehack

software
development
is hard201 — Logs Are MAGIC • #kcdc2018 • @genehack

be kind
to others202 — Logs Are MAGIC • #kcdc2018 • @genehack

be kind
to your
future
self203 — Logs Are MAGIC • #kcdc2018 • @genehack

thank
you!

seagl cfp is
open
(until 29 july!)

seeking
qa lead!
(hit me up for deets)

lemme know what you
think

questions?

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

More Related Content

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

More from John Anderson

Recently uploaded

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