Happy New Year! I spent some time this morning developing some features for Howzit that I think will be really useful (at least for me).

Howzit is my tool for documenting my project structure/build/deploy/CI methods and instructions, with the ability to execute code from the Markdown documentation. I use it in every project I create, and it makes it really easy to come back to a project where I’ve forgotten exactly how it works. For example, every project has a “Deploy” topic where I detail the steps for deploying/publishing. In any project, I can type howzit deploy and get the instructions, and howzit -r deploy will just execute my automated deploy scripts.

I added a couple of advanced features this morning.

Script-to-Howzit Communication

Scripts can now communicate back to Howzit while they’re running. This lets scripts send log messages and set variables that can be used in subsequent tasks or conditional blocks.

The communication happens through a temporary file. Howzit sets the HOWZIT_COMM_FILE environment variable to point to this file, and your scripts can write to it using a simple format:

LOG:info:This is an info message
LOG:warn:This is a warning
LOG:error:Something went wrong
VAR:MY_VAR=some_value

For example, in a bash script:

#!/bin/bash
if [ -n "$HOWZIT_COMM_FILE" ]; then
  echo "LOG:info:Starting deployment process" >> "$HOWZIT_COMM_FILE"
  echo "VAR:DEPLOY_STATUS=in_progress" >> "$HOWZIT_COMM_FILE"
fi

# ... do your deployment ...

if [ -n "$HOWZIT_COMM_FILE" ]; then
  echo "LOG:info:Deployment complete" >> "$HOWZIT_COMM_FILE"
  echo "VAR:DEPLOY_STATUS=complete" >> "$HOWZIT_COMM_FILE"
fi

Variables set by scripts are merged into Howzit’s named arguments, so they’re available for variable substitution (${VAR}) in subsequent tasks and can be used in conditional blocks. Log messages are displayed through Howzit’s console logger at the appropriate log level.

This is particularly useful for scripts that need to communicate their status or set flags that affect later tasks. See the Script-to-Howzit Communication wiki page for complete details and examples.

Conditional Blocks

Howzit now supports conditional blocks, so you can include or exclude content and tasks based on conditions. Use @if and @unless directives to control what appears in your build notes.

Basic Conditional Blocks

The syntax is straightforward:

@if environment == "production"
@run(./deploy-prod.sh) Deploy to Production
@end

@unless $SKIP_TESTS == "1"
@run(./test.sh) Run Tests
@end

You can also use @elsif and @else for multiple branches:

@if env == "production"
Production setup
@elsif env == "staging"
Staging setup
@else
Development setup
@end

String Comparison Operators

Conditions support various string comparison operators. The newest addition is the fuzzy match operator **=, which matches if the search string’s characters appear in order within the target string. For example, "fluffy" **= "ffy" matches because the characters f, f, and y appear in order.

Other operators include == for exact equality, *= for contains, ^= for starts with, $= for ends with, and =~ for regex matching. See the Conditional Blocks wiki page for details on all comparison operators.

File Contents Conditions

You can now check file contents directly in conditions:

@if file contents VERSION.txt ^= 0.
Version starts with 0.
@end

@if file contents CHANGELOG.md *= "Breaking"
Changelog contains breaking changes
@end

The file path can be a literal path or a variable from metadata, named arguments, or environment variables. This makes it easy to check version files, configuration files, or any other file content as part of your conditional logic.

Special Conditions

Howzit also supports special conditions like git dirty, git clean, file exists, dir exists, and topic exists. You can even check the current working directory with cwd using string comparison operators.

Check out the Howzit project page for general details. For complete documentation on all condition types, operators, and examples, check out the Conditional Blocks wiki page.

Please enjoy, and may Howzit make your 2026 project development smooth!