Howzit: Remember how what you work on works

Back in April I posted a short script for keeping track of the various build systems I use in my projects. You know when you open a directory you haven’t worked on for a while and there’s a Gulp file, a Rakefile, a node_modules folder, and various other cruft that means you’ll have to dig through to recall what commands you were using to build and deploy the project? Or when you know there were specific flags you were using to get the build to work, but you never got around to automating them? It’s for those situations, and other general sanity.

Over the rest of this year I’ve slowly modified and expanded the script as I’ve wanted it to do things differently or better. I’ve been hesitant to post the results because it really feels like something nobody else is going to need and it’s entirely possible that I’ve put too much time into it already. I did stop myself before turning it into a fully packaged gem, so good on me.

It’s now called “howzit.” As in “how’z it do this?” or “how’z it do that?”. Build notes are still a simple Markdown (plain text, really) file with quick notes for each topic, as applicable to the project. Running howzit displays the whole file, paged (with bat, if available) and highlighted (with mdless, mdcat, or bat markdown mode, based on availability). You can run howzit -l to list all sections, and then howzit NAME to list a single section.

Within each section you can now include directives like @run(COMMAND) and @open(FILE|URL) at the beginning of a line, and when you run howzit SECTION -r it will run all directives within that section. Aside from general convenience, this means that I can include the primary build commands and all options as a @run directive in every project, and just run howzit build -r as a universal build command.

I’ve detailed the rest of the options and features on the new howzit project page, including links to the GitHub repo and associated “Issues” section, if you happen to find it useful and find bugs, or find it almost useful and have ideas to get it the rest of the way there.