02 · 仓库地图与安装边界¶

仓库目录不是最终机器上的目录。读 Quattro 的第一道门槛，是理解同一份源代码如何被打包、安装、复制、链接或生成到不同位置。

顶层目录按责任分组¶

omarchy/
├── bin/           统一 CLI、432 个命名文件（430 个可执行入口）
├── default/       发行默认值、systemd unit、模板、session 集成
├── config/        新用户可编辑配置的种子
├── etc/           Omarchy 自有的 /etc 文件
├── install/       系统、登录、硬件、用户阶段的编排脚本
├── migrations/    已安装系统的增量演进
├── shell/         Quickshell UI、服务与内置插件
├── themes/        内置主题源
├── applications/  预装 desktop entries 与图标
├── agents/        AI agent 集成与 skills
├── test/          CLI、纯逻辑与图形验收
└── docs/          上游实现文档

default/ 与 config/ 最容易混淆：前者通常是产品拥有的默认值或系统集成源；后者是将来属于用户的初始配置。它们安装后的所有权与更新语义不同。

两个主包，两种时机¶

Quattro 的 PKGBUILD 位于配套的 omarchy-pkgs 仓库，而当前仓库提供被打包的内容。核心逻辑分成两个主包：

包	为什么存在	典型内容
`omarchy-settings`	用户创建前必须存在	`/etc/skel`、系统配置 drop-in、字体、Plymouth、SDDM、启动/快照配置
`omarchy`	正常运行与持续更新	`/usr/share/omarchy`、`/usr/bin/omarchy*`、安装器、迁移、主题、Shell

另外还有独立的 keyring 与 Neovim 包。拆包不是为了代码美观，而是解决安装时序：如果用户先创建，再安装 /etc/skel，新用户就拿不到应有的初始配置。

`/usr/share` 是不可变基线¶

生产环境下，仓库内容主要落到：

/usr/share/omarchy/      版本化的实现与资源
/usr/bin/omarchy         CLI router
/usr/bin/omarchy-*       可执行动作
/etc/...                 系统级集成
/usr/lib/...             hooks、units 等系统资源

设计上把 /usr/share/omarchy 当成包管理器拥有的不可变基线。用户不应在那里直接修改；包升级会替换它。

用户 home 的三种来源¶

flowchart TD
    Package[omarchy-settings] --> Skel[/etc/skel]
    Skel -->|创建用户时复制| Home[用户 Home]
    Package2[omarchy] --> Finalizer[omarchy-provision-user]
    Finalizer -->|补齐/生成| Home
    Reinstall[omarchy-reinstall-configs] -->|显式破坏性同步| Home

1. seed：`/etc/skel`¶

只在用户创建时复制一次。它不是持续同步机制，因此后续 package upgrade 不会自动覆盖用户已拿到的配置。

2. finalize：用户 provisioning¶

在确定具体 owner 后，以该用户身份补齐目录、agent skill 链接、应用默认值和首次安装状态。这一阶段知道“哪个 home”以及“谁拥有文件”。

3. reinstall：显式重置¶

omarchy-reinstall-configs 才是把发行配置重新同步到 home 的主动操作。它可能覆盖用户内容，所以不能偷偷挂在日常更新中。

不要用安装路径猜所有权

一个文件最初来自包，不代表其 home 副本仍由包拥有。/etc/skel 的副本一旦进入 home，就是用户文件；后续迁移需要保留修改或明确备份。

为什么有 `etc-overrides/`¶

如果某个 /etc 文件已经由 Arch 上游包拥有，Omarchy 的包不能再声明拥有同一路径，否则 pacman 会冲突。Quattro 对这类文件采用 package scriptlet 复制覆盖的方式，概念上归入 etc-overrides/。

这解决了包所有权冲突，但有明确代价：覆盖动作可能替换管理员修改。它适合 Omarchy 必须统一控制、且更新语义已知的少数文件，不适合作为通用配置策略。

延迟 provisioning¶

安装介质或自动化场景中，系统应用时可能还不知道最终用户名。此时系统阶段写入：

/var/lib/omarchy/provisioning/pending

首启服务发现 pending 后创建或确定 owner，再执行用户 finalization。于是“装好包”和“完成用户体验”之间可以跨一次 reboot，而不是假设安装脚本拥有完整图形会话。

sequenceDiagram
    participant I as 安装环境(root)
    participant D as 磁盘状态
    participant B as 首次启动服务
    participant U as owner 用户
    I->>D: 安装 settings + omarchy
    I->>D: 写 provisioning/pending
    I-->>B: reboot
    B->>D: 读取 pending
    B->>U: 创建/确定 owner
    B->>U: 运行 user finalizer

`OMARCHY_PATH`：开发与生产共用坐标¶

代码不把 /usr/share/omarchy 散落硬编码在每个文件中，而由 default/bash/env-bootstrap 建立 OMARCHY_PATH：

/etc/omarchy.conf 有有效开发路径时使用 checkout；
没有时强制回到 /usr/share/omarchy；
开发模式把 checkout 的 bin 放到 PATH 前面；
再加入 mise shims 和用户 local bin。

omarchy-dev-link 会写入 /etc/omarchy.conf，并同步 sudo secure_path drop-in。这样普通 shell 与 sudo 都指向同一份开发命令，避免“用户跑 checkout、sudo 跑安装版”的幽灵差异。

关键源码索引¶

docs/file-layout.md — 包、home 与系统路径的官方说明
default/bash/env-bootstrap — OMARCHY_PATH 判定与 PATH 构造
bin/omarchy-dev-link — checkout 链接与 sudo PATH
bin/omarchy-provision-user — 用户 finalization
install/provisioning/omarchy-provision-owner.service — 延迟 provisioning unit

下一章沿机器第一次落地的顺序走完整条链：03 · 安装、引导与首登。