What in the vault does obsync actually track?

[andyroberts2]

Part of #1

Question

What in the vault does obsync actually track?

An Obsidian vault contains far more than notes, and some of it churns constantly or does not belong in git at all.

To decide:

• .obsidian/. Genuinely contested. workspace.json / workspace-mobile.json are rewritten on every pane focus and must be excluded. But whether the rest — app.json, appearance.json, core-plugins.json, community plugin code, and plugins/*/data.json — should be tracked is a real judgement call, and plugin data can contain secrets.
• .trash/. Almost certainly excluded; confirm.
• Attachments, and whether git-LFS is in scope. Vaults accumulate images and PDFs. Git handles large binaries badly, kubernetes/git-sync has no LFS support at all, and GitHub bills LFS bandwidth. This may be the decision that reshapes the design most.
• Ship a default .gitignore, or require the user to bring one? If obsync ships one, what happens when the vault already has one.
• The untracked-file gate. simonthum/git-sync refuses to run if any untracked file exists unless explicitly opted in, precisely to stop accidental commits of junk or secrets. Whether obsync adopts anything like this.

[andyroberts2]

Resolution

obsync tracks the vault, minus a fixed floor it owns, minus a small set of paths it refuses at commit time. Two mechanisms, because there are two kinds of exclusion: the noisy, which the user may overrule, and the dangerous, which they may not.

The ignore floor

obsync owns an ignore floor written to .git/info/exclude at every startup — rewritten wholesale under a marker comment, idempotent. It is never committed, so it cannot conflict, cannot be clobbered by an external push, and cannot be disabled by editing a note. obsync never writes the vault's .gitignore; that file is content, it is the user's, and obsync only reads it (free, via git status).

The floor:

.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/workspaces.json
.obsidian/plugins/*/data.json
.trash/
.DS_Store
Thumbs.db
.vscode/
.idea/
.obsidian-git-data
obsync-attention.md

Everything else under .obsidian/ is tracked — app.json, appearance.json, core-plugins.json, community-plugins.json, and each plugin's main.js/manifest.json/styles.css — so a fresh clone arrives with the same theme, hotkeys, and plugin set. data.json is excluded because plugin settings are where community plugins keep API keys (Copilot, Smart Connections, and friends), and this project's audience points it at repos that may be public. Plugins arriving installed-but-unconfigured is an annoyance; a key in a public repo is not recoverable.

.trash/ is excluded with the consequence stated deliberately: git history is the undelete mechanism, and Obsidian's own trash duplicating it is pure cost.

The floor is a default, not a rule

Verified empirically on git 2.51: git's precedence is .gitignore first, $GIT_DIR/info/exclude second, so a vault-root .gitignore containing !.obsidian/workspace.json overrides the floor and the file reappears. This is by design. A user who wants their workspace layout synced is entitled to it, and a tool that cannot be overruled becomes a tool people work around.

