chemenu/docs/how-to/capture-repository-docs.md

Capture documentation from a git repository

Documentation that lives in a git repository is captured, not copied by hand. A capture records the repository, the ref rule and the commit it came from. Later, the wiki can tell which captured material has fallen behind its repository, and take in the new edition as a whole.

What you prepare

Access to the repository from this machine. Git uses your own keys and credential helpers, and nothing is stored in the instance. Then decide three things:

• the repository URL;
• the ref to follow, usually a branch such as main;
• which files count, as a glob, for example docs/**/*.md.

Taking a repository in for the first time

You can run the capture yourself, or name the three values to the agent and let it run the command:

tools/wikitool raw capture <repo-url> --ref main --path 'docs/**/*.md' --name <bundle>

This writes the matching files, byte for byte, into incoming/<bundle>/, together with a _capture.json manifest naming the repository, the ref rule and the commit. From there it is an ordinary source: Ingest incoming/<bundle> (Ingest a source), with the same questions and the same gate.

Keeping it current

tools/wikitool raw status

This lists every captured bundle that has fallen behind its repository, file by file, marking each file as added, modified or deleted. It only reads.

To bring them in, say:

Update the captured repositories

The agent checks every captured bundle. It takes one changed bundle per run into the wiki, replacing the old edition as a whole, and tells you how many are still behind. For the next one, /clear and say it again - each bundle is a run of its own in a fresh context. raw capture --update and raw accept --replaces-bundle are the commands underneath. What each one does is in the command reference.

Where the agent stops

The same places as any ingest: the fidelity/authority questions, the discussion of what matters, and the Mass-Update Gate when it publishes. When one repository cannot be reached, the agent reports the error and carries on with the others. A failure in one never stops the run.

Related

• Export guidelines - sending the wiki's guidelines back into the same repositories.