状态路径表

本表是“这个文件归谁、什么时候写、能不能删”的快速参考。$OMARCHY_PATH 在生产通常为 /usr/share/omarchy。

发行与系统层

路径	所有者/写入者	语义	注意
/usr/share/omarchy	pacman	当前版本实现与资源	不原地定制
/usr/bin/omarchy*	pacman	router 与动作入口	开发 checkout 通过 PATH 抢先
/etc/omarchy.conf	omarchy-dev-link	开发 checkout 路径	缺失时回生产路径
/etc/skel	settings package	新用户 seed	不是持续同步源
/etc/pacman.conf / mirrorlist	channel/config 命令	package 渠道	切换后需 update 收敛
/usr/share/libalpm/hooks	package	pacman 事务 guard/reload hook	保护 Omarchy update 顺序
/var/lib/omarchy/provisioning	root provisioning/reset	跨 boot pending 与临时 key	pending 是安全闸门
/var/log/omarchy-system-factory-reset.log	reset staging	reset 日志	early finish 主要进 journal
Btrfs @factory	Quattro installer	fresh factory baseline	升级机通常没有
/.snapshots	Snapper	可启动/可恢复快照	覆盖范围取决于 config

用户意图

路径	内容	合并语义
~/.config/omarchy/shell.json	active bar、widgets、启用插件、idle	有效文件整体替换 default
~/.config/omarchy/shell.toml	机器级 Shell token	覆盖活动主题并实时监视
~/.config/omarchy/extensions/omarchy-menu.jsonc	用户菜单扩展	同 ID 字段级覆盖，新 ID 追加
~/.config/omarchy/themes/<name>	用户/安装主题源	同名内容叠加到主题 staging
~/.config/omarchy/themed	用户模板	叠加/覆盖 packaged templates
~/.config/omarchy/plugins/<id>	第三方 QML 插件 checkout	enable 后执行，inotify 热载
~/.config/omarchy/hooks/<event>	单个用户 hook	先于同名 .d
~/.config/omarchy/hooks/<event>.d/*	多个 hook	sample 跳过；失败报告后继续
~/.config/hypr/hyprland.lua	Hyprland 用户入口	defaults 后加载用户模块
~/.config/hypr/*.lua	monitors/input/bindings/look/autostart	后加载覆盖发行 defaults
~/.config/xdg-terminals.list	默认终端	标准 xdg-terminal-exec 输入

生成与完成状态

路径	生成者	表示	是否可直接改
~/.local/state/omarchy/current/theme	omarchy-theme-set	活动主题完整产物	否；下次切换覆盖
~/.local/state/omarchy/current/theme.name	theme set	当前逻辑主题名	用 CLI 改
~/.local/state/omarchy/current/*.lua	Hyprland toggle	动态配置模块	用 toggle 命令改
~/.local/state/omarchy/done/finalize-user	provision user	用户 finalization 成功	删除会重放一次性动作
~/.local/state/omarchy/done/first-run-user	first-run	图形首登成功	删除会重跑欢迎/配置
~/.local/state/omarchy/migrations/<file>	migrator	某迁移 exit 0	不应为绕过错误手工创建
用户选择类 state	default/editor/agent 等命令	当前选择	应通过对应命令维护

运行时与临时状态

路径/机制	生命周期	用途
$XDG_RUNTIME_DIR/hypr/<signature>	Hyprland session	socket 与 instance discovery
$XDG_RUNTIME_DIR/bus	用户 session	D-Bus 地址
update/theme/restart lock	操作或 session	防并发执行
/tmp/omarchy-update.log	临时但跨 updater 进程可读	完整 update transcript
menu selection/done files	一次 select/input	CLI 与 QML 同步握手
screen recording pid/state	一次录制	stop signal 与 overlay 收尾
notification popup JSON	用户 runtime/state 实现	popup identity 与 history 迁移

删除前问什么

flowchart TD
    P[准备删除一个状态文件] --> Owner{谁生成?}
    Owner --> Promise{它承诺完成事实吗?}
    Promise -->|migration/done/pending| Stop[先验证目标状态与重放副作用]
    Promise -->|纯 cache/staging| Active{当前进程还在使用?}
    Active -->|是| Grace[先停服务/获取锁]
    Active -->|否| Rebuild[确认有重建命令后删除]

特别警惕名字很小的空 marker：内容为空不代表影响小。