Telling better stories with Git, by Tekin Suleyman


As developers we know the importance of writing “good” commit messages. But commits do not exist in isolation: They form part of the wider narrative that is the evolution of our code. How we structure these commits, the order in which they appear, their size and shape, all help to tell the story of how our code got to where it is today.

In this talk we’ll look at why the narrative of our revision history is so important for a maintainable codebase. More importantly, you'll learn concrete techniques and practices you can use to tell better stories with your commits and pull requests.


As the old adage goes: Software is never "done". It evolves and shifts, often in unexpected ways. And just as writing tests and refactoring are important in keeping a codebase maintainable, so is taking deliberate time to compose and structure our commits such that they provide a helpful narrative of our code's evolution.

This talk will be in two parts. Part 1 will look at why the narrative of the revision history is so important for the maintainability of our code, and explore what makes for a good narrative. Part 2 will cover practical techniques and practices attendees can use to tell better stories using Git.

This talk will be particularly useful for people who are less experienced Git users. Many get by with “git add .” and “git commit -m”. Most likely they do not have the support or confidence to go beyond this and learn the more advanced techniques and Git commands that help create a well-structured revision history. This talk will demystify some of these techniques with practical examples and explanations. Even the more experienced Git users should come away with something new: whether a handy new shortcut or pattern, or a deeper appreciation of the power of a well-kept revision history.


My experience working with many teams over the years has taught me that Git hygiene, and it's power to make a codebase more maintainabile, is an often overlooked and underappreciated aspect of software development. Part of this I think is simply down to the fact that less has been written and shared on the subject.

Git gives us useful tools to construct good stories with our commits. The problem is it doesn't make it very easy. It's obscure commands and flags, whilst powerful, are difficult to understand and can be scary to use. I've been fortunate enough to work with some fantastic developers over the years who have helped me both appreciate the importance of maintaining a good revision history, and also taught me ways to use get the most out of Git to create one. I want to help others gain the same appreciation and skills.

Edit proposal


RailsConf 2018 - Rejected [Edit]

Add submission