# File-watch Auto-restart

While a configured command is running, a matching on-disk file change triggers its restart. It's useful when your tool doesn't already have a good built-in watch mode.

## Configure watch patterns

1. Select the command in the sidebar.
2. Open the command context menu and choose **Edit command...**.
3. Add patterns under **File watching**.

Patterns are stored as `restart_when_changed` and are evaluated against paths relative to the project root.

Changing patterns while a command is running does not re-register its watcher. Restart the command for the new pattern list to take effect.

## Pattern notes

Solo uses glob matching for restart patterns. In this matcher, `*` can match across path separators. Prefer explicit patterns like `src/**/*.ts`, `config/**`, or `**/*.go`.

- Patterns must be project-relative. Absolute paths and patterns containing `..` components are skipped.
- Each pattern-derived watch root must exist when the watcher starts. If a missing root is created later, restart the command to register it.
- A watch root that resolves outside the canonical project root, including through a symlink, is skipped.
- Solo skips unsafe roots, including protected macOS app-data directories and overly broad recursive roots such as your home directory.

## Runtime behavior

- Solo watches pattern-derived roots within the project. Wildcard-derived roots are recursive; a literal-file pattern watches its parent directory nonrecursively.
- File events use two fixed 500 ms debounce intervals. The callback forwards the first match and suppresses later matches within its window; independently, the restart processor waits at least 500 ms after that forwarded match. It does not implement a trailing-edge quiet window measured from the last raw event.
- On match, Solo performs a full restart cycle for that command and emits a file-restart event.
- File-watch restarts are command-only and [trusted-only](./trust-security.md).
- An empty list or a list with no usable patterns creates no watcher. In a mixed list, Solo skips unusable entries and keeps usable entries active.

## Interaction with crash auto-restart

File-watch restarts and [crash auto-restart](./auto-restart.md) are separate mechanisms. File-watch restarts are triggered by matching file events; crash auto-restart is triggered by process exits and has its own crash-loop limit.

## Operational tips

- Avoid very broad patterns in large repos unless you really need them — they can cause unnecessary restarts.
- Because `*` can match path separators in Solo's matcher, use anchored patterns when you only want a narrow part of the repo.

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/commands/file-watch-auto-restart