Appearance
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 insteadEdit 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 treeThat 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/healthbefore doing anything. - The base ref must exist.
NOTESFLOW_EXPORT_BASEoverrides 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.