nightwatch/README.md

     _   _ _       _     _     _       _     _       _
    | \ | (_)     | |   | |   | \     / |   | |     | |
    |  \| |_  __ _| |__ | |_  \  \ _ /  /_ _| |_  __| |___
    | . ` | |/ _` | '_ \| __|  \  ` '  / _` | __|/ _| '_  \
    | |\  | | (_| | | | | |_    \     / (_| | |_| (_| | | |
    |_| \_|_|\__, |_| |_|\__|    \_|_/ \__,_|\__|\__|_| |_|
              __/ |
             |___/
                   T H E   N I G H T   W A T C H

The city sleeps. The files do not.

"FABRICATI DIEM, PVNC"

The Night Watch is a file change tracker for directory trees, written in Zig.

It provides:

• A standalone CLI for tracking filesystem changes
• A module for embedding change-tracking into other Zig programs
• Minimal dependencies and consistent, predictable, cross-platform behavior

It does not interfere. It does not speculate. It simply keeps watch.

---

Features

• Recursive directory tree tracking
• Deterministic multi-platform support (Linux, macOS, FreeBSD, OpenBSD, NetBSD, DragonFly BSD, Windows)
• Lightweight and fast
• Embeddable Zig module API
• Standalone CLI executable

Platform backends

Platform	Backend	Notes
Linux	inotify	Threaded mode (default) or poll mode (-Dlinux_read_thread=false)
macOS	kqueue (default) or FSEvents (-Dmacos_fsevents=true)	FSEvents requires Xcode frameworks
FreeBSD, OpenBSD, NetBSD, DragonFly BSD	kqueue
Windows	ReadDirectoryChangesW

---

Installation

The Watch is written in Zig and built using the Zig build system.

Requirements

• Zig (currently zig-0.15.2)

Build CLI

zig build

The executable will be located in:

zig-out/bin/nightwatch

Install System-Wide

zig build install

---

Using as a Zig Module

The Night Watch exposes a reusable module that can be imported into other Zig programs.

In your build.zig:

const nightwatch = b.dependency("nightwatch", .{
    .target = target,
    .optimize = optimize,
});

exe.root_module.addImport("nightwatch", nightwatch.module("nightwatch"));

In your Zig source:

const nightwatch = @import("nightwatch");

You now have programmatic access to the tracking engine.

---

CLI Usage

nightwatch [{path}..]

Run:

nightwatch --help

for full command documentation.

---

Philosophy

Other tools watch files.

The Night Watch keeps watch over the peace.

It remembers what changed. It records what vanished. It notices what arrived at 2:14 AM.

And it writes it down.