export

rigger export <PROJECT> [--hub <DIR>] [--check] [--adopt] [--docs] [--json]
rigger export --all [--check] [--adopt] [--docs] [--json]
rigger export --line [--to <FILE>] [--check]

Generates a project’s hub from the record. The plan, the changelog and the diary are views of what the database holds, so this is the other half of import: the record is read once, written by hand no more, and the notes follow it.

Without --hub it writes the hub the record knows, and makes its directory when it is gone - that is the hub being written back. A directory named with --hub has to be there: a mistyped one would become the project’s hub.

$ rigger export sample --hub C:\dev\sample\hub
  План.md        written      357 bytes
  Изменения.md   written      258 bytes
  Дневник.md     written      156 bytes
  README.md      written      211 bytes

sample wrote 4 of 4 files.

Under --json a hub export prints the files it produced:

Field	Type	Meaning
project	string	The project’s name.
files	array	The files the export produced, in the order it wrote them.
files[]	object	One file.
files[].file	string	The file’s path in the hub, like План.md.
files[].bytes	integer	Its size in bytes.
files[].unchanged	boolean	Whether the file on disk already said exactly this.

What it writes, and what it never touches

File	Where it comes from
План.md	versions not yet shipped, their tasks, and the owner’s open questions
Изменения.md	versions that shipped, newest first, with what was written about each
Дневник.md	one entry per sitting, newest first
README.md	the prose a person wrote, with the “Состояние” block written from the state lines the record holds

Nothing else in the hub is generated. The vision, the prose of the decision log, the research notes and every other text are written by a person and stay that way - the record keeps them whole, so it never rebuilds them. Every generated file opens with a marker saying so:

<!-- generated by rigger; edits here are overwritten -->

Taking a handwritten file over

A hub that has been kept by hand for months is not overwritten because a command was typed. The first export refuses, and says which way out is which:

$ rigger export sample --hub C:\dev\sample\hub
error: C:\dev\sample\hub\План.md was written by hand and the record does not own it yet.
Check what would change with `--check`, then hand it over with `--adopt`.

--check writes nothing and reports what would change - it works on a handwritten hub for exactly that reason:

$ rigger export sample --hub C:\dev\sample\hub --check
  План.md        would change 357 bytes
  Изменения.md   would change 258 bytes
  Дневник.md     would change 156 bytes
  README.md      would change 211 bytes

4 of 4 files differ from the record.

--adopt hands the files over, once and on purpose. After that the record owns them and a plain export keeps them current.

The handwritten texts

--docs also writes the documents back out: Видение.md, Ритуалы.md, one file per research note under Исследования/, and every other text import took in, each at the path it was read from - so that import reads it back to the same place. And the files that are not texts, byte for byte, each where it lay; under --json each is one more entry of files.

They are off by default because they are a cache and nothing reads them back: the record is where they live now, and writing four more files into every hub on every export would put them in every diff for no one’s benefit. They carry no generated mark either - they are your prose, and a mark saying “edits here are overwritten” would be a lie, since import takes an edit back in.

doctor --hubs compares them to the record and says when somebody has written in one:

$ rigger doctor --hubs
hubs the record cannot vouch for (1):
  rigger       Видение.md     edited since the record wrote it; `rigger import` takes the edit in

A text the hub already has and that says what the record says is noted as such by every export, with or without --docs, so that a later edit to it reads as an edit.

A text the record holds without a file - written through doc add or an assistant’s tool - goes where the hub already keeps the same words, when some file there says exactly that and belongs to no other text; otherwise under a name made from its title. Either way the record then knows the file, and the next import finds the text by it. Before v0.31.0 the name was made up on every export, beside any file that already held the text, and the next import took it in as a second document.

What the record remembers of each file

Each file an export writes - or finds already saying what the record says - is noted in the record by a digest of its text. That note is what tells a file the record has merely moved past from one somebody has written in: the first is still exactly what the record last wrote, the second is not. doctor --hubs reports the two apart, the end of every session writes the first kind again by itself, and import does not read the first kind back - it is the record as it stood at that export, and reading it would undo what the record has learnt since.

Seeing what would change

--check writes nothing and shows the lines that differ, - for what the file has and + for what would replace it:

$ rigger export demo --check --hub ./hub
  План.md        would change 102 bytes
  Изменения.md   unchanged    57 bytes

План.md:
      - [ ] first
    -
    - Рукописная строка, которую экспорт снесёт.

1 of 4 files differ from the record.

Naming the file alone was no use when the question is whether something written by hand is about to be thrown away. The answer is in the - lines: those are what the file has and the record does not.

Running it twice

An export of an unchanged record writes nothing and says so, byte for byte:

$ rigger export sample --hub C:\dev\sample\hub
  План.md        unchanged    357 bytes
  Изменения.md   unchanged    258 bytes
  Дневник.md     unchanged    156 bytes

C:\dev\sample\hub is already what the record says.

