ptwatch

ptwatch 1.0

License: MIT Copyright: pixeltamer.net 2018

ptwatch is a (not just) Go watcher that just works. It monitors source code for changes, automatically rebuilds projects and runs the results. It is designed to not force any particular semantics and make configuration easy.

Usage: ptwatch [options] [configfile...]

configfile defaults to ./default.ptwatch and also accepts glob patterns.

Options: Command line options override global and per-project config file settings

-h --help show help

-v --verbose enable verbose logging (overrides Verbose config file setting)

-q --quiet disable verbose logging (overrides Verbose config file setting)

-i --init initialize a default config file

-nr --norun disable run mode (overrides DisableRun config file setting)

-r --run force run mode (overrides DisableRun config file setting)

-b --build disable build mode (overrides DisableBuild config file setting)

-nb --nobuild force build mode (overrides DisableBuild config file setting)

-- treat all subsequent parameters as config file names

Build Mode Build Mode is on by default and can be disabled through the global and per-project DisableBuild setting. Building a project involves running the commands in the BuildCmd list sequentially until one fails or all succeeded. On success, a restart is triggered (if Run Mode is enabled). Additionally, dependent projects can be triggered to rebuild through the list of project names in the TriggerBuild list.

Rebuilds are triggered by file changes configured through the WatchPathInclude, WatchPathExclude, WatchFileInclude and WatchFileExclude lists.

Run Mode Run Mode is on by default and can be disabled through the global and per-project DisableRun setting. After a successful build, the RunCmd command line is executed. A previously started instances is stopped automatically. If Build Mode is disabled, building is assumed to be successful. Dependent projects can be restarted automatically through the TriggerRestart list.

Config File ptwatch assumes a default ".ptwatch" extension for its configuration files. If run without parameters, ptwatch uses "./default.ptwatch". If run with a directory argument, "

/default.ptwatch" is used if present. If exactly one "*.ptwatch" file is found, it is used automatically. Configuration file names may use glob patterns. All matching files are merged and used. Multiple paths can be specified too, they are merged as well. Config files are in RJSON (Relaxed JSON) format. Keys do not need to be quoted. String values only need to be quoted if they start with digits or contain whitespace or special characters. Numbers do not need to be quoted. Comma separators in lists and maps are optional. Additionally, they may have a shebang line as seen in the default config (see below). The configuration has global and per-project settings. Projects are handled concurrently.

Global Settings

• Verbose (true|false) optional, default false. Enable verbose logging.
• LogRunErrorsAsWarnings (true|false) optional, default false. Default value for per-project LogRunErrorsAsWarnings settings.
• DisableBuild (true|false) optional, default false. Default value for per-project DisableBuild settings.
• DisableRun (true|false) optional, default false. Default value for per-project DisableRun settings.

Project Settings

• Name (string) no default. Project name used in logging.
• Disabled (true|false) optional, default false. Ignore complete project entry.
• Verbose (true|false) optional, default global or false. Enable verbose logging.
• LogRunErrorsAsWarnings (true|false) optional, default global or false. Error messages from running commands are logged as warnings instead.
• DisableBuild (true|false) optional, default global or false. Do not build even if BuildCmd is specified. Acts as default for projects.
• DisableRun (true|false) optional, default global or false. Do not run even if RunCmd is specified. Acts as default for projects.
• BasePath (string) default "./". Base path for the project. Absolute or relative to current working directory.
• RunPath (string) no default. Path to start RunCmd in. Absolute or relative to base path.
• BuildPath (string) no default. Path to start BuildCmds in. Absolute or relative to base path.
• WatchPathInclude ([]string) default "./". List of paths to watch for changes.
• WatchPathExclude ([]string) default empty. List of paths not to watch for changes. Overrides WatchPathInclude matches.
• WatchFileInclude ([]string) default "*". List of glob patterns. Only files matching are considered on changes.
• WatchFileExclude ([]string) default empty. List of glob patterns to ignore on changes.
• BuildCmd ([]string) default empty. List of build commands to run.
• RunCmd (string) default empty. Command to run after builds.
• AutoRestart (string) default empty. Duration after which to restart automatically. Examples: "60s", "4h", "1d"
• TriggerRestart ([]string) default empty. List of projects to restart when this project restarts.
• TriggerBuild ([]string) default empty. List of projects to rebuild when this project builds successfully.

The example configuration produced by ptwatch --init is:

---snip---
#! /usr/bin/env ptwatch
{
	Verbose: false
	LogRunErrorsAsWarnings: false
	DisableBuild: false
	DisableRun: false
	Projects: [
		{
			Disabled: false
			Name: "Example"
			BasePath: ""
			RunPath: ""
			BuildPath: ""
			WatchPathInclude: [
				"."
			]
			WatchPathExclude: null
			WatchFileInclude: [
				"*"
			]
			WatchFileExclude: null
			BuildCmd: [
				"go build example.go"
				"echo Done"
			]
			RunCmd: "go run example.go"
			AutoRestart: ""
			TriggerRestart: null
			TriggerBuild: null
			Verbose: null
			LogRunErrorsAsWarnings: null
			DisableBuild: null
			DisableRun: null
		}
	]
}
---snap---