Commit Messages to the Rescue!

What if I told you there is more to a commit message than "-m"? Like source code time capsules, those pesky formalities can deliver wisdom and perspective about any code from the best possible source, the developer who just wrote it! Explore new facets of these time traveling rubber duck opportunities to increase their usefulness tenfold. Tools like templates, linters, hooks, and automation. Hear what Dr. Seuss can teach us about git, and don't miss the most helpful morsel of git customization around... how to open a new message in an editor other than vim!

Transcript

1. doodling.dev @doodlingdev https://xkcd.com/1296/
2. doodling.dev @doodlingdev Commit messages To the rescue
3. doodling.dev @doodlingdev Aji Slater he/him snapsheet My name is aji, A..J..I.. say it with me. The entire room sounds disappointed in me now I’m comfortable. My pronouns are he/him My website is in the upper left, and my twitter in the upper right. If twitter is a thing you do, and I 100% understand if you just. can’t. I know you have a choice in conference talks, and I want to thank you for being here.
4. doodling.dev @doodlingdev I work for a company called Snapsheet based in Chicago. We’re not unleashing the world’s creativity or anything.. I don’t honestly have a pithy one liner to explain what we do, but a story from a friend of mine, Brett, is the best way to describe it. … So technically our customers are the insurance companies, and we’re streamlining processes, saving millions of dollars, increasing efficiency, but it’s what we can do for the people like Brett that make it exciting for me. Here is where I insert the obligatory “we’re hiring” statement. Come work with me and let’s make beautiful commit messages together.
5. doodling.dev @doodlingdev I work for a company called Snapsheet based in Chicago. We’re not unleashing the world’s creativity or anything.. I don’t honestly have a pithy one liner to explain what we do, but a story from a friend of mine, Brett, is the best way to describe it. … So technically our customers are the insurance companies, and we’re streamlining processes, saving millions of dollars, increasing efficiency, but it’s what we can do for the people like Brett that make it exciting for me. Here is where I insert the obligatory “we’re hiring” statement. Come work with me and let’s make beautiful commit messages together.
6. doodling.dev @doodlingdev Once upon a time… I gave a lightning talk version of this before, and I wanted to set up some of the situations in which commit messages could save your bacon. So I came up with a story about a workplace that could have been helped by good message practice. When looking for what pictures to put on my slides during this story, I reached for Dr Seuss imagery.
7. doodling.dev @doodlingdev I especially liked it because the fish could be the project manager. That.. felt right to me. So I started looking at the pictures.. and thinking, I’m going to give this talk at Railsconf… why not go all out? So I present to you..
8. doodling.dev @doodlingdev Git add, Git rm. Git commit Minus m! by Dr Seuss Definitely not by dr Seuss
9. doodling.dev @doodlingdev Git add, Git rm. Git commit Minus m! by Dr Seuss NOT Definitely not by dr Seuss
10. doodling.dev @doodlingdev An E-commerce site on AWS is a good enough scene for our story, I guess
11. doodling.dev @doodlingdev They employed devs much more than a few but i'd like to speak of thing one and thing two now thing one took some work from their burn-it-down chart seems a bug had been found in the site's shopping cart.
12. doodling.dev @doodlingdev even through all the planning, down deep in Rails magic requests had timed out, causing dips in their traffic Thing One raced to make known what was causing the fault sweating, anxious the server might catch fire'n halt
13. doodling.dev @doodlingdev For a week without sleep, many cans of La Croix, "At long last I've uncovered our one tragic flaw!" With git blame we find out that Thing 2 wrote the class that for the last week was a pain in the ...... workflow
14. doodling.dev @doodlingdev now, it's readable.. tested.. but somethings amiss no one class should employ as much logic as this
15. doodling.dev @doodlingdev it made sense at the time, said thing 2 un-repenting and you KNOW all of MY code is self documenting "so you say," said Thing One, "but it needs a refactor." "Now help me find out just what that method is after.
16. doodling.dev @doodlingdev "Seems like dead code to me, not much more than obstruction." Then their fix was merged in, and they pushed to production.
17. doodling.dev @doodlingdev But their sigh of relief only lasted a flash. never before had a site started crashing so fast. Looking at server logs their heart beats all quicken, "Hey I wonder if we could ask that Sean Griffin?"
18. doodling.dev @doodlingdev "He maintained Active Record, his opinion I trust." "Nah! He'll just tell us we should have used Rust."
19. doodling.dev @doodlingdev so call Aaron Patterson!
20. doodling.dev @doodlingdev call DHH! We're hemorrhaging money all over the place! As our devs contemplate the lost data and sales, think! When code loses context, apps run ...off the Rails.
21. doodling.dev @doodlingdev OK! Fun’s over. Down to business. Commit messages. We all do them, and like TDD we think they’re important but probably cut some corners here and there. I don’t want to stand up here and tell you you’re all doing something wrong..
22. doodling.dev @doodlingdev Because you’re not. But you might not be getting the most out of your commit messages
23. doodling.dev @doodlingdev Because you’re not. But you might not be getting the most out of your commit messages
24. doodling.dev @doodlingdev We’re all committed In general, version control is something that's taught fairly early on in learning to code. So the concepts need to be imparted in uncomplicated ways, and I bet that I can name a few.
25. doodling.dev @doodlingdev Its a save point, like in a video game
26. doodling.dev @doodlingdev Its a moment captured in time
27. doodling.dev @doodlingdev Its saving your work as you go along Like those or not, I'm fairly confident there wasn't much time spent on it, and we just used -m
28. doodling.dev @doodlingdev At the time, either when you're first learning coding, or first learning git, there's a lot to take in. Git is.. a little inaccessible at best.. so simplifying the steps is important to help learn. So we're shown `-m` and told to write a brief description and move on.
29. doodling.dev @doodlingdev Especially because if we typed git commit without the -m we were going to get stuck in a twilight zone from which there is no escape
30. doodling.dev @doodlingdev Especially because if we typed git commit without the -m we were going to get stuck in a twilight zone from which there is no escape
31. doodling.dev @doodlingdev Git commit was going to land us in VIM
32. doodling.dev @doodlingdev Much like I've seen the one true light, and use VIM as my daily-driver now that I have more familiarity, I've circled back around to git and commit messages.
33. doodling.dev @doodlingdev Because when these messages aren't thought about as a tool, but as a hindrance to work, or as a chore that we have to do that doesn't matter.. we end up with messages that are…
34. doodling.dev @doodlingdev Because when these messages aren't thought about as a tool, but as a hindrance to work, or as a chore that we have to do that doesn't matter.. we end up with messages that are…
35. doodling.dev @doodlingdev Unhelpful
36. doodling.dev @doodlingdev Incredulous
37. doodling.dev @doodlingdev Maybe a bit on the nose..
38. doodling.dev @doodlingdev Even desperate
39. doodling.dev @doodlingdev Dishonest
40. doodling.dev @doodlingdev Depressing
41. doodling.dev @doodlingdev downright belligerent
42. doodling.dev @doodlingdev I’ve got nothin’
43. doodling.dev @doodlingdev I listen to a podcast, "The Bike Shed," and in days gone by it was hosted by Sean Griffin and Derek Prior, and somewhere in there, who remembers when...
44. doodling.dev @doodlingdev ...Sean started to talk about what a good commit message means, and how it can save you from bad situations I thought to myself, alright, this is a guy who talks about complicated code concepts like its nothin'.. and so often I don't know what he's talking about,
45. doodling.dev @doodlingdev but commit messages? Here's a bit of wisdom from this programming celebrity that I can put into practice.
46. doodling.dev @doodlingdev I know Kung fu So I started to look into commit messages. I read some blogs, a forum post or two, plenty of stack overflow questions, and a few pieces of advice rose to the top time and again
47. doodling.dev @doodlingdev 1. Use imperative tense 2. Start with a capital letter 3. Don’t end with a period 4. Keep it < 75 characters 5. Just use -m Show of hands, how many people have heard rules like these? and use them? how many people are seeing these ideas for the first time? Some of these have reasons behind them... keep the subject short because git will truncate at around 50 characters.
48. doodling.dev @doodlingdev That’s 17.85% of a tweet Capital Letter, Period, the ?tense? you use...That's all just tabs or spaces. There's a convention we gravitate to (these conventions) but if your team or your project prefers something else, and has a different style guide? Go for it.
49. doodling.dev @doodlingdev You do you And -m? Well we'll see why that shortcut is the same as an ice cream breakfast. It's nice at the time, but it's not going to help you get through the day.
50. doodling.dev @doodlingdev Speak for yourself
51. doodling.dev @doodlingdev The road Most travelled Let's take a moment and look at well intentioned commit messages I pulled from Github Again, please with a show of hands, how many of you have written a commit message like... this?
52. doodling.dev @doodlingdev How about this…
53. doodling.dev @doodlingdev or..
54. doodling.dev @doodlingdev What do these examples have in common?
55. doodling.dev @doodlingdev Poor life choices? They all follow those canonical rules, don't they. They might enforce stylistic consistency, but they're addressing the wrong things. Those examples all had something else in common..
56. doodling.dev @doodlingdev No body Every last one of those did not include a body to the commit message. The habit of not using message bodies is so prevalent, that I bet there are some developers out there who are capable, smart, great developers.. that have NEVER written a commit message body. There might be some at this conference, or in this room.
57. doodling.dev @doodlingdev Hi And to you, if you're out there, I cannot wait to share the new perspective on this boring, common tool…because it absolutely can be a game. changer.
58. doodling.dev @doodlingdev Overused cliche We’ve seen some examples and it seems pretty easy to agree on what makes a commit message unhelpful, what goes into a good commit message?
59. doodling.dev @doodlingdev Overused cliche We’ve seen some examples and it seems pretty easy to agree on what makes a commit message unhelpful, what goes into a good commit message?
60. doodling.dev @doodlingdev This is from an open source project by Thoughtbot called Clearance, with the subject line “Use route independent password reset redirect” and the body: … Concise but descriptive subject In two sentences this message conveys * The problem that required a change to be made * The intention of the code originally and therefore what the change is aiming for * References the main point of the solution.
61. doodling.dev @doodlingdev This is the little commit message that could. So much conveyed, with only as much text as it needs. This is more to type than 50 character -m message, but wouldn’t you already have this kind of information in your head if you had just made this change? There’s not a lot of extra work to make this happen.
62. doodling.dev @doodlingdev Let’s take a look at an example from the rails repo.
63. doodling.dev @doodlingdev Fix secret_key_base for Railties This was missed in the security fix for local dev. CI doesn’t have a tmp directory in the apps built for testing so these end up failing. This adds the secret_key_base so we don’t need to generate one.
64. doodling.dev @doodlingdev This talks about the problem being fixed, even where and how the bug was introduced. That can certainly be useful. Mentions what this commit adds, and why. Again, this is less than the amount of information that you would share with someone who walked by your desk and asked what you were working on.. but it gives us a LOT to work with if we’re thinking of changing the underlying code here.
65. doodling.dev @doodlingdev What made those messages better than some of the others we’ve looked at? [click] context. Why is context important? Well to illustrate my point, I'm going to go back to a Dr Seuss story,
66. doodling.dev @doodlingdev Context What made those messages better than some of the others we’ve looked at? [click] context. Why is context important? Well to illustrate my point, I'm going to go back to a Dr Seuss story,
67. doodling.dev @doodlingdev “Dr. Seuss” == “Theodore Geisel” #=> true not a seussical poem, but a story about Theodore Geisel (his real name) and one of his stories, Horton hears a who
68. doodling.dev @doodlingdev In which, an elephant named Horton vows to protect a tiny civilization floating on a spec of dust, met with ridicule from the other animals who can't or won't hear them. Horton proclaims "A person's a person no matter how small." Here's some context for you.
69. doodling.dev @doodlingdev Theodore Geisel was born in 1904, and like many white people of the time was pretty darned racist. I'm not going to put those images on screen, but famously he drew troubling images of Japanese citizens in the run up to World War II as a political cartoonist, amongst many other examples.
70. doodling.dev @doodlingdev But after the war, he travelled to Japan and met the people there, saw their relationship with the American Occupation, and heard their direct experience with nuclear weapons... and wrote Horton Hears a who as an allegory about the war. Some lines in there are straight up a reference to the atom bomb falling out of the sky.
71. doodling.dev @doodlingdev He also drew this cartoon.. it says.....
72. doodling.dev @doodlingdev Without the context, Horton is a silly book with a good message, with context it becomes one man's attempt to admit to the wrongs of his past attitudes in a very public way, and influence others to realize the same mistakes in themselves, or at least inoculate the youngins as best he could.
73. doodling.dev @doodlingdev Code Context Just as a work of art cannot be fully understood without context, code can be difficult to impossible to wrap your head around without it.
74. doodling.dev @doodlingdev Who What Where When How The commit itself is going to tell you Who, What, Where, When, How.. but it's missing WHY. Its a blessing and a curse of programming that there are a million different ways to solve every problem. It's less like engineering and math, and more like creative writing.
75. doodling.dev @doodlingdev Software Craftsman novelist We're constantly making decisions that have consequences to the future, and there's always a reason that we make the decisions we do. Record that reason in a commit message, because you or someone else might need it. How many times have you looked into a file that you didn't write only to think, "Why does this look like this?"
76. doodling.dev @doodlingdev Wouldn't it be great if we could hover over a line of code in our editors and read a note explaining exactly why a thing looks the way it does?
77. doodling.dev @doodlingdev Rhetorical Question You can, here it is in VSCode
78. doodling.dev @doodlingdev This is an extremely popular extension called Git Lens. This file is in the Rails source code, ActiveRecord, you can see the module name. Lets jump down a few lines and hover the mouse on line 44.. Have you ever had an annotated Shakespeare book before? How about annotated source code.. you ALREADY HAVE IT Who is all this context for, anyway?
79. doodling.dev @doodlingdev This is an extremely popular extension called Git Lens. This file is in the Rails source code, ActiveRecord, you can see the module name. Lets jump down a few lines and hover the mouse on line 44.. Have you ever had an annotated Shakespeare book before? How about annotated source code.. you ALREADY HAVE IT Who is all this context for, anyway?
80. doodling.dev @doodlingdev Do unto Others *Other Developers* who are changing this code, or using this API, or debugging an issue anyone who might write something that executes our code in the future.
81. doodling.dev @doodlingdev But aji… counterpoint: what if i'm the only one working on this?
82. doodling.dev @doodlingdev You are other developers Great! "Other Developers" can mean you in the future.
83. doodling.dev @doodlingdev Code Review To properly review code, you're going to need more than just seeing the change. Especially if you're using a tool that truncates a diff, the reviewer might not even be seeing all the code that's affected by the change.
84. doodling.dev @doodlingdev Do you see there on the left, [click] the line numbers go from 120 to 167. 47 lines of hidden code. Who knows what could be in there without opening each and every fold.
85. doodling.dev @doodlingdev Do you see there on the left, [click] the line numbers go from 120 to 167. 47 lines of hidden code. Who knows what could be in there without opening each and every fold.
86. doodling.dev @doodlingdev But aji… “counterpoint: that's what the PR comment is for.” 100% agree. That means you're already thinking that context is important, so why wouldn't you save it in the history instead of throwing it out when the code gets merged?
87. doodling.dev @doodlingdev Makes the dream Work Has anyone ever searched for something because you're stuck, only to find a blog post from one of your colleagues, or even yourself, that gives you the answer? You can have that without googling, or if your internet is down [sign of the cross] with rich messaging.
88. doodling.dev @doodlingdev Cogito ergo Summary What's going to be easier to capture, context while you're closer to your thoughts, or a summary at the end of feature work after the fact? Its the same with TDD, writing tests up front and as you work, or going back in and struggling to cover all your bases.
89. doodling.dev @doodlingdev The laziness Argument I'm willing to admit that it's what won me over to actually *doing* TDD instead of just thinking its a good idea. When you're in the middle of feature development, you have all the energy of an exciting new task. And if we write our thoughts in the git history as we go, we can leverage that immediacy and capture helpful information for the project's future developers.
90. doodling.dev @doodlingdev Tooling ftw And tooling makes it easy to copy out any relevant information for code review into the PR.
91. doodling.dev @doodlingdev Less Is more The body of a commit message doesn't need to be a novel, or an entire page of documentation. The explanation should match the size of the context to share. What do we write?
92. doodling.dev @doodlingdev Public interface? If it’s part of a public interface, how could it be used or extended? What's relying on it not to change?
93. doodling.dev @doodlingdev Convention over Confusion We're Rails developers, we love conventions. We can all speak more or less the same language, and it should be easy for new developers to come onto a project if it all looks "Railsy" enough. Did something need to go against a convention for some reason?
94. doodling.dev @doodlingdev Cross Contamination Is there a non-obvious side effect that falls out of the change?
95. doodling.dev @doodlingdev Frankenstein’s Docs This never happens but, did the actual execution of a library not line up with the documentation?
96. doodling.dev @doodlingdev It’s dangerous To go alone Are they any gotchas this code introduces? Are there any pitfalls that you saw when you were up to your elbows in this subsystem that would be good to know about in the future? think what precise domain knowledge you have *right then* that you want to remember.
97. doodling.dev @doodlingdev Flying Solo Try to write a message that will make sense without seeing the code. Not to replicate the code method for method, but if reading the git logs without the code open makes sense, the history becomes a much more useful document.
98. doodling.dev @doodlingdev My emotional Support commit Is there an external resource that applies? Link to - a ticket - a feature spec or user story - PR comments - Slack discussions can be deep linked - Resources you used: stack overflow answers, blog posts, videos, documentation, or specifications. But remember that links aren’t forever, the message should still make sense.
99. doodling.dev @doodlingdev Not another learning experience… We all refer to old code as a reference from time to time. "How did I solve this last time?" A little explanation and you're leaving breadcrumbs about how a design pattern, library or technique worked or didn't work, you're able to be one step ahead next time.
100. doodling.dev @doodlingdev Tag Team I've had some success with tagging my messages. Not git's tags, plain text tags to search either with GitHub's search box or with git log on the command line. an example...
101. doodling.dev @doodlingdev $tagname I use this convention when it’s some piece of work I might want to refer back to, and I try to give it a good name, but y’know.. only two hard problems…
102. doodling.dev @doodlingdev I’m in a repo of code for a workshop I led, and I think what I need is near the beginning, so I’ll log in reverse…
103. doodling.dev @doodlingdev I’m in a repo of code for a workshop I led, and I think what I need is near the beginning, so I’ll log in reverse…
104. doodling.dev @doodlingdev Well I didn’t see it, so we’ll try to grep. Because the command is a regex after the =, we have to escape the ‘$’ Here’s the syntax for the command, ——grep=query
105. doodling.dev @doodlingdev Well I didn’t see it, so we’ll try to grep. Because the command is a regex after the =, we have to escape the ‘$’ Here’s the syntax for the command, ——grep=query
106. doodling.dev @doodlingdev git log - -grep=<query> Well I didn’t see it, so we’ll try to grep. Because the command is a regex after the =, we have to escape the ‘$’ Here’s the syntax for the command, ——grep=query
107. doodling.dev @doodlingdev git log - -grep=<query> There it is!
108. doodling.dev @doodlingdev git log - -grep=<query> There it is!
109. doodling.dev @doodlingdev Unpopular opinion self-documenting, completely self-contained context-free code is an unrealistic myth, and at worst an excuse not to try.
110. doodling.dev @doodlingdev Don’t @ me Even if you're using a tool like yard, or jsdoc, (both of which I really like) to generate API documentation, that's just adding more what.
111. doodling.dev @doodlingdev Right tool Right place Right time And why we wrote some code one way isn't necessarily going to be helpful for someone looking up what arguments a function takes, so "why" doesn't go there. but It can be helpful for someone who is making a change to the code.
112. doodling.dev @doodlingdev Out of Sync api docs and code comments don't stay in sync with the code as written, but commit messages persist exactly the same length of time as the code they describe. because new code necessarily changes the messages.
113. doodling.dev @doodlingdev Home free Change your code and update docs for free
114. doodling.dev @doodlingdev In practice so we've talked about why we want to write better messages, and how we can assemble a useful git history. It sounds like we're going to get to know our way around some parts of git that might be unfamiliar.
115. doodling.dev @doodlingdev Because treating the commit history as a kind of documentation requires a little more thought towards what commits you leave behind.
116. doodling.dev @doodlingdev Because treating the commit history as a kind of documentation requires a little more thought towards what commits you leave behind.
117. doodling.dev @doodlingdev Git has a lot of baked in tools to help us accomplish just that. Like the message template.
118. doodling.dev @doodlingdev Many of us are probably familiar with this message, it’s what appears when you start a new commit from the command line. This is customizable. It doesn't have to be the same as this. If a teams has a standard of what should be included in a message, we can leave prompts for ourselves to fill in.
119. doodling.dev @doodlingdev Remember the default message, any line with an # will be ignored. On line 12 we see “Closes.” [click] With an issue number, Github will close the related issue once this commit is merged to the default branch
120. doodling.dev @doodlingdev Remember the default message, any line with an # will be ignored. On line 12 we see “Closes.” [click] With an issue number, Github will close the related issue once this commit is merged to the default branch
121. doodling.dev @doodlingdev close fix resolve Any of these keywords will work for GitHub, close, closes, closed etc. If you don’t use github, many other tools have similar features as well.
122. doodling.dev @doodlingdev This example has width guides in case we can’t set a hard wrap. [click] Also includes a reference to tags in the subject line. This is a convention popular in projects like Angular, Electron and other places. [click] It’s called ‘conventional commits’ I’m not going to touch on that here, but the super simplified version: to make commit messages both more human readable and helpful, but also machine parseable.
123. doodling.dev @doodlingdev This example has width guides in case we can’t set a hard wrap. [click] Also includes a reference to tags in the subject line. This is a convention popular in projects like Angular, Electron and other places. [click] It’s called ‘conventional commits’ I’m not going to touch on that here, but the super simplified version: to make commit messages both more human readable and helpful, but also machine parseable.
124. doodling.dev @doodlingdev To make this template thing happen, we make a plain text file. It'll look like... Yup. Just that. Whatever we want to have at the top, write it in. Save this wherever you want, perhaps you have a dotfiles management system? I'll happily geek out about that in the hall after if anyone wants. You know who you are.
125. doodling.dev @doodlingdev Tell git where to find the template in the gitconfig. That's a file that lives in the home directory, [click] Or for windows…
126. doodling.dev @doodlingdev ~/.gitconfig Tell git where to find the template in the gitconfig. That's a file that lives in the home directory, [click] Or for windows…
127. doodling.dev @doodlingdev ~/.gitconfig C:\ProgramData\Git\config Tell git where to find the template in the gitconfig. That's a file that lives in the home directory, [click] Or for windows…
128. doodling.dev @doodlingdev there are plenty of configuration options possible in here, but the one we care about right now is this… Commit in brackets is the section heading Template equals and then the path to the file we just made If this is the only configuration in this file, its totally valid.
129. doodling.dev @doodlingdev And that is commit templates.
130. doodling.dev @doodlingdev And that is commit templates.
131. doodling.dev @doodlingdev
132. doodling.dev @doodlingdev
133. doodling.dev @doodlingdev wohpos Sometimes small changes need to happen after a commit, whitespace fix, or we want to change a variable name, but we’ve written a really great message. Insightful, future-aware comment.
134. doodling.dev @doodlingdev Sometimes small changes need to happen after a commit, whitespace fix, or we want to change a variable name, but we’ve written a really great message. Insightful, future-aware comment.
135. doodling.dev @doodlingdev What’s that going to do to the messages for that file?
136. doodling.dev @doodlingdev Whoops What’s that going to do to the messages for that file?
137. doodling.dev @doodlingdev Kind of a contrived example, but here’s a bit of code. [click] We see there are some typos. Autocomplete makes that easy sometimes, means it’s valid code, but it’s gotta be fixed. [click] If we fix the typo and commit again.. what are the commit messages going to look like?
138. doodling.dev @doodlingdev Kind of a contrived example, but here’s a bit of code. [click] We see there are some typos. Autocomplete makes that easy sometimes, means it’s valid code, but it’s gotta be fixed. [click] If we fix the typo and commit again.. what are the commit messages going to look like?
139. doodling.dev @doodlingdev Kind of a contrived example, but here’s a bit of code. [click] We see there are some typos. Autocomplete makes that easy sometimes, means it’s valid code, but it’s gotta be fixed. [click] If we fix the typo and commit again.. what are the commit messages going to look like?
140. doodling.dev @doodlingdev Good messages on all the lines, but the typo fix overrides it on some fairly important places. Sometimes there are changes that aren’t worth a commit message, but there needs to be a commit. Or maybe there’s a commit you need for development that doesn’t need to be pushed up or merged.
141. doodling.dev @doodlingdev Good messages on all the lines, but the typo fix overrides it on some fairly important places. Sometimes there are changes that aren’t worth a commit message, but there needs to be a commit. Or maybe there’s a commit you need for development that doesn’t need to be pushed up or merged.
142. doodling.dev @doodlingdev right? You don't have to re-type or copy paste messages, there's a command to merge commits, and we can sweep that typo or WIP under the rug, no one needs to know it ever existed.
143. doodling.dev @doodlingdev git rebase -i If you've had trouble with rebase in the past, that's alright, we don’t need to grok the concept in the same way with this technique, “-i” means this is interactive rebase and we're just going to change within our current branch This allows us a lot of flexibility in manipulating the commit history, and it’s done by opening a text file in your chosen editor… more on that in a minute.
144. doodling.dev @doodlingdev This file is going to serve as a set of instructions to git on how it should handle each commit. We see they’re listed out in order, oldest to newest. * First is the action we want git to take for each commit, defaulting to “pick” * Second is the shortform hash that acts as id for the commit * Finally, the subject line of our commit message
145. doodling.dev @doodlingdev Note here the body of the messages are not displayed. Just the subject for now. Another reason why a descriptive subject line is important. Try messing around with the git history with a bunch of subject lines like “some changes to model” And helpfully the available actions we can use are listed below in the commented out portion. I’ve lightened some because today we’re going to cover those four only.
146. doodling.dev @doodlingdev First up is “pick”. It’s the default action for each commit, and it basically means, use this commit. Don’t do anything, replay it into the history just the way it is.
147. doodling.dev @doodlingdev First up is “pick”. It’s the default action for each commit, and it basically means, use this commit. Don’t do anything, replay it into the history just the way it is.
148. doodling.dev @doodlingdev First up is “pick”. It’s the default action for each commit, and it basically means, use this commit. Don’t do anything, replay it into the history just the way it is.
149. doodling.dev @doodlingdev Next is reword. Use commit, but edit the commit message. Lets take a look at what a reword action looks like in practice.
150. doodling.dev @doodlingdev Next is reword. Use commit, but edit the commit message. Lets take a look at what a reword action looks like in practice.
151. doodling.dev @doodlingdev Next is reword. Use commit, but edit the commit message. Lets take a look at what a reword action looks like in practice.
152. doodling.dev @doodlingdev Before we start, let’s take a look at the commit we want to change, it’s the last commit relative to where we are now, [click] so we use git log HEAD~ to mean show me the message on the commit right before HEAD We don’t need to memorize the content here to understand what happens next, so let’s continue
153. doodling.dev @doodlingdev Before we start, let’s take a look at the commit we want to change, it’s the last commit relative to where we are now, [click] so we use git log HEAD~ to mean show me the message on the commit right before HEAD We don’t need to memorize the content here to understand what happens next, so let’s continue
154. doodling.dev @doodlingdev We’ll use our git rebase -i to get started
155. doodling.dev @doodlingdev We’ll use our git rebase -i to get started
156. doodling.dev @doodlingdev First step is to change the text on the line of the commit we want to reword. Then save and close the file. Git will read in those instructions and proceed…
157. doodling.dev @doodlingdev First step is to change the text on the line of the commit we want to reword. Then save and close the file. Git will read in those instructions and proceed…
158. doodling.dev @doodlingdev
159. doodling.dev @doodlingdev
160. doodling.dev @doodlingdev Git opens a commit prompt, same as if it was a brand new commit, but prepopulated with the message that currently exists. We’re going to make a really obvious change to show what’s going on. [click] Note we’re not changing the subject here, but we could if we wanted to.
161. doodling.dev @doodlingdev Git opens a commit prompt, same as if it was a brand new commit, but prepopulated with the message that currently exists. We’re going to make a really obvious change to show what’s going on. [click] Note we’re not changing the subject here, but we could if we wanted to.
162. doodling.dev @doodlingdev Let’s log the same message and see what it looks like now [click] All changed! I’ll superimpose the old log..[click] And you can see, the commit hash has changed because the content of the commit changed in the message. But the date, everything else stays the same.
163. doodling.dev @doodlingdev Let’s log the same message and see what it looks like now [click] All changed! I’ll superimpose the old log..[click] And you can see, the commit hash has changed because the content of the commit changed in the message. But the date, everything else stays the same.
164. doodling.dev @doodlingdev Let’s log the same message and see what it looks like now [click] All changed! I’ll superimpose the old log..[click] And you can see, the commit hash has changed because the content of the commit changed in the message. But the date, everything else stays the same.
165. doodling.dev @doodlingdev Next is “squash,” I find it the most useful for managing unnecessary commits, or creating commits that more succinctly encompass the work for a branch. [click] Because sometimes development needs more commits than we’ll need in master.
166. doodling.dev @doodlingdev Next is “squash,” I find it the most useful for managing unnecessary commits, or creating commits that more succinctly encompass the work for a branch. [click] Because sometimes development needs more commits than we’ll need in master.
167. doodling.dev @doodlingdev Next is “squash,” I find it the most useful for managing unnecessary commits, or creating commits that more succinctly encompass the work for a branch. [click] Because sometimes development needs more commits than we’ll need in master.
168. doodling.dev @doodlingdev I’m looking at these three commits Seems like they’re doing very similar things, and I want to have the messages and changes merged into one commit to push it up for code review.
169. doodling.dev @doodlingdev I’m looking at these three commits Seems like they’re doing very similar things, and I want to have the messages and changes merged into one commit to push it up for code review.
170. doodling.dev @doodlingdev I’m looking at these three commits Seems like they’re doing very similar things, and I want to have the messages and changes merged into one commit to push it up for code review.
171. doodling.dev @doodlingdev What I want to do is take the commits on lines 3 & 4, and merge them into the commit on line 2. When you label a commit for squashing, [click] it will be merged into the commit before it. So remember that. Squashes move UP
172. doodling.dev @doodlingdev What I want to do is take the commits on lines 3 & 4, and merge them into the commit on line 2. When you label a commit for squashing, [click] it will be merged into the commit before it. So remember that. Squashes move UP
173. doodling.dev @doodlingdev And because the contents of the commit has changed, [click] We’ll amend the subject too Let’s see it in practice
174. doodling.dev @doodlingdev New subject line! And because the contents of the commit has changed, [click] We’ll amend the subject too Let’s see it in practice
175. doodling.dev @doodlingdev We’ll fire up interactive rebase
176. doodling.dev @doodlingdev We’ll fire up interactive rebase
177. doodling.dev @doodlingdev Same as before but now we choose squash. Save and quit.
178. doodling.dev @doodlingdev Same as before but now we choose squash. Save and quit.
179. doodling.dev @doodlingdev This file that is opened is where we tell git what to do with the messages, as three commits become one [click] Each message is delineated with a comment. [click] And each section consists of the commit’s subject, a blank line, and the message. If we did nothing, the new commit message would look just like this without the comments. [click] But it doesn’t seem necessary to me to keep the outdated subjects. I remove the comments too so I can see what the finished message will look like.
180. doodling.dev @doodlingdev This file that is opened is where we tell git what to do with the messages, as three commits become one [click] Each message is delineated with a comment. [click] And each section consists of the commit’s subject, a blank line, and the message. If we did nothing, the new commit message would look just like this without the comments. [click] But it doesn’t seem necessary to me to keep the outdated subjects. I remove the comments too so I can see what the finished message will look like.
181. doodling.dev @doodlingdev This file that is opened is where we tell git what to do with the messages, as three commits become one [click] Each message is delineated with a comment. [click] And each section consists of the commit’s subject, a blank line, and the message. If we did nothing, the new commit message would look just like this without the comments. [click] But it doesn’t seem necessary to me to keep the outdated subjects. I remove the comments too so I can see what the finished message will look like.
182. doodling.dev @doodlingdev This file that is opened is where we tell git what to do with the messages, as three commits become one [click] Each message is delineated with a comment. [click] And each section consists of the commit’s subject, a blank line, and the message. If we did nothing, the new commit message would look just like this without the comments. [click] But it doesn’t seem necessary to me to keep the outdated subjects. I remove the comments too so I can see what the finished message will look like.
183. doodling.dev @doodlingdev The first line will become our new subject, [click] and this doesn’t accurately reflect what this commit is changing, so we can update that as well.
184. doodling.dev @doodlingdev The first line will become our new subject, [click] and this doesn’t accurately reflect what this commit is changing, so we can update that as well.
185. doodling.dev @doodlingdev And we’ll take a look at the new commit now that we’re all done. I’m going to use git log - - oneline to see a compact version of the log with only subjects
186. doodling.dev @doodlingdev And we’ll take a look at the new commit now that we’re all done. I’m going to use git log - - oneline to see a compact version of the log with only subjects
187. doodling.dev @doodlingdev and copy the shortcode to use for our git logging. Start the printout at that specific commit. [wait] and there it is.
188. doodling.dev @doodlingdev and copy the shortcode to use for our git logging. Start the printout at that specific commit. [wait] and there it is.
189. doodling.dev @doodlingdev Finally, “fixup” which doesn’t need a whole runthrough, because fixup merges UP, like squash, but the commit message is just deleted. This is perfect for those typos or whitespace commits.
190. doodling.dev @doodlingdev Finally, “fixup” which doesn’t need a whole runthrough, because fixup merges UP, like squash, but the commit message is just deleted. This is perfect for those typos or whitespace commits.
191. doodling.dev @doodlingdev Finally, “fixup” which doesn’t need a whole runthrough, because fixup merges UP, like squash, but the commit message is just deleted. This is perfect for those typos or whitespace commits.
192. doodling.dev @doodlingdev The never- Ending story I could literally spend another hour up here going through git commands and minutia so if you wanted more of that, I sincerely hope you went to Chris Toomey’s incredible deep dive into git workshop on Wednesday
193. doodling.dev @doodlingdev As for me, I made a bold promise in the talk description that I would teach you how to do all of this git wrangling in an editor other than VIM
194. doodling.dev @doodlingdev Hold your Horses first! I want to show you how to use VIM juuuust enough to not have to open another application… So you can stay in the terminal for all your message crafting needs.
195. doodling.dev @doodlingdev Git commit will likely drop you into VIM, yes. And that can be a scary place if you don’t know all of the arcane incantations required.
196. doodling.dev @doodlingdev Git commit will likely drop you into VIM, yes. And that can be a scary place if you don’t know all of the arcane incantations required.
197. doodling.dev @doodlingdev But you can handle committing, and message editing with three commands.
198. doodling.dev @doodlingdev But you can handle committing, and message editing with three commands.
199. doodling.dev @doodlingdev Nothing works the way you’re used to when you first get into vim
200. doodling.dev @doodlingdev Nothing works the way you’re used to when you first get into vim
201. doodling.dev @doodlingdev That’s because you’re in a mode for navigating the text, not editing. To edit you must enter insert mode.
202. doodling.dev @doodlingdev That’s because you’re in a mode for navigating the text, not editing. To edit you must enter insert mode.
203. doodling.dev @doodlingdev Press i to get into insert mode. Then you can type and move around the way you’re used to. Even with the arrow keys work here.
204. doodling.dev @doodlingdev Press i to get into insert mode. Then you can type and move around the way you’re used to. Even with the arrow keys work here.
205. doodling.dev @doodlingdev When you’re done editing, you’ll need to press escape. No mnemonic. Cancel out of insert mode by pressing escape.
206. doodling.dev @doodlingdev When you’re done editing, you’ll need to press escape. No mnemonic. Cancel out of insert mode by pressing escape.
207. doodling.dev @doodlingdev To complete the process you’ll type :wq Colon to enter a command, W to WRITE
 and q to QUIT That’s i, type your message, escape, : write quit.
