# wiki bless

_record that a picture is still true_

**Intent.** wiki bless exists so that a person who has looked at a picture whose subject changed can clear the check, and leave a record of why. It should never clear a picture without a reason.

`wiki bless` records a picture's current fingerprint, and the reason it is still true, in the picture
record.[^bless] When a picture needs it is described on [Pictures](../../checks/pictures/index.md), and every key
of the record on [PICTURES.toml](../../pictures-toml/index.md).

## Usage

Both arguments are required, and a reason with spaces is quoted.[^usage]
```sh
wiki bless [-h] [--root ROOT] [--wiki WIKI] PICTURE REASON
wiki bless refund-flow.svg "the arrows still match the code"
```

## Arguments

| Argument | Meaning |
|---|---|
| `PICTURE` | the picture's file name, as its record names it[^usage] |
| `REASON` | why the picture is still true, which cannot be empty[^exit] |

## Output

It prints the picture and the reason it recorded.[^bless]
```text
wiki: refund-flow.svg blessed -- the arrows still match the code
```

**It rewrites the whole of `PICTURES.toml`**: every comment becomes the tool's own header, any key other
than `made`, `digest`, `depicts` and `blessed` is dropped, and an earlier reason is replaced.[^ledger]

## Exit codes

| Code | Condition | Message |
|---|---|---|
| `0` | the blessing is recorded[^exit] | `wiki: refund-flow.svg blessed -- the arrows still match the code` |
| `1` | the picture has no record[^exit] | `wiki: missing.png has no entry in PICTURES.toml` |
| `1` | the reason is empty[^exit] | `wiki: a blessing needs a reason; it is the record that the picture was looked at` |
| `1` | the record names a path that is not in the project[^exit] | `wiki: a picture says it shows src/gone.py, which is not in this project` |
| `1` | the record names a folder holding no files[^exit] | `wiki: a picture says it shows src/empty, which holds no files` |
| `2` | an argument is missing[^exit] | `wiki bless: error: the following arguments are required: REASON` |
| `2` | an option it does not know[^exit] | `wiki: error: unrecognized arguments: --unknown` |
| `2` | there is no wiki where it was pointed[^nowiki] | `wiki: no wiki at nowhere` |

[^bless]: `src/builder/build.py` — `bless()` writes `digest` and `blessed` through `write_ledger()`, and
    returns the line `run()` prints.
[^usage]: `src/builder/cli.py` — `main()` gives `bless` the positional `picture` and `reason`, each read
    as one argument.
[^ledger]: `src/builder/build.py` — `write_ledger()` writes its own header and, for each picture, only
    `made`, `digest`, `depicts` and `blessed`.
[^exit]: `src/builder/build.py` — `bless()` raises `WikiError` for an unrecorded picture or an empty
    reason, and `subject_digest()` for a missing path or an empty folder; `src/builder/cli.py` — `main()`
    returns 1 for it, and argparse exits 2 on a missing argument or an option it does not know.
[^nowiki]: `src/builder/cli.py` — `main()` prints `no wiki at` and the path, and returns 2, when the wiki
    folder does not exist.