> For the complete documentation index, see [llms.txt](https://ascribed-dev.com/docs/llms.txt). This documentation describes Ascribe 0.4.5. Anything marked in main, not yet released isn't in that release yet. # `ascribe addresses` > Reference · Keep ascribe.addresses: make it, record a move or a retired address, and list the redirects each build writes, with each command's options and output. `ascribe addresses` keeps `ascribe.addresses`, the record of where the addresses the docs published went: it makes the file, records a move or a retired address, and lists the redirects each build writes. [Keep the addresses you've published](https://ascribed-dev.com/docs/publishing/redirects.md) is the task the commands are used in. The options every command accepts are in the [command reference](https://ascribed-dev.com/docs/command.md#options-every-command-accepts). ## `ascribe addresses` Keeps `ascribe.addresses`. Each takes `--format json`, and writes the document its [schema](https://ascribed-dev.com/docs/contracts/json-reports/addresses.md#ascribe-addresses-init) describes. Each exits with `0` when it's done, and `2` when it couldn't run: the project doesn't load, or the file can't be read or written. ### `ascribe addresses init` Makes `ascribe.addresses`, with its header, its `version`, and empty tables. A file already there is left as it is, and it says so. In a project whose `ascribe.toml` still has `[permalinks]`, from before `ascribe.addresses` recorded [permalinks](https://ascribed-dev.com/docs/glossary.md#permalink), it moves the table's entries into the file, made or already there, and takes the table out of `ascribe.toml`, keeping the rest of the file as written. Each of `[permalinks.retired]` goes in `[retired]` as `go:`, or in `[moved]` to its `to` when it has one. Each of `[permalinks.aliases]` goes in `[moved]` as `go:`, leading to `go:` and the name it leads to. Run `ascribe permalinks sync` after, when the project has `ascribe.permalinks`. A base whose `ascribe.toml` still has the table is read as if it had been moved, so the move itself loses no address. - `--dry-run`: Say what it would change, and change nothing. - `--force`: Change files even when git couldn't put them back as they are: ones with changes not committed, ones git doesn't track, or ones in no repository. - `--format `: How to show what was done. - `text` (the default): Short text, for people and agents to read. - `json`: One JSON document, for tools. ### `ascribe addresses move` Records that a page, or a heading's id, moved, after a move made without Ascribe, as with `git mv`. The old path is gone; the new one is a page of the project, or a heading on one. A permalink no heading declares any more, `go:`, moves to a page or a heading, or to another permalink, `go:`. ```console $ ascribe addresses move guides/keys.md security/keys.md Recorded in ascribe.addresses: guides/keys.md moved to security/keys.md. ``` Each page's path is from the current folder or from the content root, and the entry is from the content root. So, from a repository's root whose project is in `docs/` with its content in `docs/content/`, `ascribe addresses move --config docs docs/content/guides/keys.md docs/content/security/keys.md` records the same entry, and so does `ascribe addresses retire` given such a path. **`--from-git`** records every move git sees between the base and the working tree whose old path is gone, one entry for each page, so a reorganization made with `git mv` is recorded at once. The base is chosen as `ascribe check` chooses it, with `--base` and `--base-exact`. Git sees a file that's renamed and added, as `git mv` leaves it, and only when the old and new files are mostly the same: a page rewritten as it moved is forwarded with `ascribe addresses move `. ```console $ ascribe addresses move --from-git Recorded 1 move git sees: guides/setup.md → start/setup.md. ``` - `[OLD]`: Where it was: a page's path, from the current folder or from the content root; a file's path, `#`, and a heading's id; an address from the host's root, starting with `/`, from before the project used Ascribe; or a permalink, `go:`, nothing declares now. - `[NEW]`: Where it is now: a page's path, from the current folder or from the content root, and optionally `#` and a heading's id; or, for a permalink, another permalink, `go:`. - `--from-git`: Record every move git sees between the base and the working tree whose old path is gone, one entry for each page, as after a reorganization made with `git mv`. Git sees a file renamed and added, and only when the old and new files are mostly the same. - `--base `: With `--from-git`, the revision git's renames are seen from: anything git accepts. By default, the repository's default branch, from its merge base with `HEAD`, as `ascribe check` chooses it. - `--base-exact`: With `--from-git`, see the renames from the base revision itself instead of its merge base with `HEAD`. - `--dry-run`: Say what it would change, and change nothing. - `--force`: Change files even when git couldn't put them back as they are: ones with changes not committed, ones git doesn't track, or ones in no repository. - `--format `: How to show what was recorded. - `text` (the default): Short text, for people and agents to read. - `json`: One JSON document, for tools. ### `ascribe addresses retire` Records that a page, or a heading's id, or a permalink, `go:`, was removed on purpose, with the reason, which is for whoever reads the file later. ```console $ ascribe addresses retire reference/legacy-sync.md --reason "The sync agent was removed in 4.0" Recorded in ascribe.addresses: reference/legacy-sync.md was retired. ``` - `OLD`: What was removed: a page's path, from the current folder or from the content root; a file's path, `#`, and a heading's id; an address from the host's root, starting with `/`; or a permalink, `go:`, nothing declares now. - `--reason `: Why it was removed. - `--dry-run`: Say what it would change, and change nothing. - `--force`: Change files even when git couldn't put them back as they are: ones with changes not committed, ones git doesn't track, or ones in no repository. - `--format `: How to show what was recorded. - `text` (the default): Short text, for people and agents to read. - `json`: One JSON document, for tools. ### `ascribe addresses list` Shows the redirects and retired addresses each build writes, as its `_ascribe/redirects.json` has them, and the entry of `ascribe.addresses` each comes from. It changes nothing. - `--build `: Show only this build. By default, every build in `ascribe.toml`. - `--format `: How to show the redirects. - `text` (the default): Short text, for people and agents to read. - `json`: One JSON document, for tools. ## See also - [Keep the addresses you've published](https://ascribed-dev.com/docs/publishing/redirects.md): what the check reports, how to fix a lost address, and what the build writes.