# `mix surfex.relate`
[🔗](https://github.com/dcoai/surfex/blob/v0.6.2/lib/mix/tasks/surfex.relate.ex#L1)

Records a relation between two scanned ids, at their current hashes
(`Surfex.Record.relate/6`).

    mix surfex.relate "spec.md#Carts/Adding items" MyApp.Cart.add/2 --type implements
    mix surfex.relate MyApp.Cart.add/2 MyApp.Cart.Line.new/1 --type depends_on --note "builds a line"

For a directed type (`depends_on`, `refines`, `tests`) the order is from → to. Prefix
an id with `spec:` or `code:` when it is scanned as both. The entry supersedes the
relation's current judgement, if it has one.

Naming a pair validates nothing (§18). An `implements` or `excuses` relation is recorded
as proposed. A `verifies` relation is recorded on the test's failing run when the last
`mix test` saw its current version fail, and as proposed otherwise.

`--planned` relates a scanned id to one that doesn't exist yet (`Surfex.Record.plan/7`):
the section is written and the code isn't, or the other way round.

    mix surfex.relate --planned "spec.md#Carts/Adding items" MyApp.Cart.add/2 --type implements

The relation is planned until the id is scanned, then dangling until you confirm it. An
id that couldn't be this project's (a spec file the scanner doesn't read, a code name
outside the project's namespaces) is refused as a likely typo.

---

*Consult [api-reference.md](api-reference.md) for complete listing*