godemon

godemon is both a CLI tool and Go library that detects changes to files and directories.

It has many uses:

• Restart a development server or tests
• Copy or upload changed contents automatically, via rsync
• Print the changes that are happening
• Sleep until some file exists or is changed
• Lots of other things!

It is inspired by nodemon which is a similar tool written in JavaScript.

Goals

• Strong defaults: godemon ships with a default ignore list and also treats .gitignore files as additional ignore patterns. Restarts are throttled to 50ms by default, so that rapid changes to a file don't unnecessarily restart the command multiple times (this is common with IDE format-on-save actions, for example).
• Configurability: All of the opinionated behaviors and settings can be customized.
• Efficiency: godemon is fast to start up and responds to file changes immediately. It uses efficient file watching APIs (inotify and fsevents) rather than polling for changes, so it doesn't use CPU resources when nothing is changing.
• Utility: you can use godemon's file-watching capabilities in various ways, beyond just running a command on every change. You can use it to stream the raw filesystem change events that it observes, to be consumed and processed by other programs, or to block a script until some filesystem-related condition becomes true (e.g. file exists). You can also use it as a Go library, to integrate file watching capabilities into your Go library.

Status

godemon has been tested on Mac and Linux. It has not yet been tested on Windows.

The command line interface and config file format are not yet stable.

Installation

The easiest way to install godemon is with the go CLI:

go install github.com/bduffany/godemon/cmd/godemon@latest

Basic usage

The godemon command can be used as follows:

godemon [options ...] <command> [args ...]

By default, the given command is executed whenever any file in the current directory changes.

Examples

To watch the current directory (recursively) and run a command on any change:

godemon command

To watch multiple directories, use --watch or -w. When using this flag, the current directory needs to be passed explicitly, otherwise it's assumed that you only want to watch /some/other/dir (in this example).

godemon --watch . --watch /some/other/dir command

To only restart on changes to certain paths or patterns, use --only or -o:

godemon --only '*.ts' --only '*.tsx' command

To ignore changes to certain paths or patterns, use --ignore or -i:

godemon --ignore '**/build/**' --ignore '**/dist/**' command

To suppress godemon's own log output while still allowing the watched command to write to stdout and stderr, use --quiet or -q:

godemon --quiet command

Default ignored patterns

The default ignored patterns are listed in default_ignore.go.

To disable the default ignore list, pass --no-default-ignore.

By default, godemon also ignores patterns that are listed in .gitignore files for any watched paths which are contained in a Git repository. To disable this behavior, pass --no-gitignore.

Scripting

In addition to using godemon at the command line, it can also be used in scripts as a generic file watcher utility.

To have godemon exit once a watched command finally succeeds, use --exit-on-success. This is more responsive and efficient compared to a while loop that repeatedly runs the command.

godemon --exit-on-success command

To have godemon just print all changes on stdout, use --print-changes. This allows using godemon's file watching capabilities directly:

godemon --print-changes
# Example output:
WRITE /tmp/foo
CHMOD /tmp/foo
CREATE /tmp/bar
REMOVE /tmp/bar

Throttling is disabled when using --print-changes.