Skip to content

Exporting to git ​

bash
pnpm export:git [target-directory]

Writes the whole workspace as real Markdown files into a git repository and commits them. The server must be running — the export reads the workspace over the API.

Default target: notesflow-export, or NOTESFLOW_EXPORT_DIR.

What you get ​

field-notes.md                    a page, with its properties as YAML frontmatter
projects.md                       a page with pages inside it…
projects/bridge.md                …which are written in a folder named for it
projects/tasks.md                 a database view, as a real GFM table
bases/open-tasks.base.yaml        that view's query: scope, filters, columns, sort
.notesflow/*.ids.json             the sidecar: which block is which

The page tree becomes folders. A page with pages inside it is written beside its folder — projects.md next to projects/ — the "folder note" layout, which Notesflow reads back as that folder's page when the export is imported again. Every link is relative to the file it is in, so a page three folders down links to the top as ../../../readme.md.

Bringing a docs repository in and out again ​

Pages imported from a folder of Markdown keep their file names as their slugs, so an export writes them back where they came from: a pilot import of this project's own 66 docs files exported 56 of them to exactly their original paths. The rest differ in three known ways:

  • Names are lower case. README.md comes back as readme.md.

  • A folder's index file comes back beside the folder. guide/index.md is written as guide.md; imported again, either form is the folder's page.

  • A name is unique across the workspace, not per folder. Slugs are how links and merge-back know which page a file is, so two faq.md in different folders become faq.md and faq-2.md.

  • Links are relative .md paths built from slugs. No identifier appears in any link target, so every link works in any Markdown editor.

  • Properties are real frontmatter, because properties are constrained to be frontmatter-shaped in the first place. A journal's day and a week's or month's note's period are written there too, as journalDate and journalPeriod.

  • A task's fields are Dataview's inline fields at the end of its line, such as - [ ] Send the report [due:: 2026-11-06], so Obsidian reads them as it reads its own.

  • Attachments are written out alongside the pages that reference them.

  • The sidecar in .notesflow/ carries block identity. Identity never appears in the document body — it travels beside it, which is what makes the round trip lossless modulo block identity by design rather than by luck.

It is deterministic ​

Exporting an unchanged workspace produces an unchanged tree, so a repository of exports has a history of real edits rather than a history of export runs. The command tells you when there is nothing to do:

No changes since the last export. notesflow-export is up to date.

It also removes files for pages that no longer exist, and says how many.

Marking the base ​

Every export moves a git ref — refs/notesflow/export-base — to the commit it just wrote.

That mark is what makes merge-back an ordinary three-way merge rather than guesswork: it is the record of exactly what Notesflow last wrote, which is the base both sides diverged from.

Settings ​

VariableDefaultWhat it does
NOTESFLOW_APIhttp://localhost:3211The API to read the workspace from
NOTESFLOW_EXPORT_DIRnotesflow-exportWhere to write, if no argument is given
NOTESFLOW_EXPORT_MESSAGEExport <timestamp>The commit message
NOTESFLOW_GIT_NAME / NOTESFLOW_GIT_EMAILgit's own configWho the commit is by

What this is good for ​

A workspace that is greppable, readable in vim, publishable by a static-site generator, and checkable by CI. None of those needs the traffic to flow back — which is why mirroring is worth having even before merge-back is in the picture.

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