Perch

Perch is a tool that lets you run commands in response to file changes.

Installation

The quickest way to install Perch is via the installation script.

curl -fsSL https://raw.githubusercontent.com/uint4096/perch/main/installation/script.sh | bash

The script places the binary in your $PATH and configures Perch to run as a background service. You can see the contents of the installation script.

Building from Source

You can clone this repo and build it from source.

Requirements

• OS: Linux (systemd), macOS
• Go: >=1.26
• make >=4.4.1

Steps

1. Clone the repo

git clone https://github.com/uint4096/perch

2. Run make

make

By default, make runs the service-install target: it builds the binary, creates an empty configuration, and starts Perch as a background service.

You can uninstall Perch by running make uninstall.

Configuration

The configuration for Perch lives at $HOME/.config/perch/perchconf.toml. Here's an example configuration that echoes the names of changed .txt files within the /tmp/myDir directory.

[[Watches]]
Path = "/tmp/myDir"
Events = ["create", "remove", "write"]
Command = 'echo "changed file: $PERCH_TARGET_FILE. Events: $PERCH_TARGET_EVENTS"'
WorkingDir = "/tmp/myDir"
Include = ["*.txt"]
Debounce = 30

In the configuration above, the echo command runs every time any file ending with .txt is created, deleted, or written to. Command can be a shell command or a path to an executable script.

Path can be either a file or a directory. For directories, Perch recursively resolves any subdirectories.

Perch exposes the following environment variables which you can use within the Command config:

• $PERCH_TARGET_FILE: The full path to the file that changed.
• $PERCH_TARGET_EVENTS: A list of change events as space-separated strings (unordered). Quick successive events can overwrite earlier ones.
• $PERCH_TARGET_DELETED: true if the target file no longer exists during command execution (i.e. it was deleted), false otherwise.

Note: Globstar (**) syntax is not yet supported.

See the configuration reference for a complete list of options.

Service

Running the installation script automatically configures Perch as a background service. If you're building from source, you can use the minimal service files (perchd.service for systemd, perchd.plist for launchd) in the installation directory to get started.

Note: Perch reads its configuration once at startup, so restart the service after editing perchconf.toml for the changes to take effect.

Linux

The installation script configures Perch to run as a systemd service under your user account, so it doesn't require root access.

Checking service status

systemctl --user status perchd.service

Checking logs

journalctl --user -u perchd.service -f

Restarting the service

systemctl --user restart perchd.service

macOS

Perch runs as a launchd user agent under your user account on macOS.

Checking service status

launchctl print gui/$(id -u)/com.perch.perchd

Checking logs

Perch writes its output to ~/Library/Logs/perchd.log.

tail -f ~/Library/Logs/perchd.log

Restarting the service

launchctl kickstart -k gui/$(id -u)/com.perch.perchd

CLI Reference

Command	Description
perch	Run the watcher in the foreground using the configured watches
perch validate	Verify whether the config file is valid
perch version	Print the current version
perch help	Print usage information

License

Perch is licensed under the GNU General Public License v3.0 or later. See LICENSE for the full text.