modd

Modd looks for a modd.conf file in the current directory on startup. The configuration consists of one or more blocks, each containing file match patterns and associated commands.

Command Types

• prep: Commands that run and terminate (e.g., compilers, test suites, linters). They run in order. If any prep command fails, the block execution stops immediately. If all succeed, any daemons in the block are restarted.
• daemon: Commands that run continuously (e.g., databases, webservers). Modd restarts them if they exit. When a block is triggered, modd sends a signal (defaulting to SIGHUP) to the daemon process group.

Block Syntax

pattern { 
    prep: command
    daemon: command
}

Variables are declared in the global scope (outside of blocks) using the syntax @variable = value. All values are treated as strings and follow command semantics (supporting escaped line endings or quoted strings). Variables are read once at startup; attempting to re-declare an existing variable will result in an error. You can reference variables in commands using the @ prefix.

@dst = ./build/dst
** {
    prep: ls @dst
}

To use modd, create a modd.conf file in your project root. A basic configuration to run Go tests whenever a .go file changes looks like this:

**/*.go {
    prep: go test @dirmods
}

Run modd by executing the command in your terminal:

$ modd

On the first run, modd executes the commands for all matching files. Subsequently, it only triggers the block when a file matching the pattern is modified.

Modd does not implicitly traverse symlinks. To monitor a symlink, you must split the path specification and the matching pattern:

mydir/symlinkdir foo.* {
    prep: echo changed
}

Modd displays a header in the terminal to identify which command is responsible for the output. This header is derived from the first non-whitespace line of the command. You can customize this display name by using shell comments at the beginning of your command block. Backslash escapes are removed from the end of the line, and comment characters are removed from the beginning.

{
    # This will show as "prep: mycommand"
    prep: "
        mycommand \
            --longoption 1 \
            --longoption 2
    "
    # This will show as "prep: daemon 1"
    prep: "
        # daemon 1
        mycommand \
            --longoption 1 \
            --longoption 2
    "
}

Modd is a single binary with no external dependencies. You can install it by downloading the appropriate package for your OS from the releases page and adding it to your PATH.

Alternatively, you can install it using go install. Note that CGO is required; if CGO is disabled in your environment, prepend CGO_ENABLED=1.

$ go install github.com/cortesi/modd/cmd/modd@latest

The indir option can be used within a block to control the execution directory. Modd will change to this directory before executing commands and daemons, and change back to the previous directory once the block finishes. The directory specification follows standard command conventions and can be enclosed in quotes to span multiple lines.

{
    indir: ./my/directory
    prep: ls
}

Modd ignores common nuisance files (like .git/) by default.

• To see the current ignore list, use the -i flag when running modd.
• To disable the default ignore list and match everything, use the +noignore flag within a block.

.git/config +noignore {
    prep: echo "git config changed"
}

The special @shell variable determines which shell is used to execute commands. Valid values are:

• modd (default)
• bash
• sh
• powershell

Note: It is recommended to avoid setting @shell to maintain cross-platform portability via the built-in modd shell.

@shell = bash

If command output lacks color, it is likely because the program detects it is not running in a terminal and disables color codes. To fix this, you have two options:

1. Use the specific tool's flag to force color output (e.g., --color=always).
2. Use a pseudo-terminal emulation tool like unbuffer (on Linux) to interpose between modd and the subprocess.

Prep Commands

Prep commands are executed in order. You can use the +onchange option to skip the initial run at startup and only execute when a change is detected.

*.go {
    # only trigger on file changes
    prep +onchange: go test
}

Daemon Commands

Daemons are started at startup and restarted if they exit. You can specify which signal to send to the daemon using the +sig<signal> flag. Supported signals include: sighup, sigterm, sigint, sigkill, sigquit, sigusr1, sigusr2, sigwinch.

daemon +sigterm: mydaemon --config ./foo.conf

Note: On Windows, signal types are ignored; all daemons are stopped and restarted instead of being signalled.

Modd provides several shell-escaped variables for use within prep commands: