# solo.yml change notifications

Solo watches each open project's root directory for `solo.yml` changes and marks the project as out of sync when the file content differs from the last synced version.

The watcher debounces filesystem events and compares file hashes, so repeated save events do not necessarily create repeated sync prompts. If a branch switch or edit returns `solo.yml` to the last synced content, Solo clears the out-of-sync state.

## What triggers a sync

Common cases:

- `git pull` updates `solo.yml`
- Switching branches changes, removes, or restores `solo.yml`
- You edit and save `solo.yml` directly
- A tool rewrites the file
- The file becomes unreadable or larger than Solo's 1 MB YAML limit

## What you see

When a project needs syncing, Solo shows:

- A warning indicator in the project area of the sidebar.
- A **Sync** banner/action in the sidebar project UI.
- A persistent **solo.yml changed** toast. Click the toast to open the project in its owning workspace and window, or click its **X** to dismiss it without navigating.

## Sync action

Click **Sync** to apply the latest `solo.yml` into Solo. Syncing can:

- Add new commands
- Update changed commands
- Remove deleted commands
- Preserve a command row across an unambiguous rename when the command string matches

If removed commands are currently running, they're stopped during sync.

YAML commands that would collide with an existing terminal or agent name are skipped instead of overwriting that non-command item.

## Trust and sync

Commands may require [trust](../commands/trust-security.md) again after sync when critical configuration changes. That includes changes to:

- The command string
- The working directory
- [Auto-start](../commands/auto-start.md) or [auto-restart](../commands/auto-restart.md) behavior
- [File-watch restart patterns](../commands/file-watch-auto-restart.md)
- Environment values

If a command variant has already been trusted on your machine, Solo can reuse that trust across branch switches even if the process name changes. Enabling **Automatically trust command changes** in the project settings applies trust automatically for that project's commands, so review them before you turn it on. During a sync, working directories that do not resolve safely inside the repo are not auto-trusted.

## Auto-start and restarts

Sync updates configuration only. It doesn't automatically restart or auto-start commands as part of the sync action itself.

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/projects/yml-change-notifications