"Git hook[ed]” on images & up your documentation game

By Veronica Hanus

Elevator Pitch

Can you remember the difference between two hex color values? Me neither! Entering visual representations of recent-changes into version control makes review of past changes easier & speeds acclimation to a new web project. Join me for a review of current methods & how to choose the best for you!


Can you remember the difference between two hex color values? Me neither! Entering visual representations of recently-changed elements into version control makes review of past changes easier & speeds acclimation to a new web project, especially for visual learners. Surprisingly, methods for including images in your version control aren’t standardized and are rarely used outside of large companies, and the rest of us are left checking out every major commit and viewing changes locally! Join me for a review of methods currently in use and discuss the benefits and drawbacks of each. The audience will learn from a survey of tools used by both designers and web developers, what methods are most appropriate for individual projects, & how these methods differ from those used at some of the largest companies (Google, eBay, etc.). Finding a method to track changes in your visual elements will save our future contributors (and future selves!) the pain of having to distinguish #2dc651 (lime green) from #34a34e (darker(!) lime green) and ultimately make our commit histories cleaner and our repos easier to navigate in ways that many of us have never imagined!


About me & this topic

Before I was a programmer, I worked with in a science that relies on visual work and spent a lot of time thinking about how to incorporate our images and screenshots into our research. As I entered web development, I found myself asking the same questions and began learning as much as I could about ways that folks do/don’t incorporate images into their workflows and what they see as the benefits/costs. I’ve given this talk locally and this will be it’s first time at a regional conference.


Intro of me / what I do :: 1min

  • Python + web, interested in how things work & how people use them
  • In my academic life, worked as a lab researcher & enjoyed thinking about the problems / inefficiencies of the processes used in their research setting and taking that perspective to learning web dev

Statement of problem :: 4 mins

  • Version control is text-based: Text in code diffs, text in commits
  • Text-based version control increases cognitive load for the programmer
  • Different learning strategies work for different folks
    • 65% of people are visual learners, supporting them supports potential contributors
  • Example site change & associated tracking
  • Online diff shows only hex color & any added comments
  • Editor with plug-in to show color will display hex color, but need to be viewing locally to use
  • I will have an example site to demonstrate a few changes consistently so my audience can concentrate on the tools/methods and not my changes! My demos will be recorded and gathered in a repo for later consumption / ease of access during the talk. A blog post will be added for later reference.

The Hacks :: 5 mins

  • Screenshots of before/after saved with a commit describing the change
  • Limitations: when/how is this viewed, extra trouble of making the screenshots
  • Great stuff: makes a record, faster than opening up Github or Git diff & plugging the hex into a hex-viewer
  • Color changes can be viewed in-editor with a plug in
  • Examples: Atom’s Pigments (view colors in editor) & Color Picker (select/add colors in editor), Sublime’s Color Highlighter (view colors in editor)
  • Limitations:
  • Doesn’t help with non-color changes, such as spacing, fonts, etc.
  • Most useful for folks who have a terminal -> editor flow for reviewing past commits, not those who view in Github

The Tools :: 10 mins

  • Puppeteer (Node library API to control Chrome & Chromium)
  • What / how Puppeteer works
  • Best use / applications
  • Steps to add to workflow
  • Demo
  • Benefits: Screenshot is automated & can be entered into source control
  • Alternative: Selenium/WebDriver (cross-browser)
  • Testing for Screenshot & HTML diffing
  • Common for companies (Google, eBay (documentation ), Servo) to use an internal process for screenshot diffing, not a external tool
    • I have arranged to interview people at each company to discuss their different approaches.
  • Two strategies: Screenshot & HTML comparison
  • Screenshots taken when tests fails, developer compares & confirms new screenshot should be committed
  • HTML
  • Benefits: Automated process
  • Limitations: Screenshot is still one commit behind & inaccessible for most developers/projects

Learn from other visual creators :: 5 mins

  • Tools for designers
    • Abstract’s Compare Mode
    • Git-like functionality
    • No integration
  • Sketch’s Pages & Artboards (scroll through to see changes) [demo]
  • Zeplin (for smaller, less easily spotted changes) [demo]
  • Powerful to realize other creators started at visuals and created tool with Git-like functions while I was starting with Git and incorporating visuals

Modify workflows to work for you :: 5 mins

  • Use Git hooks to initiate screenshots at the times that make sense to you
  • My favorites
  • File size considerations & workarounds
  • Managing your Git hooks (you can use Python!)
  • Other uses: Lolcommits project offers “git-based selfies” by taking webcam picture of the developer at the time of the commit. If it can be used for that, we sure can use it for screenshots!

Lessons & empowering send-off :: 1min

  • This is a problem a lot of people think about & there are many different solutions
  • Time is saved by improving clarity, another way to support a variety of contributors
  • Pick what is best for you:
    • Puppeteer/Selenium/WebDriver for screenshots taken at every change
    • Abstract/Zeplin/Sketch for scroll-through visuals to be used alongside your version control
    • Hand-created screenshots checked into version control
    • Editor plugins that help you visualize the colors on your site
    • Integrations with Git hooks

Key takeaways

  • Including visual representations of your work in version control has the potential to be a powerful tool for anyone, and will be especially helpful to the 65% of people who are visual learners.
  • There are many ways to include screenshots of your work, including using tools developed for screenshot diffing (automated testing), but screenshots are still uncommon outside of the design field.
  • Your experience can be further customized & streamlined with the use of web hooks.
  • Incorporating existing & customized tools and learning from other creators allows us to create a system that meets our needs and provides big gains in lowering cognitive load for yourself and others.

Intended Audience

Intermediate web-developers, Open source maintainers & contributors (Increasing Accessibility & Diverse Learning Styles), Designers