Howzit

Gem GitHub license

A command-line reference tool for tracking project build systems

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 or mdcat 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.

Warranty

This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.

Documentation

Development and Testing

Source Code

The howzit source is hosted on GitHub. Clone the project with

$ git clone https://github.com/ttscoff/howzit.git

Requirements

You will need Ruby with Bundler.

Install the development dependencies with

$ bundle

Rake

Run $ rake -T to see all Rake tasks.

rake build                 # Build howzit-2.0.1.gem into the pkg directory
rake bump:current[tag]     # Show current gem version
rake bump:major[tag]       # Bump major part of gem version
rake bump:minor[tag]       # Bump minor part of gem version
rake bump:patch[tag]       # Bump patch part of gem version
rake bump:pre[tag]         # Bump pre part of gem version
rake bump:set              # Sets the version number using the VERSION environment variable
rake clean                 # Remove any temporary products
rake clobber               # Remove any generated files
rake install               # Build and install howzit-2.0.1.gem into system gems
rake install:local         # Build and install howzit-2.0.1.gem into system gems without network access
rake release[remote]       # Create tag v2.0.1 and build and push howzit-2.0.1.gem to Rubygems
rake rubocop               # Run RuboCop
rake rubocop:auto_correct  # Auto-correct RuboCop offenses
rake spec                  # Run RSpec code examples
rake test                  # Run test suite
rake yard                  # Generate YARD Documentation

Guard

Guard tasks have been separated into the following groups: doc, lint, and unit. By default, $ guard will generate documentation, lint, and run unit tests.

Contributing

Please submit and comment on bug reports and feature requests.

To submit a patch:

  1. Fork it (https://github.com/ttscoff/howzit/fork).
  2. Create your feature branch (git checkout -b my-new-feature).
  3. Make changes. Write and run tests.
  4. Commit your changes (git commit -am 'Add some feature').
  5. Push to the branch (git push origin my-new-feature).
  6. Create a new Pull Request.