That stability is a test, not a hope: the same record generates the same bytes, and a file is rewritten only when the record behind it changed.

--all: every hub, back where it lay

--all writes every hub the record knows, each at the place the record says it lies - the retired projects’ and the line’s own place among them - and makes the directory of any that is gone. It is what makes the hubs a cache rather than a second copy: with --docs, a deleted directory of hubs comes back whole.

$ rigger export --all --docs
  alpha    wrote 14 of 14 files - the directory was gone and is made again
  attic    wrote 9 of 9 files - the directory was gone and is made again
  line     wrote 52 of 52 files - the directory was gone and is made again

Wrote 75 files across 3 hubs.

A file kept by hand in any of them refuses the whole run before a single file is written - half a line written and half refused is a state nobody asked for - and --adopt hands them all over at once. The line’s own place gets its texts and files and nothing else: it plans nothing, and a plan of nothing would be four empty files above every hub.

Two files of a hub do not come back, because they are not views: the decisions journal Решения.md and the wishes file Хотелки.md are inputs the record has taken in - each entry an event, each wish a wish, the journal’s preamble a document. doctor --hubs vouches for them only when every one of their entries is in the record.

Under --json:

Field	Type	Meaning
hubs	array	Every hub written, by project name.
hubs[]	object	One hub.
hubs[].project	string	The project’s name.
hubs[].hub	string	Where it was written.
hubs[].made	boolean	Whether its directory was gone and was made.
hubs[].files	array	The files written, as for one hub.
hubs[].files[]	object	One file.
hubs[].files[].file	string	The file’s path in the hub.
hubs[].files[].bytes	integer	Its size in bytes.
hubs[].files[].unchanged	boolean	Whether the file on disk already said exactly this.

What the record keeps so a hub survives the trip

A hub is prose with structure in it, and most of what a person wrote is neither a version number nor a task. So the record keeps the shape as well as the substance: the heading exactly as it was written, how deep it sat, which block it belonged to, the order its stages had, the prose written before a task list and the prose written after it, the marker a question list used, and the blank lines a hub leaves around its rules. Guessing any of these rewrites a real file on every run.

The line ending is the file’s own. Every hub written on Windows is CRLF, and a generated file in LF would differ from its source on every single line - which is not a diff anybody reads. The record itself keeps LF, whatever a text came in with: a document read from a CRLF file used to keep its carriage returns, and the export, converting the endings of the file it wrote, put each one back as \r\r\n. Schema 30 took them out of what the record already held.

--line: the public registry

Every generator on a line needs the same list - which products exist, what each one’s mark and colour are, what shape of thing it is, where to read about it. --line writes it as JSON, from the same record:

$ rigger export --line --to ..\line\line.json
Wrote ..\line\line.json - 18 products

{
  "generator": "rigger",
  "version": "0.33.0",
  "products": [
    {
      "name": "sample",
      "about": "A sample product",
      "mark": "sa",
      "accent": "#3FA873",
      "form": "cli",
      "repository": "https://github.com/example/sample.git",
      "docs": "https://example.github.io/sample/"
    }
  ]
}

The fields come from project mark and from the repository itself. A product recorded before its mark was drawn is still published, with those fields simply absent - leaving it out would make the registry disagree with the record about what exists, which is the fault this command fixes. Without --to the JSON goes to standard output.

With --to and --json, it prints what was written instead of the registry:

Field	Type	Meaning
path	string	The file named by --to.
product_count	integer	How many products the registry holds.
changed	boolean	Whether the registry differs from what the file held.
written	boolean	Whether the file was written.

Without --to the registry itself is the output; its products leave out any field the record does not have (about among them):

Field	Type	Meaning
generator	string	What wrote the registry: always rigger.
version	string	The rigger version that wrote it.
products	array	The line’s products, sorted by name.
products[]	object	One product.
products[].name	string	The project’s name.
products[].about	string	What the product is, in one line read from its manifest; left out when none says.
products[].mark	string	The product’s monogram.
products[].accent	string	The mark’s colour, #RRGGBB.
products[].accent2	string	The second colour, for a mark drawn as a pair. Absent when there is none.
products[].form	string	What shape of thing it is: cli, desktop, web, library or service.
products[].repository	string	The repository’s https:// address.
products[].docs	string	The documentation’s https:// address.

What it will not publish

The record holds paths on a machine, the hubs in a notes vault, the stages of unreleased work and the questions waiting for an owner. This command writes into a public repository, so the one mistake it can make is the one that cannot be taken back.

The rendered file is therefore checked before it is written, every time, rather than reviewed by whoever remembers to: a drive letter, a UNC prefix or a home directory anywhere in it refuses the write, as does a repository or documentation address that is not https://. The check reads the finished JSON rather than the fields it knows about, because the field that leaks will be the one added after the check was written.

Related

• import - the other half: a hub read into the record.
• doctor - --hubs names a file somebody has written in since the record did, apart from a file that is only behind.
• project - project mark records what --line publishes.