Dotfiles¶
Omni syncs dotfiles through a Git-backed GNU Stow repo. Config declares logical dot entries; Stow creates symlinks from the original filesystem locations to the repo package directories.
Stow packages are plain directories. If package nvim contains
.config/nvim/init.lua, Stow links that file back to ~/.config/nvim/init.lua.
Omni keeps this layout so the repo is auditable without running Omni.
Configure The Repo¶
The repo stores managed content under:
The outer ~/dotfiles path is the Git repository root. The inner dotfiles/
directory is the Stow package root. Git operations such as pull, commit, and
push run at the outer root; sync/adopt/link operations use the inner package
root.
For a logical entry named nvim with path ~/.config/nvim, the default source
path is:
Add A Dot Entry¶
Adopt an existing local path:
Discover candidates:
Choose the add mode deliberately:
| Command | Use when | Mutates local files? | Mutates repo files? |
|---|---|---|---|
omni dots add <path> --group <group> |
You want Omni to validate the path and stop before adoption. Current behavior requires --adopt for an existing local path. |
no | no |
omni dots add <path> --group <group> --adopt |
The current local path is the desired source of truth. | yes | copies/adopts into repo package |
omni dots add <name-or-path> --group <group> --discovered |
dots discover found an existing repo/local candidate and you only want to persist it. |
no | no |
dots discover reads three sources: packages under <dots_repo>/dotfiles/,
non-hidden children of ~/.config, and well-known home-level files such as
shell and tool config files. It filters entries already tracked by config.
Sync And Status¶
status includes symlink health and dotfiles repo Git state. sync creates or
repairs Stow links.
Launch Sync¶
Opening the TUI runs that same link repair once, for every entry, whenever a
dotfiles repo is configured. It pulls nothing; it is omni dots sync without
the Git step, and the footer reads Syncing dots… while it runs. So starting
the TUI is a mutating action, not a read-only look at state.
What it settles on its own:
| Entry state | Launch sync |
|---|---|
| Missing or broken link | Creates or repairs the link. |
| Local path with no repo source | Adopts the path into the repo, then links it. |
| Local file newer than its repo source | Adopts the local content: copies it into the repo and relinks the target. |
| Local file differs but is not newer | Left alone as a conflict. |
Adoption of a newer local file commits the repo's current state first
(dots: pre-sync <name>), so the replaced sources stay recoverable from Git
history. "Newer" is strictly by modification time, so a local file and its repo
source written within the same timestamp tick count as a conflict, not as an
edit to adopt.
A conflict is never resolved for you — it waits for u/l on the dots tab or
for omni dots resolve. A row key pressed while the launch sync is still
running is ignored, so let it finish before acting on a row.
For a look at dotfile state that changes nothing, use the CLI: omni dots
status and omni dots list are read-only.
Ignore Patterns¶
Ignore an entire logical dot entry:
Ignore files inside an entry:
Config shape:
{
"name": "nvim",
"path": "~/.config/nvim",
"ignore": ["*.log", "cache/", "/local.lua", "!/cache/keep"]
}
Patterns are gitignore-style and apply within the dot entry.
Host Variants¶
Use variants when the same logical dotfile needs different content on different machines:
omni dots variant add nvim --host workstation --package nvim@workstation
omni dots variant list nvim
omni dots variant remove nvim --host workstation
Config shape:
{
"name": "nvim",
"path": "~/.config/nvim",
"hosts": {
"workstation": { "package": "nvim@workstation" }
}
}
Resolve Conflicts¶
When local files and repo files disagree, choose the source explicitly:
Use repo when the dotfiles repo should replace local content. Use local when the current machine has the desired content and the repo should be updated.
Force-resolve every conflict in one pass instead of per entry:
omni dots sync --use-repo # keep the repo version for all conflicts
omni dots sync --use-local # adopt the local version for all conflicts
A per-entry on_conflict policy still wins over the sync-wide flag. In the TUI,
press U (use repo) or L (use local) on the dots tab to force-resolve all
conflicts at once; both prompt for confirmation.
Extract A Subdirectory¶
Split a subdirectory out of a tracked directory entry into its own entry so it can belong to a different group than its parent:
omni dots extract nvim lua/plugins --group work
omni dots extract nvim lua/plugins --group work --name nvim-plugins
The parent stops managing the subtree (an ignore is added) and the subtree is
adopted as a new entry assigned to --group (default: this host's group). In
the TUI, expand an entry and press g on a child sub-path row to do the same.
Git Workflow¶
pull fetches remote dotfile changes and then syncs links. push stages,
commits, and pushes all dotfiles repo changes.
Omni's automatic safety checkpoints never commit the current branch. They
snapshot the worktree on the local omni/backup branch without changing HEAD,
the index, or the worktree, and never push that branch. Explicit commit,
push, auto_commit, and auto_push retain their documented Git behavior.
Native Services¶
Reminders check whether dotfiles need attention:
Watch sync runs a local service that syncs after file changes:
Inspect both:
Native service support depends on the current platform. Omni uses user-level services such as launchd or systemd where available.
Backups¶
Before replacing local dotfiles, Omni creates safety copies under:
Review backups before deleting them.
Repository checkpoints are available through native Git: