# Mark logs

A mark log is what was done with a [mark](/docs/marks) at one commit: its follower checked the commit or deployed it, or someone has something to say about it. It is free text, usually markdown, and optionally a link. Its first line is the headline; the rest (a summary, numbers, the end of a log) opens under it. A body over 64 KiB keeps its start and its end. A mark has one log per commit, and the next one there replaces it, so a follower's "checking" becomes "passed" and then "live".

```bash
oak mark log web                                          # web's logs, newest first
oak mark log web 3f2a8b1c                                 # its log at one commit, in full
oak mark log web --body "held: waiting on the migration"  # at the mark's commit
oak mark log web main --body-file notes.md                # `-` reads stdin
oak mark log web main --body "live" --url https://ops.example/deploys/7
```

Commits are `main`, a full hash, or a unique prefix; without one, a new log goes on the mark's commit. `oak mark log` takes `--repo OWNER/NAME` (default: the checkout's repository), `--server URL` and `--json`, and `-n` says how many logs to list. `--move-id ID` ties a log to one of the mark's moves; `oak mark follow` writes its "deploying", "live" and "failed" logs that way. While its script runs, the follower replaces its log every few seconds with the step, the elapsed time and the end of the output (see [Steps and progress](/docs/marks#steps-and-progress)); open pages showing it follow along without a reload. `oak mark moves` lists the mark's moves, each with the headline of the mark's log there.

Mark logs are written for the people and agents reading them, so there are no fixed states. Whether a commit passed something is the mark's move: a [mark's follower](/docs/marks#following-a-mark) moves the mark when its check passes, and says what went wrong in the mark's log when it fails.

## Where they show

A mark's page on the History tab lists the commits it has been at, each with the mark's log there. A commit's page lists every mark's log at that commit.

## Who can write one

Anyone who can write the repository writes mark logs, with a key that has the `write` scope. A mark's followers can also write its logs on its moves and checks with a read-only key, but never replace a log someone else wrote. Everyone who can read the repository reads them.

## API

| Request | What |
|---|---|
| `POST /api/:owner/:name/marks/:mark/logs` | Write one: `{"commit", "body", "url", "move_id"}` (`commit` defaults to the move's, then the mark's). A follower adds `progress` (`kind`, `state`, `step`, `steps`, `started_at`, `estimate_seconds`), which the mark's page and `…/marks/:mark/now` read |
| `GET /api/:owner/:name/marks/:mark/logs?limit=N&before=ID` | The mark's logs, newest first, with `next_before` for the next page; `commit=C` for its log at one commit. Each has `mark`, `commit`, `headline`, `body`, `url`, `move_id`, `author`, `updated_at` |
| `GET /api/:owner/:name/commits/:commit/logs` | Every mark's log at a commit: `commit`, and `logs` as above |
