howzit

Keeping track of your build systems so you don’t have to

Howzit is a tool that allows you to keep Markdown-formatted notes about a project’s tools and procedures. It functions as an easy lookup for notes about a particular task, as well as a task runner to automatically execute appropriate commands.

Features

  • Match topic titles with any portion of title
  • Automatic pagination of output, with optional Markdown highlighting
  • Use @run(), @copy(), and @open() to perform actions within a build notes file
  • Use @include() to import another topic’s tasks
  • Use fenced code blocks to include/run embedded scripts
  • Sets iTerm 2 marks on topic titles for navigation when paging is disabled
  • Inside of git repositories, howzit will work from subdirectories, assuming build notes are in top level of repo
  • Templates for easily including repeat tasks

Getting Started

Howzit is a simple, self-contained script (at least until I get stupid and make a gem out of it).

Prerequisites

  • Ruby 2.4+ (It probably works on older Rubys, but is untested prior to 2.4.1.)
  • Optional: if bat is available it will page with that
  • Optional: mdless or mdcat for formatting output

Installing

One-Line Install

You can install howzit by running:

curl -SsL 'https://raw.githubusercontent.com/ttscoff/howzit/main/install.sh'|bash

Manual Install

Clone the repo or just download the self-contained script. Save the script as howzit to a folder in your $PATH and make it executable with:

chmod a+x howzit

Anatomy of a Build Notes File

Howzit relies on there being a file in the current directory with a name that starts with “build” or “howzit” and an extension of .md, .txt, or .markdown, e.g. buildnotes.md or howzit.txt. This note contains topics such as “Build” and “Deploy” with brief notes about each topic in Markdown (or just plain text) format.

Tip: Add “buildprivate.md” to your global gitignore (git config --get core.excludesfile). In a project where you don’t want to share your build notes, just name the file “buildprivate.md” instead of “buildnotes.md” and it will automatically be ignored.

If there are files that match the “build*” pattern that should not be recognized as build notes by howzit, add them to ~/.config/howzit/ignore.yaml. This file is a simple list of patterns that should be ignored when scanning for build note files. Use (?:i) at the beginning of a pattern to make it case insensitive.

The topics of the notes are delineated by Markdown headings, level 2 or higher, with the heading being the title of the topic. I split all of mine apart with h2s. For example, a short one from the little website I was working on yesterday:

## Build

gulp js: compiles and minifies all js to dist/js/main.min.js

gulp css: compass compile to dist/css/

gulp watch

gulp (default): [css,js]

## Deploy

gulp sync: rsync /dist/ to scoffb.local

## Package management

yarn

## Components

- UIKit

