# Refs and revisions

A ref is the address of one part of a file. A revision names the file and the way its refs were read. Together they let an edit change the part you read and nothing else.

The examples use [lease.docx](https://convert.dev/samples/lease.docx), a sample file you can download.

Set your key once. `lease.docx` is the sample.

```sh
export CV_API_KEY=cv_sk_…
```

## The refs view

A read with refs prints a file as text with a ref in front of every part an edit can aim at: a paragraph, a table and its cells, a slide and its shapes, a sheet's cells, a form field.

The view shows text the way an edit's `find` matches it, so what you read is what you aim at. Comments and tracked changes show as `>` lines after their part.

```sh
cv read lease.docx --scope p2-p5
```

```text
## [p2] Rent

[p3] The tenant pays the rent every month.

[p4] Rent is paid to the port office by the fifth day.

[t1]
| | A | B | C |
|---|---|---|---|
| 1 | Due | Amount | Paid to |
| 2 | Rent | 1,300 | Port office |
| 3 | Deposit | 2,600 | Port office |

[p5] Late payments carry a fee of 2% a month.
```

stderr:

```text
rev: 3f2a9c1b7d4e
```

In the API the view is a job's `refs`. `{"refs": {}}` asks for the whole view. Ask for it as `json` to get its units, each with its `ref` and its `text`.

## What a ref names

A ref is a position in the file as convert.dev reads it, not an id stored in the file. Read the same file again and you get the same refs.

| Format | Refs |
| --- | --- |
| Word | Paragraphs `p3`, and `h1/p1` and `f1/p2` in headers and footers. Tables `t1`, cells `t1!B2`, ranges `t1!B2:C4`, rows `t1!3:3`. Comments `c1`. |
| Spreadsheets | Cells `Sheet1!B3`, ranges `Sheet1!B3:D5`, rows `Sheet1!5:5`. `B3` alone is on the first sheet. |
| Presentations | Slides `s1`, shapes `s1/2`, their paragraphs `s1/2/p3`, table cells `s1/4!B2`, notes `s1/notes`. |
| PDF forms | Fields by name, such as `Name`. Pages `p1` and annotations `p1/a2`. |

Every ref also works as a scope. `--scope p2-p5` reads those parts, and a single ref shows the part that holds it. See [Read a big file](https://convert.dev/docs/read-big.md).

## What a revision is

Every read with refs gives the file's revision, `rev`, such as `3f2a9c1b7d4e`. `cv` prints it on stderr. In the API it is on each of the job's `inputs`.

A revision is a hash of two things: the file's bytes, and the way convert.dev reads refs from that format. It changes when either one changes, and the same file uploaded again, even after the first upload was deleted, gets the same revision.

So the same file can get a new revision after convert.dev changes how it reads that format. Refs from the old read may then point at other parts, and the revision is what tells the two reads apart.

## Why an edit needs one

A ref is only an address. `p5` in one file is another paragraph in another file, or in the same file after a paragraph was added above it.

So an edit that names a ref sends the revision of the read the ref came from. convert.dev checks it against the file before it changes anything. If they differ, nothing changes and the edit fails with `conflict`. Read the file again and take the refs from that read.

A revision covers the whole file, not one read. Every ref in one list of edits must come from the read whose revision you send.

An edit that only finds text, with no ref, needs no revision. The text says where it goes.

## When refs move

An edit that adds or removes parts moves the refs after them. Put a paragraph after `p3`, and the old `p4` becomes `p5`.

Its output comes with no revision, because a ref from the first read would hit another part of it. `cv edit` says the refs after it moved, and with `--json` its `rev` is `null`.

- To edit again, add the next edits to the same list and send it to the original file with its revision. `--json` gives that command in `try`.
- Or read the edited file and take every ref from that new read.

Do not mix the two. A ref you saw in the edited file points at another part of the original. An edit that changes text and adds or removes nothing keeps every ref in place, and its output has a revision for the next edit.

## Use them

- [Edit a file](https://convert.dev/docs/edit.md) goes through a read, an edit and a check, step by step.
- [Read a big file](https://convert.dev/docs/read-big.md) reads a long file one scope at a time.
- [See where the refs are](https://convert.dev/docs/refs.md) draws the refs on the pages of a PDF or the slides of a deck.
