howzit
Keeping track of your build systems so you don’t have to
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
ormdcat
for formatting output
Installing
Download the script as howzit
to a folder in your $PATH and make it executable with:
chmod a+x howzit
Usage
Howzit works on note files you keep per project.
Setup
Howzit relies on there being a file in the current directory with a name that starts with “build” and an extension of .md
, .txt
, or .markdown
, e.g. buildnotes.md
. This note contains sections such as “Build” and “Deploy” with brief notes about each topic in Markdown (or just plain text).
The sections of the notes are delineated by Markdown headings, level 2 or higher, with the heading being the title of the section. 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]
@run(gulp)
## Stage
gulp sync: rsync /dist/ to scoffb.local
## Package management
yarn
## Components
UIKit
@open(https://getuikit.com/docs/introduction)
Howzit expects there to only be one header level used to split sections. Anything before the first header is ignored.
@Commands
You can include commands that can be executed by howzit. Commands start at the beginning of a line anywhere in a section. Only one section’s commands can be run at once, but all commands in the section 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 usesstart
, and on Linux it usesxdg-open
, which may require separate installation.
Using howzit
Run howzit
on its own to view the current folder’s buildnotes.
Include a section name to see just that section, or no argument to display all.
howzit build
Use -l
to list the section titles.
howzit -l
Use -r
to execute any @copy, @run, or @open commands in the given section. Options can come after the section argument, so to run the commands from the last section you viewed, just hit the up arrow to load the previous command and add -r
.
howzit build -r
Other options:
Usage: howzit [OPTIONS] [SECTION]
Show build notes for the current project (buildnotes.md). Include a section name to see just that section, or no argument to display all.
Options:
-c, --create Create a skeleton build note in the current working directory
-R, --list-runnable List sections containing @ directives (verbose)
-t, --title Output title with build notes
--title-only Output title only
-T, --task-list List sections containing @ directives (completion-compatible)
-L, --list-completions List sections for completion
-l, --list List available sections
-r, --run Execute @run, @open, and/or @copy commands for given section
--[no-]color Colorize output (default on)
--[no-]md-highlight Highlight Markdown syntax (default on), requires mdless or mdcat
--[no-]pager Paginate output (default on)
-w, --wrap COLUMNS Wrap to specified width (default 80, 0 to disable)
-h, --help Display this screen
-v, --version Display version number
Additional Features
- Match section titles with any portion of title
- Automatic pagination of output with Markdown highlighting
- Wrap output with option (
-w COLUMNS
) to specify width (default 80, 0 to disable) - Use
@run()
,@copy()
, and@open()
to perform actions within a build notes file - Set iTerm 2 marks on section titles for navigation when paging is disabled
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 sections, and howzit -T
to list all “runnable” sections (sections containing an @directive). Completion examples for Fish are included in the fish
directory.
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.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 “Section 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” sections
- Add -T switch for completion-compatible listing of “runnable” sections
- Add -L switch for completion-compatible listing of all sections
- 1.0.1
- Allow section matching within title, not just at start
- Remove formatting of section 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)
Speaking of howzit…