208. doodling.dev @doodlingdev To complete the process you’ll type :wq Colon to enter a command, W to WRITE
 and q to QUIT That’s i, type your message, escape, : write quit.
209. doodling.dev @doodlingdev now, you know vim
210. doodling.dev @doodlingdev now, you know vim
211. doodling.dev @doodlingdev One of us! One of us! But if you feel the need to use another editor, all we’re going to have to do is open up that gitconfig and add another setting.
212. doodling.dev @doodlingdev Core as the heading Editor equals then the command to open your editor from the command line. Sometimes you’re going to have to install that command, it should be in your editor’s FAQ or the like if you don’t have it already set.
213. doodling.dev @doodlingdev If you use a GUI editor, definitely for Atom, VSCode, or Sublime, you’ll need to append - - wait to the command, or it will only open a blank file.
214. doodling.dev @doodlingdev git config - -global core.editor “atom - -wait” Or you can run this command from the command line once.
215. doodling.dev @doodlingdev git config - -global core.editor “atom - -wait” I am basically out of time, but I want to let you know I will be tweeting out a copy of these slides, as well as a post about all of the things I didn’t get to cover.
216. doodling.dev @doodlingdev git config - -global core.editor “atom - -wait” because after running my talk for the first time, I realized it was two hours long.. and some things just had to go.
217. doodling.dev @doodlingdev git config - -global core.editor “atom - -wait” Things like a mini review of my opinions on plugins for most of the major editors and more useful git commands for reading and managing commit history.
218. doodling.dev @doodlingdev I apologize for not being able to get it all together for you,
219. doodling.dev @doodlingdev but we were woken up this morning by a call from our doggie daycare that they had to rush my little boy to the vet, he’s fine, but its obviously left me with less time than I thought I had. So, I’m not religious or anything, but hugs at a distance for Henson please.
220. doodling.dev @doodlingdev I hope you all have formed or started to form your own idea of what a "good" commit message is.
221. doodling.dev @doodlingdev I think you’ll find the answer to "how do we write good commit messages?" is different in every team, every person, and every situation, while still considering its usefulness
222. doodling.dev @doodlingdev I'm going to close with my answer to that. A line that is very quickly becoming my personal catchphrase..
223. doodling.dev @doodlingdev I'm going to get it tattooed, written on my gravestone & hire a skywriter.
224. doodling.dev @doodlingdev The answer, like the answer to most things, is with empathy.
225. doodling.dev @doodlingdev Commit with Empathy Empathy for you teammates, empathy for yourself, empathy for developers of the future you might never meet.
226. doodling.dev @doodlingdev Commit with Empathy Someone earlier in the week said something that i LOVE. When I told them about my talk, they called me a 'commit message archaeologist'.
227. doodling.dev @doodlingdev So I encourage you to be commit message archaeologists, and at the same time.. to leave something behind that can be useful for fellow archaeologists.
228. doodling.dev @doodlingdev So I encourage you to be commit message archaeologists, and at the same time.. to leave something behind that can be useful for fellow archaeologists.
229. doodling.dev @doodlingdev And even if you can't convince everyone else you work with that commit messages should be more than
230. doodling.dev @doodlingdev And even if you can't convince everyone else you work with that commit messages should be more than
231. doodling.dev @doodlingdev if you're one in a team of five, then taking up the mantle of meaningful commit messages still means that you'll have 20% more of a chance that a commit message can save your bacon, too. And once your message saves someone else.. maybe it'll be a 40% chance, then 60 So I’ll leave you with that thought and a paraphrased quote
232. doodling.dev @doodlingdev Be the change you want to see in the code Thank you