Wheeeeee

Ringing in the new year with new tools!

Cleandiff

CleanDiff is a graphical diffing tool that pays attention to word instead of lines.

Why

Two reasons:

1. I hate looking at diffs of changed lines and knowing something changed, but having to hunt for what that something is.
2. Too much noise. In addition to wanting to see the specific “word” or “character” that changed, I don’t want to have to scroll through the entire document to get to it, or the opposite problem where something like git diff shows you a tiny bit of context, but not enough.

git-com

git-com is a tool for creating structured commit messages that’s easy to configure for each project. A simple YAML document at the repo’s root drives an interactive UI with select lists and text fields to easily populate your commit message with structured, and repeatable elements.

[front-end] bug-fix: item listing works with large minimum font size

Text elements started overlapping each other when a user had a
minimum font size set in their browser.

Tags: accessibility, css

That commit message could have been created with the following elements

<code-section> <work-type>: <title>

<description>

<tags>

Why

This is yet another entry in a collection of tools to help answer questions about what’s changed in a codebase. Sometimes it’s that simple. Sometimes it’s trying to find where a bug introduced. Sometimes it’s to be able to have an accurate accounting for stakeholders.

Good commit messages have saved me countless hours of spelunking when I was in charge of a support-engineering team (putting out fires in production), and as a release manager trying to figure out what actually made it into the impending release.

In things like my dotfiles repo, they’ve been useful for just knowing what part of my system a commit pertains to. In my writing it lets me know which book I was making changes in, and if it was new writing, or edits.

Codebase Example

[fix] was erroring if run from a subdirectory
[fix] icon in readme on github
[fix] removed unecessary blank line from .git-com.yaml
[fix] removed flag from script to update homebrew tap
[add] added quick-start to docs
[clean-up] simplified .git-com.yaml

Writing Example:

[ji-woo] renamed 2 of the container kids
[thimble] finished telling taylor's dad about thimble
[thimble] few days worth of editing and adding
[worldbook] added info re cats barely growing
[worldbook] added / updated content warning stuff
[nicole] finished off day after meeting ji-woo

options_parser

options_parser is a new options parser for Ruby

It supports

• auto-generated help docs
• required & optional arguments
• short and/or long variations
• arguments that take values, or just act as flags
• separating flag from value with space or equals
• auto-conversion to integer or float as defined by the value_type
• trailing arguments Ex. `command -n 4 – file_1.txt file_2.txt`

A simple example

options = {}
parser = OptionsParser::Parser.new(
            command: "myapp",
            description: "Does something useful") do |p|

  p.on(short: "-f",
       long: "--file",
       value_type: :string,
       help: "Input file path") do |value|
    options[:file] = value
  end
end
parser.parse(ARGV)

Oddly, this isn’t the first options parsing library I’ve written. I wrote one for Crystal that allowed you to create “sentence-like human interfaces to your apps”. It had a similarly creative name: sentence_options

Alas, everything pales in comparison to what Raku comes with in its standard library. 😿

Why

Because - IMNSHO - Ruby’s optparse is a clusterfuck of confusing code, bad docs, and limited functionality. And I was writing a script that took two arguments and processed commit messages created with git-com and converted them into a rough changelog for the next release of git-com. 😜

oho (bonus)

Not technically “new” but somewhere along the way oho (the world’s greatest tool for converting escape codes to HTML) developed bit rot. Two key regular expressions that definitely used to work, started either matching too much, or too little and completely hosing the output as a result.

I’ve updated it, and found - and fixed - a couple edge cases it wasn’t handling well.

Why?

oho was created because - as a release manager - I found myself maintaining a growing arsenal of CLI tools that could spelunk through our git logs and generate useful information for stakeholders.

Just copy-pasting from the terminal - and loosing all the colors - lost a lot of important context and made it hard for stakeholders to focus on what they needed to. I needed a way to capture the colors and formatted output my tools were producing.

Oho lets me go from colorful terminal output to HTML which can then be converted to PDF. People are weird about being given raw HTML files, but PDF is something they’re comfortable with.

Credit Where It’s Due

Cleandiff wouldn’t have been possible without my amazing wife bringing Fenestro back to life by porting it to Go, and without her creation of the tokendiff diffing algorithm (geeky details here) the results wouldn’t be nearly as nice.

Fenestro is a fancy web-view you can throw lots of HTML files at really quickly, and then switch between them by clicking on its sidebar. It used to be in Swift, but then it stopped compiling as the language moved forwards. Now it’s written in Go and leverages the Wails GUI framework.

To make Cleandiff I simply took her work with Fenestro, and Tokendiff, and combined it with everything I’d learned making, and refining the proof of concept for Cleandiff, and slapped it all together into one app.