@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. The environment variable $HOWZIT_SCRIPTS is set to ~/.config/howzit/scripts, so if you store scripts needed by your build notes in that directory, you can call them with $HOWZIT_SCRIPTS/myscript.sh

• @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.

• @before...@end

  A block defined between @before and @end markers will be considered prerequisite for any task the topic can run. If one or more of these blocks exist in the topic, they will be displayed before running and a yes/no dialog will request confirmation that the prerequisites have been met. The content between these markers is still included when viewing the topic, but the tags themselves do not show up in output.

  This is generally used for a checklist of tasks that must be handled manually. Any @directives inside this box will be displayed raw, and the will be executed in line with everything else, not waiting for confirmation (tasks are processed in order).

• @after...@end

  A block defined between @after and @end markers will be displayed after a topic is run. Use it to remind yourself of additional tasks after automated ones have been executed. The content between these markers is still included when viewing the topic, but the tags themselves do not show up in output.

  This is generally used for a checklist of tasks that must be handled manually after the automation runs. Any @directives inside this box will be displayed raw, and the will be executed in line with everything else.

Adding Titles

When displaying a topic, howzit can display a title instead of the contents of a directive. Any text after the closing parenthesis will be considered the task title.

@run(~/scripts/deploy.sh) Deploy script

When the topic is displayed, it will now show "Run Deploy script" instead of the path to the script. This can be overridden with the --show-code flag, which will instead show the contents of the directive.

For adding titles to run blocks (fenced code), see below.

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.

The environment variable $HOWZIT_SCRIPTS is set to ~/.config/howzit/scripts, so if you store scripts needed by your build notes in that directory, you can call them with $HOWZIT_SCRIPTS/myscript.sh or however the block's hashbang processor references environment variables.

Requiring Confirmation

You can have howzit confirm whether to execute an @command at runtime by including a question mark to the directive, e.g. @run?(...). This will present a yes/no dialog before running the directive, with a default response of "yes" if you just hit return. To make the default response "no," add an exclamation point, e.g. @run?!(...).

This works for any directive, including @include, and run blocks, which can use run? as the language specifier:

```run? Description of block
# Tasks to execute
```

See Variables for info on making your tasks dynamic.

See Templates and metadata for info on re-using tasks between projects.