# 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:

```bash
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](ingest-a-source.md)), with the same
questions and the same gate.

## Keeping it current

```bash
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:

```text
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. Run it again for the next one.
`raw capture --update` and `raw accept --replaces-bundle` are the commands underneath. What each one
does is in the [command reference](../reference/commands/raw-material-and-uploads.md).

## 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](export-guidelines.md) - sending the wiki's guidelines back into the same
  repositories.