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 | lfnw 2017 | 7 may 2017
1 — LFNW 2017 – 7 May 2017 – @genehack

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 | lfnw 2017 | 7 may 2017

hi, i'm john.
a/k/a @genehack

In my day job, I'm the VP of Technology for Infinity, a small
IT consultancy.
vp, tech
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
control5 — LFNW 2017 – 7 May 2017 – @genehack

I liked CVS...
cvs6 — LFNW 2017 – 7 May 2017 – @genehack

I liked SVN a bit more...
svn7 — LFNW 2017 – 7 May 2017 – @genehack

Hell, I even liked RCS
rcs8 — LFNW 2017 – 7 May 2017 – @genehack

Actually, that's a lie -- I don't think
anybody liked RCS.
Anybody here remember RCS?
Anybody still using RCS?
rcs9 — LFNW 2017 – 7 May 2017 – @genehack

And now we have git
git10 — LFNW 2017 – 7 May 2017 – @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!

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 — LFNW 2017 – 7 May 2017 – @genehack

I'm also not going to be claiming to dispense any universal
truths in this talk...
nouniversal
truths14 — LFNW 2017 – 7 May 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 — LFNW 2017 – 7 May 2017 – @genehack

So what is this talk about then?
what this
talk is16 — LFNW 2017 – 7 May 2017 – @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 projects

...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 — LFNW 2017 – 7 May 2017 – @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
history24 — LFNW 2017 – 7 May 2017 – @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 time28 — LFNW 2017 – 7 May 2017 – @genehack

...you eventually will just do them without thinking too much
about it
then you
don't have
to think
about it29 — LFNW 2017 – 7 May 2017 – @genehack

or even better, if you're the right kind of twisted...
even
better30 — LFNW 2017 – 7 May 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
it

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

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

some
notable
antipatterns37 — LFNW 2017 – 7 May 2017 – @genehack

squashed
branches

fast
forward
merges39 — LFNW 2017 – 7 May 2017 – @genehack

this is basically doing extra work to mimic what a fast
forward merge probably would have done
rebase
before
merge40 — LFNW 2017 – 7 May 2017 – @genehack

all
destroy
history41 — LFNW 2017 – 7 May 2017 – @genehack

all
destroy
history
needlessly

a linear
commit
history
is a lie43 — LFNW 2017 – 7 May 2017 – @genehack

a linear
commit
history
is a lie
(probably)

instead

some good
patterns46 — LFNW 2017 – 7 May 2017 – @genehack

branch

branch
for
errythang48 — LFNW 2017 – 7 May 2017 – @genehack

(speciﬁcs
will vary)49 — LFNW 2017 – 7 May 2017 – @genehack

have a
release
branch50 — LFNW 2017 – 7 May 2017 – @genehack

release may be master
release may be another branch

(again,
speciﬁcs
will vary)

merging to
the release
branch is
a release53 — LFNW 2017 – 7 May 2017 – @genehack

(ideally,
automatically)

make all
merges
non-FF55 — LFNW 2017 – 7 May 2017 – @genehack

an aside

~/.gitconfig

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

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

maximal
historical
information60 — LFNW 2017 – 7 May 2017 – @genehack

keep it
clean61 — LFNW 2017 – 7 May 2017 – @genehack

~/.gitconfig
aliases

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

clean up
remote
branches

git push origin --delete <branch>

nuke = push origin --delete

clean up
orphaned
remote-tracking
branches67 — LFNW 2017 – 7 May 2017 – @genehack

git remote prune origin

prune = remote prune origin

ﬁnd
unmerged
branches

git branch --no-merged master

git branch --no-merged --remote master

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

keep it
clean74 — LFNW 2017 – 7 May 2017 – @genehack

one ﬁnal
note on
branches75 — LFNW 2017 – 7 May 2017 – @genehack

branch
names76 — LFNW 2017 – 7 May 2017 – @genehack

a branch
equals
a ticket77 — LFNW 2017 – 7 May 2017 – @genehack

