Appearance
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 whichThe 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.mdcomes back asreadme.md.A folder's index file comes back beside the folder.
guide/index.mdis written asguide.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.mdin different folders becomefaq.mdandfaq-2.md.Links are relative
.mdpaths 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
journalDateandjournalPeriod.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
| Variable | Default | What it does |
|---|---|---|
NOTESFLOW_API | http://localhost:3211 | The API to read the workspace from |
NOTESFLOW_EXPORT_DIR | notesflow-export | Where to write, if no argument is given |
NOTESFLOW_EXPORT_MESSAGE | Export <timestamp> | The commit message |
NOTESFLOW_GIT_NAME / NOTESFLOW_GIT_EMAIL | git's own config | Who 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.