State

dots keeps local state in the dotfiles repo:

.dots/state.json

Do not commit this file. It belongs to one machine.

State is what lets dots update and remove only the resources it manages. It stores each resource's last applied configuration and the profiles that own it. See profile cleanup rules.

If your state file predates profile ownership, delete .dots/state.json and apply each profile again. Dots cannot infer ownership from the old file.

Track an existing resource

When a declaration already matches the machine, dots check shows it under Tracking. For example:

Tracking:
  ~ file /etc/myapp/config.toml

dots apply adds the resource to state without changing it. Once tracked, dots can update or remove it when the declaration changes.

List managed entries

Run:

dots state list

Example entries:

symlink:/home/me/.zshrc
package:paru:ripgrep
service:systemd:start:docker.service
font:/home/me/.local/share/fonts/dots/runcat.ttf
file:/etc/myapp/config.toml
directory:/srv/myapp/uploads
group:media
user-group:media

Forget an entry

Use forget when the resource should stay on the machine but dots should stop managing it.

For example, to keep an uploads directory and a configuration file:

dots state forget directory:/srv/myapp/uploads
dots state forget file:/etc/myapp/config.toml

Both paths stay where they are. forget removes their state entries for all profiles.

Remove the corresponding declarations from dots.lua first. If a declaration is still present, the next dots apply offers to track the resource again. Use dots state list to copy the exact entry name.

The same command can leave an installed package or running service unmanaged:

dots state forget package:paru:ripgrep
dots state forget service:systemd:start:docker.service

It does not uninstall the package or stop the service.