gomon

gomon is a minimalist, dependency-free (aside from a filesystem watcher), and highly efficient file watcher and process restarter built in Go. It's designed to monitor local file changes and automatically restart your command without relying on bulky external tooling.

---

🚀 Installation

gomon is easily installed using the standard Go toolchain.

go install github.com/audinue/gomon@latest

Ensure your GOPATH/bin directory is in your system's PATH to run the command directly.

---

💡 Why gomon? (Technical Philosophy)

gomon was created to provide a precise and robust process supervision tool based entirely on the Go standard library and native Unix system calls, adhering to the philosophy of "Do the Right Things."

• Minimal Footprint: No heavy dependencies—only a reliable file system watcher (github.com/rjeczalik/notify) is used.
• Clean Process Killing: It uses Process Group Isolation (Setpgid: true) and SIGTERM to the Process Group ID (-PGID) to ensure your target process and all its child processes are cleanly terminated before a restart, avoiding orphaned processes.
• Built-in Debouncing: Implements a state-of-the-art time.Timer mechanism (Go 1.23+ idiom) for precise debounce, preventing rapid restarts from multiple simultaneous file saves.

---

🛠️ Usage

Simply prefix the command you wish to monitor with gomon.

Monitoring a Go Program

To watch for changes and automatically restart a Go application:

gomon go run hello-world.go

Monitoring Any Command

You can use gomon to watch files and restart any script or executable:

gomon ./server-build --port 8080
# or for a simple script:
gomon bash script.sh

---

⚙️ How it Works

1. Watch: gomon starts watching the current directory (./...) for Create, Write, and Remove events.
2. Start: The target command is executed in a new isolated Process Group.
3. Debounce: Upon detecting a file event, a timer is reset (currently set to 16ms).
4. Restart: If no further file events occur before the timer expires, the Process.Stop() method sends a SIGTERM signal to the entire Process Group, waits for it to terminate, and then executes Process.Start() to launch the command again.
5. Graceful Exit: Pressing $\text{CTRL}+\text{C}$ sends a SIGINT to gomon, which then gracefully terminates the monitored process group before exiting itself.

---

🏗️ Technical Implementation Details

The core logic of process management is encapsulated in the Process struct and uses the following primitives:

• syscall.SysProcAttr{Setpgid: true}: Creates a new Process Group for the target command.
• syscall.Kill(-pgid, syscall.SIGTERM): Ensures a full, clean shutdown of the process and its children.
• errors.Join(p.Stop(), p.Start()): The Restart() function handles and reports combined errors from the stop and start operations, prioritizing continuous supervision.

---

This README was written by Gemini 2.5 Flash