Howzit expects there to only be one header level used to split topics. Anything before the first header is ignored. If your topics use h2 (##), you can use a single h1 (#) line at the top to title the project.

@Commands

You can include commands that can be executed by howzit. Commands start at the beginning of a line anywhere in a topic. Only one topic’s commands can be run at once, but all commands in the topic will be executed when howzit is run with -r. Commands can include any of:

  • @run(COMMAND)

    The command in parenthesis will be executed as is from the current directory of the shell

  • @copy(TEXT)

    On macOS this will copy the text within the parenthesis to the clipboard. An easy way to offer a shortcut to a longer build command while still allowing it to be edited prior to execution.

  • @open(FILE|URL)

    Will open the file or URL using the default application for the filetype. On macOS this uses the open command, on Windows it uses start, and on Linux it uses xdg-open, which may require separate installation.

  • @include(TOPIC)

    Includes all tasks from another topic, matching the name (partial match allowed) and returning first match.

Run blocks (embedded scripts)

For longer scripts you can write shell scripts and then call them with @run(myscript.sh). For those in-between cases where you need a few commands but aren’t motivated to create a separate file, you can use fenced code blocks with run as the language.

```run OPTIONAL TITLE
#!/bin/bash
# Commands...
```

The contents of the block will be written to a temporary file and executed with /bin/sh -c. This means that you need a hashbang at the beginning to tell the shell how to interpret the script. If no hashbang is given, the script will be executed as a sh script.

Example:

```run Just Testing
#!/bin/bash
echo "Just needed a few lines"
echo "To get through all these commands"
echo "Almost there!"
say "Phew, we did it."
```

Multiple blocks can be included in a topic. @commands take priority over code blocks and will be run first if they exist in the same topic.

Variables

When running commands in a topic, you can use a double dash (--) in the command line (surrounded by spaces) and anything after it will be interpreted as shell arguments. These can be used in commands with $ placeholders. $1 represents the first argument, counting up from there. Use $@ to pass all arguments as a shell-escaped string.

For example, the topic titled “Test” could contain an @run command with placeholders:

## Test
@run(./myscript.sh $@)

Then you would run it on the command line using:

howzit -r test -- -x "arg 1" arg2

This would execute the command as ./myscript.sh -x arg\ 1 arg2.

Placeholders can be used in both commands and run blocks. If a placeholder doesn’t have an argument supplied, it’s not replaced (e.g. leaves $2 in the command).

Templates and metadata

You can create templates to reuse topics in multiple build note files. Create files using the same formatting as a build note in ~/.config/howzit/templates with .md extensions. Name them the way you’ll reference them:

~/.config/howzit/templates
- markdown.md
- ruby.md
- obj-c.md

Use howzit --templates for a list of templates you’ve created, along with the topics they’ll add when included. Just in case you make a bunch and can’t remember what they’re called or what they do. I was just planning ahead.

You can then include the topics from a template in any build note file using a template: key at the top of the file.

Howzit allows MultiMarkdown-style metadata at the top of a build notes file. These are key/value pairs separated by a colon:

template: markdown
key 1: value 1
key 2: value 2

The template key can include multiple template names separated by commas.

Additional metadata keys populate variables you can then use inside of your templates (and build notes), using [%key]. You can define a default value for a placeholder with [%key:default].

For example, in the template markdown.md you could have:

### Spellcheck

Check spelling of all Markdown files in git repo.

```run
#!/bin/bash
for dir in [%dirs:.]; do
    cd "$dir"
    /Users/ttscoff/scripts/spellcheck.bash
    cd -
done
```

Then, in a buildnotes.md file in your project, you could include at the top of the file:

template: markdown
dirs: . docs

# My Project...

If you only want to include certain topics from a template file, use the format template_name[topic] or include multiple topics separated by commas: template_name[topic 1, topic 2]. You can also use * as a wildcard, where template_name[build*] would include topics “Build” and “Build and Run”.

If a topic in the current project’s build note has an identical name to a template topic, the local topic takes precedence. This allows you to include a template but modify just a part of it by duplicating the topic title.

Templates can include other templates with a template: key at the top of the template.

You can define what metadata keys are required for the template using a required: key at the top of the template. For example, if the template script.md uses a placeholder [%executable] that can’t have a default value as it’s specific to each project, you can add:

required: executable

at the top of project.md. If the template is included in a build notes file and the executable: key is not defined, an error will be shown.

Using howzit

Run howzit on its own to view the current folder’s buildnotes.

Include a topic name to see just that topic, or no argument to display all.

howzit build

Use -l to list all topics.

howzit -l

Use -r to execute any @copy, @run, or @open commands in the given topic. Options can come after the topic argument, so to run the commands from the last topic you viewed, just hit the up arrow to load the previous command and add -r.

howzit build -r

Other options:

Usage: howzit [OPTIONS] [TOPIC]

Options:
    -c, --create                     Create a skeleton build note in the current working directory
    -e, --edit                       Edit buildnotes file in current working directory using editor.sh
    -L, --list-completions           List topics for completion
    -l, --list                       List available topics
    -m, --matching TYPE              Topics matching type
                                     (partial, exact, fuzzy, beginswith)
    -R, --list-runnable              List topics containing @ directives (verbose)
    -r, --run                        Execute @run, @open, and/or @copy commands for given topic
    -s, --select                     Select topic from menu
    -T, --task-list                  List topics containing @ directives (completion-compatible)
    -t, --title                      Output title with build notes
    -q, --quiet                      Silence info message
        --verbose                    Show all messages
    -u, --upstream                   Traverse up parent directories for additional build notes
    -w, --wrap COLUMNS               Wrap to specified width (default 80, 0 to disable)
        --edit-config                Edit configuration file using editor.sh
        --title-only                 Output title only
        --templates                  List available templates
        --[no-]color                 Colorize output (default on)
        --[no-]md-highlight          Highlight Markdown syntax (default on), requires mdless or mdcat
        --[no-]pager                 Paginate output (default on)
    -h, --help                       Display this screen
    -v, --version                    Display version number

Configuration

Some of the command line options can be set as defaults. The first time you run howzit, a YAML file is written to ~/.config/howzit/howzit.yaml. You can open it in your default editor automatically by running howzit --edit-config. It contains the available options:

---
:color: true
:highlight: true
:paginate: true
:wrap: 80
:output_title: false
:highlighter: auto
:pager: auto
:matching: partial
:include_upstream: false
:log_level: 1

If :color: is false, output will not be colored, and markdown highlighting will be bypassed.

If :color: is true and :highlight: is true, the :highlighter: option will be used to add Markdown highlighting.

If :paginate: is true, the :pager: option will be used to determine the tool used for pagination. If it’s false and you’re using iTerm, “marks” will be added to topic titles allowing keyboard navigation.

:highlighter: and :pager: can be set to auto (default) or a command of your choice for markdown highlighting and pagination.

:matching: can be “partial”, “beginswith”, “fuzzy” or “exact” (see below).

If :include_upstream: is true, build note files in parent directories will be included in addition to the current directory. Priority goes from current directory to root in descending order, so the current directory is top priority, and a build notes file in / is the lowest. Higher priority topics will not be overwritten by a duplicate topic from a lower priority note.

Set :log_level: to 0 for debug messages, or 3 to suppress superfluous info messages.

Matching

All matching is case insensitive. This setting can be overridden by the --matching TYPE flag on the command line.

  • :matching: partial

    Partial is the default, search matches any part of the topic title.

    Example: howzit other matches ‘Another Topic’.

  • ‘:matching: beginswith`

    Matches from the start of the title.

    Example: howzit another matches ‘Another Topic’, but neither ‘other’ or ‘topic’ will.

  • :matching: fuzzy

    Matches anything containing the search characters in order, no matter what comes between them.

    Example: howzit asct matches ‘Another Section’

  • :matching: exact

    Case insensitive but must match the entire title.

    Example: Only howzit another topic will match ‘Another Topic’

Pager

If set to auto, howzit will look for pagers in this order, using the first one it finds available:

  • $GIT_PAGER
  • $PAGER
  • bat
  • less
  • more
  • cat
  • pager

If you’re defining your own, make sure to include any flags necessary to handle the output. If you’re using howzit’s coloring, for example, you need to specify any options needed to display ANSI escape sequences (e.g. less -r).

Highlighter

If set to auto howzit will look for markdown highlighters in this order, using the first it finds available:

  • mdcat
  • mdless

If you’re combining a highlighter with howzit’s pagination, include any flags needed to disable the highlighter’s pagination (e.g. mdless --no-pager).

Shell Integration

I personally like to alias bld to howzit -r. If you define a function in your shell, you can have it default to “build” but accept an alternate argument. There’s an example for Fish included, and in Bash it would be as simple as howzit -r ${1:build}.

For completion you can use howzit -L to list all topics, and howzit -T to list all “runnable” topics (topics containing an @directive or run block). Completion examples for Fish are included in the fish directory.

Similar Projects

There are a few projects that tackle the same concept (a Markdown makefile). Most of them are superior task runners, so if you’re looking for a make replacement, I recommend exploring the links above. What I like about howzit (and what keeps me from switching) is that it’s documentation-first, and that I can display the description for each topic on the command line. The others also don’t have options for listing topics or runnable tasks, so I can’t use completion (or my cool script that adds available tasks to my Macbook Pro Touch Bar…). But no, I don’t think howzit is as good an overall task runner as mask or maid.

Roadmap

  • Recognize header hierarchy, allow showing/running all sub-topics

Author

Brett Terpstra - brettterpstra.com

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Download

Download the howzit script on GitHub.

Changelog

1.1.25

  • Hide run block contents by default
  • :show_all_code: config setting to include run block contents
  • –show-code flag to display run block contents at runtime
  • Modify include display

1.1.24

  • Use ~/.config/howzit/ignore.yaml to ignore patterns when scanning for build notes
  • Use required and optional keys in templates to request that metadata be defined when importing
  • Allow templates to include other templates

1.1.23

  • Add flags to allow content to stay onscreen after exiting pager (less and bat)

1.1.21

  • Merge directive and block handling so execution order is sequential

1.1.20

  • Template functionality for including common tasks/topics

1.1.19

  • Add --upstream option to traverse up parent directories for additional build notes

1.1.15

  • Code refactoring/cleanup
  • Rename “sections” to “topics”
  • If no match found for topic search, only show error (:show_all_on_error: false option)

1.1.14

  • Fix removal of non-alphanumeric characters from titles
  • -s/–select option to display a menu of all available topics
  • Allow arguments to be passed after -- for variable substitution
  • Allow –matching TYPE to match first non-ambigous keyword match

1.1.13

  • –matching [fuzzy,beginswith,partial,exact] flag
  • –edit-config flag
  • sort flags in help

1.1.12

  • After consideration, remove full fuzzy matching. Too many positives for shorter strings.

1.1.11

  • Add full fuzzy matching for topic titles
  • Add @include(TOPIC) command to import another topic’s tasks

1.1.10

  • Add config file for default options

1.1.9

  • Use system instead of exec to allow multiple @run commands
  • Add code block runner

1.1.8

  • Add -e/--edit flag to open build notes in $EDITOR

1.1.7

  • Use exec for @run commands to allow interactive processes (e.g. vim)

1.1.6

  • Add option for outputting title with notes
  • Add option for outputting note title only

1.1.4

  • Fix for “topic not found” when run with no arguments

1.1.1

  • Reorganize and rename long output options
  • Fix wrapping long lines without spaces

1.1.0

  • Add -R switch for listing “runnable” topics
  • Add -T switch for completion-compatible listing of “runnable” topics
  • Add -L switch for completion-compatible listing of all topics

1.0.1

  • Allow topic matching within title, not just at start
  • Remove formatting of topic text for better compatibility with mdless/mdcat
  • Add @run() syntax to allow executable commands
  • Add @copy() syntax to copy text to clipboard
  • Add @url/@open() syntax to open urls/files, OS agnostic (hopefully)
  • Add support for mdless/mdcat
  • Add support for pager
  • Offer to create skeleton buildnotes if none found
  • Set iTerm 2 marks for navigation when paging is disabled

  • Wrap output with option to specify width (default 80, 0 to disable)

  • Support
  • GitHub
  • Download

Speaking of howzit…

Related Projects