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
- Grep topics for pattern and choose from matches
- Use positional and named variables when executing tasks
Getting Started
Prerequisites
- Ruby 2.4+ (It probably works on older Rubys, but is untested prior to 2.4.1.)
- Optional: if
fzf
is available, it will be used for handling multiple choice selections - Optional: if
bat
is available it will page with that - Optional:
mdless
ormdcat
for formatting output
Installing
You can install howzit
by running:
gem install howzit
If you run into permission errors using the above command, you’ll need to use gem install --user-install howzit
. If that fails, either use sudo
(sudo gem install howzit
) or if you’re using Homebrew, you have the option to install via brew-gem:
brew install brew-gem
brew gem install howzit
Usage
See the wiki for documentation.
Author
Brett Terpstra - brettterpstra.com
License
This project is licensed under the MIT License - see the LICENSE.txt file for details.
Download
Download the howzit script on GitHub.
Changelog
Click to expand
2.1.10
2024-04-09 14:59
NEW
- –no option (opposite of –yes) to answer no to all yes/no prompts
2.1.9
2023-09-07 11:02
NEW
- Add –templates-c to get a completion-compatible list of available templates
2.1.8
2023-05-31 11:58
FIXED
- Colors.rb error when code is integer
2.1.7
2023-05-29 12:59
FIXED
- Handle variable replacements on lines containing colons outside of variable
2.1.6
2023-05-29 12:42
FIXED
- Remove empty undefined variables with no default
2.1.5
2023-04-12 15:13
FIXED
- Allow tilde in path to editor
2.1.4
2023-03-07 12:52
NEW
- A theme file is automatically created where you can change the default output of any color that Howzit outputs. They can be 2-3 digit ANSI escape codes, or ‘#XXXXXX’ RGB hex codes
2.1.3
2023-03-07 11:21
FIXED
- Annoying warning about color template format string having too many arguments
2.1.2
2023-03-07 10:24
IMPROVED
- Merge metadata into named variables so they’re also available as ${NAME}
2.1.1
2023-03-07 09:47
FIXED
- Allow variables names to contain numbers and underscores
2.1.0
2023-03-07 09:24
NEW
- Use TOPIC_TITLE (var1, var2) to have access to ${var1} ${var2} in text and scripts, populated with positional variables on the command line
- Add a default (fallback) value to any variable placeholder with ${var_name:default value}
2.0.34
2023-01-15 13:32
FIXED
- Fail to partial match include commands after running fzf
2.0.33
2023-01-15 13:26
2.0.32
2023-01-15 10:46
IMPROVED
- When using fzf chooser, make matching exact to avoid running multiple topics
2.0.31
2022-08-31 07:17
FIXED
- Color template formatting of task output
2.0.30
2022-08-31 07:15
FIXED
- Formatting of –help and –version commands
2.0.29
2022-08-30 04:20
NEW
- –yes flag will answer yes to all prompts when executing
- –force flag will continue executing directives after an error
IMPROVED
- A non-zero exit status on a run directive will stop processing additional directives
- A little extra output formatting, more descriptive results logging
2.0.28
2022-08-29 18:42
IMPROVED
- If a topic runs multiple directives, stop processing them if one returns a non-zero exit status
2.0.27
2022-08-23 12:25
IMPROVED
- Code cleanup
2.0.26
2022-08-23 11:36
IMPROVED
- Add ctrl-a/d bindings to fzf menu for select/deselect all
2.0.25
2022-08-09 12:46
FIXED
- Template metadata inheritence
2.0.24
2022-08-09 09:04
FIXED
- Avoid reading upstream files multiple times
2.0.23
2022-08-09 05:51
FIXED
- –grep function regression
2.0.22
2022-08-08 13:49
IMPROVED
- Paginate output of –templates
FIXED
- –templates attempting to create new build note
- Fix handling of paths when the same as note_file
2.0.21
2022-08-08 13:16
IMPROVED
- Use os-agnostic copy function for –hook
- Rename link title for –hook
2.0.20
2022-08-08 11:38
NEW
- –hook command for macOS to copy a link to the build note to clipboard
FIXED
- Error on –edit-config
- Fzf preview empty
2.0.19
2022-08-08 06:18
IMPROVED
- Sort options in help output
2.0.18
2022-08-08 03:48
NEW
- Use –ask to require confirmation of all tasks when running a topic
2.0.17
2022-08-07 06:09
2.0.16
2022-08-07 06:05
NEW
- –edit-template NAME will open a template in your editor, offering to create it if missing
FIXED
- If –show-code is given (or :show_all_code: is set to true), show content of @directives instead of title
2.0.15
2022-08-05 17:16
IMPROVED
- -R can take an argument to filter results
- Show a topic preview when using fzf to select from available topics
- Paginate help output
- Refactor Topic.run
FIXED
- Invalid options for more pager
- Error running grep command
- Show method not accepting paginate option
2.0.14
2022-08-05 13:24
FIXED
- Travis CI fixes
2.0.13
2022-08-05 13:19
IMPROVED
- Add tests for more ruby versions via Docker
2.0.12
2022-08-05 11:27
IMPROVED
- Show how many tasks will be included when requesting confirmation for an include? directive
2.0.11
2022-08-05 11:21
IMPROVED
- Update fish completions with all current command line options
2.0.10
2022-08-05 08:17
IMPROVED
- Provide more helpful feedback if no content is found in build note
- Confirm whether the user wants to create a new note when one isn’t found
2.0.9
2022-08-05 07:29
IMPROVED
- Avoid error trace on interrupt
- Better stty settings for y/n prompt
- Better coloring of default options in dialogs
FIXED
- Encoding issues with older ruby versions
- Globbing for build notes was picking up files that contained “build” but not at the beginning of the filename
2.0.8
2022-08-04 13:28
FIXED
- Bugfixes
2.0.7
2022-08-04 13:04
NEW
- –debug flag (shortcut for :log_level: 0)
IMPROVED
- Console output now gets log levels, so :log_level: config option and –quiet/verbose have more utility
2.0.6
2022-08-04 11:08
2.0.5
2022-08-04 10:50
NEW
- Make any task optional when running by adding a ? (@open?(…))
- Optional tasks default to yes when you hit enter, invert by using a ! (@open?!(…)) to make default “no”
FIXED
- Replace escaped newlines in task list output so that they don’t trigger a newline in the shell
2.0.4
2022-08-04 06:25
IMPROVED
- Ask to open new buildnote for editing after creation
FIXED
- Loop when creating new buildnote
2.0.3
2022-08-04 05:31
IMPROVED
- General code cleanup
- Attempt at os agnostic @copy command, hopefully works on Windows and Linux systems
FIXED
- Not displaying action if title is missing
2.0.2
2022-08-03 18:26
IMPROVED
- If a title is provided after an @command, display it instead of the contents when viewing
2.0.1
2022-08-03 12:46
FIXED
- Failure to create new notes file when one isn’t found
2.0.0
2022-08-03 12:37
FIXED
- Positional arguments not rendering in tasks
- Fix degradation where arguments are empty
1.2.19
2022-08-03 12:18
FIXED
- –config-get returning non-default options
1.2.18
2022-08-03 12:13
FIXED
- Unwritable content property
1.2.17
2022-08-03 12:10
FIXED
- Variables in topics not being replaced with metadata
- Allow default response in yes/no prompt
1.2.16
2022-08-03 11:41
IMPROVED
- Complete code refactoring
FIXED
- Multiple includes of upstream files when templates are specified
1.2.15
2022-08-02 11:59
NEW
- Option to set :header_format: to block for alternate topic title appearance
FIXED
- Missing spacing around topic titles when displaying multiple topics
1.2.14
2022-08-02 11:01
NEW
- Config option and flag to determine how to handle multiple results (first, best, all, choose)
- –config-get and –config-set flags for working with config options
IMPROVED
- Allow multiple selections when using fzf
- Clean up newlines in output
1.2.13
2022-08-01 20:50
1.2.12
2022-08-01 16:23
IMPROVED
- Replace ANSI escape codes with color template system
- When @including an external file, if the file doesn’t contain any level 2+ headers, import it as plain text.
1.2.11
2022-08-01 08:23
IMPROVED
- Code cleanup and refactoring
1.2.10
2022-08-01 07:45
FIXED
- Headline formatting when iTerm markers are inserted
1.2.8
2022-08-01 07:01
FIXED
- Frozen string error
1.2.6
2022-08-01 06:09
NEW
- Use @before…@end and @after…@end to specify prerequisites and a post-run message. Topics with @before will require y/n verification before running
FIXED
- ITerm markers weren’t being inserted when paging was off
1.2.3
2022-07-31 14:20
IMPROVED
- Don’t include a topic multiple times in one display
- Don’t execute nested topics more than once
- Indicate nested includes in headers
- Code cleanup
1.2.2
2022-07-31 08:56
- Add -F option to pager setup (quit if less than one screen)
1.2.1
2022-07-31 05:12
- Add handling for delta pager to not clear screen on exit
1.2.0
2022-07-31 04:59
- Add grep feature, searches topic/content for pattern and displays matches (selection menu if multiple matches)
1.1.27
2022-01-17 11:45
NEW
- Use fzf for menus if available
- “@run() TITLE” will show TITLE instead of command when listing runnable topics
- @include(FILENAME) will import an external file if the path exists
1.1.26
- Fix for error in interactive build notes creation
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
andoptional
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 ofexec
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)
Speaking of howzit…
- Automating the Dimspirations workflow
- Howzit with named variables
- Brett's Favorites 2022 - Personal Projects
- Getting started with Howzit
- howzit got gemified
- Project Updates July 2022
- Just your average project update and wellness check-in
- Howzit gets templates
- Let's get crazy with BetterTouchTool and Touch Bar Simulator
- Some updates for howzit, Markdown notes for your projects
- Brett's Favorites 2020
- Using howzit as a task runner
- Howzit: Remember how what you work on works