One exception. .obsidian/plugins/*/data.json is also applied as a pathspec exclusion on the git add itself, which no .gitignore can negate. Overriding a noisy default is a preference; committing a credential is unrecoverable. Two mechanisms, two kinds of entry.

The floor takes no configuration

No knobs, no policy toggles, no user-supplied extra-ignores list. The override mechanism is the user's own .gitignore — standard, discoverable, already outranking the floor, and the same file every other Obsidian git tool has taught them to write. A config knob would be a second and worse way to do the same thing, and every knob is a combination the conflict and untrack paths have to reason about. (Follows #7's precedent: one rule, not configurable.)

Already-tracked paths

Ignore rules only ever affect untracked paths. A vault whose history already contains workspace.json churns forever regardless of the floor, so obsync untracks the churn subset once — git rm --cached on workspace*.json, workspaces.json, .trash/, and the cruft entries — in a single, loudly-messaged commit. Files stay on disk (--cached only). This runs once, as a one-shot condition at the top of the local half after the first successful fetch and merge, not as a bootstrap step: untracking against a stale tip risks doing it twice, and when the remote is unreachable obsync is in #6's degraded local-autocommitter mode, which is exactly when it should not make structural commits it cannot push.

Already-tracked data.json is left alone. Untracking it would delete deliberately-synced plugin settings from every other clone on the next pull, and would not unleak a key that is already in the remote's history. The secrets rule is never be the thing that commits a key for the first time — refuse to add, never remove. obsync logs loudly at startup when it finds tracked data.json files and leaves the history call to the human.

Stated cost of the untrack commit: it deletes those paths from every other clone on their next pull. For workspace.json that is the point. It is why the floor stays narrow.

Attachments, and git-LFS

Attachments are committed as ordinary git blobs. git-LFS is out of scope — not deferred, ruled out. LFS is a per-repo setup act the user performs (git lfs track, a committed .gitattributes); if they have done it, obsync inherits it for free by simply running git, and no obsync feature is required. What obsync must never do is configure LFS on the user's behalf. The mechanical reason it would be more than a feature flag: #7's out-of-tree merge would compute conflicts over pointer files rather than content, so a keep-both of two LFS attachments yields a conflict copy pointing at an object that may never have been fetched.

The in-scope residue is a size ceiling: obsync refuses to commit any single file above it, rather than building a commit the push will reject forever. Default 95MB — under GitHub's 100MB hard block, above its 50MB soft warning, so obsync refuses only what genuinely cannot be pushed. This is the one configurable value in this decision, and it is the exception that proves the no-knobs rule: it is not taste, it is a fact about the remote, and 100MB is GitHub's number, wrong for every self-hosted Gitea or GitLab obsync will also run against.

The refusal layer

simonthum/git-sync's hard stop on any untracked file is right in spirit and unusable in letter: in a vault, every new note is an untracked file, so a literal adoption freezes on first use. Its real value is not untracked is suspicious but have an opinion about what you sweep in. So: untracked notes and attachments sweep in silently, and a small closed list of refused paths never enters a commit.

Refusal is name-matching only — no content scanning, ever. Sniffing for -----BEGIN OPENSSH PRIVATE KEY----- would catch a key saved as notes.md, but this is a note-taking vault: people write notes about keys, paste example blocks into documentation, keep security runbooks. Given refusal is silent-by-omission, a false positive is the expensive error, and nobody names a note id_rsa.

The list, closed, with no escape hatch:

.env, .env.*
id_rsa, id_dsa, id_ecdsa, id_ed25519
*.pem, *.key, *.p12, *.pfx
.netrc, .npmrc, .pypirc
credentials

plus any single file over the size ceiling. The list stays short precisely so no escape hatch is needed. Honest cost: someone who genuinely wants a .pem in their vault cannot sync it, and their recourse is to rename the file.

Refusal skips the path — it never freezes the loop

This reverses the initial reading. A refused path is skipped; everything else commits and pushes normally. If a 200MB video lands in the vault and obsync network-freezes, every note the user writes stops reaching the remote because of an attachment — and the freeze removes nothing and protects nothing that skipping had not already protected. A stopped sidecar is the failure that gets a sync tool uninstalled.

The committable set

Refusal creates a hole that has to be closed: a tracked file modified past the ceiling leaves git status permanently dirty, and #5's "commit if dirty" cadence would wake every tick, stage nothing, and either produce empty commits or re-log the same warning every 60 seconds forever.

So the loop's gate changes. Define the committable set — the paths a sync run would actually stage, after the floor and after refusals. #5's "commit if dirty" becomes "commit if the committable set is non-empty." A tree containing only refused paths is quiescent: no commit, no push, no repeated warning. WARN fires once per path on transition; the standing signal is the attention note.

Consequence, to be stated plainly in the spec: while a tracked path is refused, the remote holds the last version that passed and the working tree holds a newer one. Stale, consistent, and visible — the right trade against a commit that can never push.

The attention note

#7's conflict note is renamed the attention note, file obsync-attention.md at the vault root, and now carries both concerns in sections: outstanding conflict copies, and refused paths. Two notes competing for the vault root is clutter, and from the user's side both say the same thing — obsync needs you to look at something. The name generalises to whatever a later ticket adds without a third rename. See the amendment on #7.

All of #7's properties survive: derived from what is on disk each run, never authoritative over it, deleted when every section is empty.

The note is floored, not tracked — it is in .git/info/exclude. Nothing is lost, since it is regenerated each run from what is actually in the vault (conflict copies, which are committed; refused paths, which are local by definition), so it is reconstructible wherever it is meaningful and meaningless where it is not. Tracking it would put derived state in history, add create/delete churn on exactly the paths a user is already anxious about, and push a warning to readers who cannot act on it.

A WARN line alone is not enough: nobody reads a sidecar's logs, and the vault is the only place this user is looking. Never an unhealthy check — same discipline as #7.

Vocabulary added to CONTEXT.md

Ignore floor, committable set, refused path, and conflict note → attention note.

Opened by this decision

The size ceiling's policy is settled, but its mechanism inside #7's out-of-tree merge is not: conflict copies are written into a tree object by commit-tree, never staged by git add, so the pathspec refusal layer does not reach them, and "refuse" mid-merge has to say what the tree holds at that path instead. Ticketed separately rather than hand-waved here.