n-commit 0.1.0

Git-shaped sync between Notion database views and folders of markdown files

notion-sync

Git-shaped sync between Notion database views and local folders of markdown files. Notion is the source of truth; you decide when to pull and push.

Install

pip install n-commit

First call opens a browser for OAuth. Tokens cache at ~/.config/notion-sync/tokens/.

Onboarding

mkdir my-notion && cd my-notion
n-commit add interviews --view "https://www.notion.so/…?v=…"
# repeat for each binding; the first `add` creates notion-sync.toml + .gitignore

To use the same workspace on another machine: copy notion-sync.toml to a folder and run n-commit pull. (Git, scp, Dropbox — anything that moves a 1KB text file.)

Mental model

A workspace is a directory tree containing one notion-sync.toml manifest at its root and one subfolder per binding. Each binding mirrors one Notion database view.

~/my-notion/
├── notion-sync.toml          ← the manifest (committed)
├── .gitignore                ← ignores **/.notion/
├── interviews/
│   ├── _FIELDS.md            ← cheat sheet, regenerated on bind
│   ├── jane.md               ← row ↔ file
│   └── .notion/              ← cache (gitignored)
│       ├── schema.json
│       ├── fingerprints.json
│       └── mirror/jane.md    ← last-pulled bytes
└── crm/people/
    ├── _FIELDS.md
    ├── alice.md
    └── .notion/

Manifest:

[folders."interviews"]
view = "https://www.notion.so/…?v=…"

[folders."crm/people"]
view = "https://www.notion.so/…?v=…"

Workspace is found by walking up from cwd, like git finds .git/. One file describes every binding.

Verbs

add, remove, status, pull, push, restore. Run n-commit <verb> --help for the per-verb reference. API-call cost per verb:

Verb	Reads remote	Writes remote	Writes local	Default API calls
add	yes (one-time)	no	yes	1 list_rows + 1 fetch_schema (+ N fetch_row if --init=push)
status	only --remote	no	no	0 (or 1 list_rows per binding)
pull	yes	no	yes (clean only)	1 list_rows per binding + N fetch_row (cache misses only)
push	yes (drift check)	yes	yes (echo)	3/file (drift+update+echo); 2 with --force
restore	no	no	yes	0

Conflict / drift playbook

• pull → ConflictError (dirty file + remote also changed):
  • keep local: push <file> (will DriftError if remote also moved → --force)
  • take remote: restore <file> then re-pull
  • both diverged: open file, mirror at .notion/mirror/<rel>, hand-merge, push
• push → DriftError (mirror diverged from current remote):
  • keep local: pull --force, re-merge, push. Or push --force.
  • take remote: restore <file>
• status --remote surfaces conflicts early — cheapest place to catch them.

Layout

File	Role
notion_sync/core.py	The five primitives + CLI entrypoint. All filesystem IO.
notion_sync/manifest.py	notion-sync.toml read/write/find. Pure, no Notion deps.
notion_sync/frontmatter.py	Pure transforms: envelope parse, props ↔ YAML, body normalize, row fingerprint, slug.
notion_sync/client.py	Typed Notion MCP wrapper.
notion_sync/auth.py	Generic MCP OAuth (PKCE) with fcntl.flock to serialize refresh-token rotation.
notion_sync/mcp_client.py	Generic MCP transport + dynamic tool proxy.

Invariants

• fetch_row is the single source of truth for row bytes. Never mix list_rows props with envelope-fetch props in the same path — they disagree on edge keys.
• Mirror is always updated on pull, even on conflict. Working files are only overwritten if clean (or --force). Conflicts surface loudly via ConflictError.
• Canonicalization for hashing. normalize_body strips presigned-S3 query strings so attachment URLs don't cause drift. CRLF → LF. Trailing whitespace stripped. Triple-newlines collapsed.
• Read-only types are stripped on push: created_time, last_edited_time, rollup, formula.
• notion_id is always 32-char undashed hex. Normalize at boundaries via url_to_id.
• Comments don't bump Last edited time. Use pull <file> (always fetches) when you want comments.
• query-database-view caps at 100 rows. Larger views truncate silently — pull <file> is the escape hatch for the tail.
• Empty list_rows is a no-op. Not "everything was deleted".
• OAuth refresh tokens are single-use. FileTokenStorage uses fcntl.flock so concurrent sessions don't race.
• create_row validates the parent. Rejected property bags silently produce orphan pages on Notion's side; create_row re-fetches and verifies the parent matches.

Practices

• frontmatter.py and manifest.py are pure. No IO outside their declared file.
• core.py's primitives take view_url as an argument; only the CLI reads the manifest.
• No imports inside functions. Module top only.
• Explicit over compact. Readable loops beat dense comprehensions.