the ticket id
should be in
the branch name

along with
something
for the
humans79 — LFNW 2017 – 7 May 2017 – @genehack

put the number
at the end of
the branch name

good:
fix-login-864

meh:
fix-864

bad:
864-crap

!!!:
foobar

just.
don't.

when merging
include the
branch name86 — LFNW 2017 – 7 May 2017 – @genehack

default message
works nicely

Merge branch <name>

maximal
historical
information89 — LFNW 2017 – 7 May 2017 – @genehack

to review

don't squash

don't fast forward

don't rebase before merge

don't destroy your history

use branches

use a release branch

use no-ff to make merge commits

keep your repo clean

let's get
more
granular

structuring
individual
commits100 — LFNW 2017 – 7 May 2017 – @genehack

a commit
equals
one "change"101 — LFNW 2017 – 7 May 2017 – @genehack

important:
at each commit
the software
must work102 — LFNW 2017 – 7 May 2017 – @genehack

git bisect

smaller >> bigger

whitespace
& formatting

always
go in
distinct commits106 — LFNW 2017 – 7 May 2017 – @genehack

remember!

revision
is also a
thing108 — LFNW 2017 – 7 May 2017 – @genehack

what you
eventually
push109 — LFNW 2017 – 7 May 2017 – @genehack

!=110 — LFNW 2017 – 7 May 2017 – @genehack

your
commits
while
working

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

every
working
micro
step

single "change"
10-15 commits

git add --patch

git add -p

editor
support117 — LFNW 2017 – 7 May 2017 – @genehack

magit
fugitive118 — LFNW 2017 – 7 May 2017 – @genehack

magit

don't push
ﬁrst drafts

tell a
story

git rebase -i

may be useful
to preserve
dead ends123 — LFNW 2017 – 7 May 2017 – @genehack

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

commit
messages125 — LFNW 2017 – 7 May 2017 – @genehack

ticket
numbers
in the subject

(at the end)

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

examples

good:
make login form use POST instead of GET [#864]

meh:
fixed form [#864]

bad:
#846 fix

!!!:
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

segregate
formatting
changes141 — LFNW 2017 – 7 May 2017 – @genehack

use
checkpoint
commits
as savepoints

don't push
ﬁrst drafts

revise to
tell a
story144 — LFNW 2017 – 7 May 2017 – @genehack

or at least make yourself look
smart145 — LFNW 2017 – 7 May 2017 – @genehack

using
history
better146 — LFNW 2017 – 7 May 2017 – @genehack

jfri147 — LFNW 2017 – 7 May 2017 – @genehack

just
friggin'
read
it148 — LFNW 2017 – 7 May 2017 – @genehack

~/.gitconfig
(again)

color
support150 — LFNW 2017 – 7 May 2017 – @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 blame

git blame -w -M

[alias]
praise = blame

editorintegration156 — LFNW 2017 – 7 May 2017 – @genehack

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 log --follow

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,
date,
author
`--pretty=format:
'%Cred%h%Creset
-%C(yellow)%d%Creset
%s
%Cgreen(%cr)
%C(bold blue)<%an>%Creset'`

takeaways!

history
is
important175 — LFNW 2017 – 7 May 2017 – @genehack

it's probably
worth more
of your time176 — LFNW 2017 – 7 May 2017 – @genehack

both
creating it
and
using it

don't just stop
when the
software
works178 — LFNW 2017 – 7 May 2017 – @genehack

software
development
is hard179 — LFNW 2017 – 7 May 2017 – @genehack

be kind
to others180 — LFNW 2017 – 7 May 2017 – @genehack

be kind
to your
future
self181 — LFNW 2017 – 7 May 2017 – @genehack

thanks!
lfnw organizers &
volunteers
linus & others for git
YOU!

questions?
(ps: please ﬁll out the talk eval form!)

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 (20)

More from John Anderson (20)

Recently uploaded (20)

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