Skip to content

Merging changes back ​

bash
pnpm merge:git [directory]            # report only — the default
pnpm merge:git [directory] --apply    # write the changes into the workspace
pnpm merge:git [directory] --propose  # open a proposal for each changed file instead

Edit an exported .md file in vim, Obsidian, or a colleague's editor, and bring it back — with the blocks keeping the identity and the authored dates they already had.

Why this is possible here ​

Merge-back is the frontier that block-core products decline to promise, and the reason is always the same: no base to merge against. Notesflow has one.

base    the export directory at refs/notesflow/export-base — what we last wrote
theirs  the files as they are now — whatever vim, Obsidian or a colleague did to them
ours    the live block tree

That makes it an ordinary three-way merge. The only new idea it needs is bookkeeping the export was already doing: it commits the files and marks the commit, the sidecar carries the block ids, and the op log applies ops.

It reports by default ​

This is the one command in the set that can overwrite writing nobody has read yet, so --apply is a deliberate act and everything else is a preview. Run it with no flag and you get a description of what would change:

Nothing was written. Re-run with --apply to merge these in,
or --propose to send them for review.

--propose instead of --apply ​

--propose opens a proposal for each changed file rather than writing it.

That exists because a file edited on somebody's laptop is exactly the case where the writer and the person who looks after the page are most likely to be different people, and --apply gives them no way to hand it over. It also needs only comment access — so somebody who may not edit a page can still bring their copy of it back for a decision.

Requirements ​

  • The target must be a git repository produced by pnpm export:git. Merge-back refuses a directory that is not one, and tells you to export first.
  • The server must be reachable; it checks /api/health before doing anything.
  • The base ref must exist. NOTESFLOW_EXPORT_BASE overrides which ref is used.

What survives the trip ​

Blocks keep their identity and their authored dates, so the timeline and provenance are unaffected by the file having been outside for a while. The edit that arrives is attributed to whoever ran the merge, at the moment they ran it — which is the truth, and is why --propose exists for when it should be somebody else's decision.

Blocks and the op log are canonical. Markdown is a projection. Git is a target.