I had a bit of a manic coding week this last week. Which probably means I’m headed for some depression soon, so I wanted to write about at least one of the things I’ve worked on recently before I lose motivation. So let’s start with Howzit, my little CLI for tracking all of the build settings and other notes for your coding projects.

I added the ability to run tasks from within a notes file a while back, and I use it a lot. I quickly found that there were some tasks that were common to most projects of the same type, be it ruby gems, Xcode projects, or just Markdown repositories. Projects within a type tend to use some common commands and scripts with only the target paths or build flags changing (if anything does). So to make it easy to replicate tasks between build files, I added “templates” to Howzit.

I wrote it up for the docs, so I’ll just give you a quick description and then point you there.

All you do is create a Markdown file in ~/.config/howzit/templates/ and, just like a Howzit file, add level 2 or higher headers for each topic/task followed by the notes and directives. You can use MultiMarkdown-style placeholders for variables, e.g. [%variable] inside the notes. The name of the file is the key with which you’ll reference it in your build notes.

Then, in buildnotes.md in some Markdown-based project, you would just add MMD-style metadata:

template: markdown
spelling_dirs: . docs

# My Markdown Project
[...]

spelling_dirs becomes a variable I can reference in my template, which in this case includes a Spellcheck task, and spelling_dirs tells it which directories to find Markdown files in. Variables can even have default values after a colon, e.g. [%spelling_dirs:.].

A file can reference multiple templates, and you can include only specific tasks with wildcard support in the format:

template: markdown[spellcheck,markdown lint], ruby[build*]

If you get into the template thing and have a bunch, it’ll be easy to forget what titles you gave them all and what tasks they contain, so I added a --templates flag that will show you all of your installed templates and what topics will be added when you include them. Just run howzit --templates to get the list.

Be sure to update to the latest version of the script to get all the new goodies. Someday I’ll probably package it as a gem and make updating easy, but for now you need to re-download the script and overwrite your current version.

Or you can do what I do and clone the repository from GitHub, then symlink the howzit file into a directory in your path. Then you can just do a git pull when you want to get the latest version… {.tip}

Anyway, that was my Sunday morning project. If you’ve found howzit useful before, I hope this adds some extra usability for you.

Oh yeah, and a week or two ago I also added “upstream searches,” which checks for build notes in parent directories and compiles any topics found into the notes for the current folder. It travels up to root (/), so you can have a universal build note in an ancestor directory and all topics in it will be included in descendant notes. It was the predecessor to templates (which are definitely a superior solution). Upstream searches have to be enabled in ~/.config/howzit/howzit.yaml with :include_upstream: true.

Also, if you run howzit in a subdirectory of a git repo and it doesn’t find a build notes file in the current directory, it now checks the top level of the repo for build notes and executes tasks from there. Fun stuff.

All the details on the Howzit project page.