Claim Your Repo with dotrepo

If you maintain a repository and want to adopt dotrepo, the shortest path is not to learn the whole protocol first.

The shortest path is to do three things:

• start a canonical root .repo
• run the maintainer loop locally until the answers look right
• line that canonical record up with the public story for your repository

That is the real “claim your repo” path.

1. Install the Toolchain You Intend to Use

The intended install surface in v1.0.0 is the release bundle, not a pile of ad hoc local binaries.

Download the latest platform bundle from the GitHub Releases page, extract it, and put dotrepo, dotrepo-lsp, and dotrepo-mcp on your PATH.

If you are just exploring, a local source build is fine. But if you are trying to adopt dotrepo in a real repository, it is better to start from the same shipped toolchain the project treats as canonical.

2. Start the Canonical Record

There are two honest starting points:

dotrepo --root . init

if you want to author a canonical .repo from scratch, or:

dotrepo --root . import

if you want to bootstrap from existing README.md, CODEOWNERS, and SECURITY.md content first.

The important thing is what happens after that first step. Once the root .repo exists, treat it as the source of truth. Compatibility surfaces can still be generated or managed, but they should stop being the primary editing surface.

3. Run the Maintainer Loop

The core local loop is short on purpose:

dotrepo --root . validate
dotrepo --root . query repo.build --raw
dotrepo --root . trust
dotrepo --root . doctor
dotrepo --root . generate --check

Each command answers a different question:

• validate tells you whether the current .repo is structurally valid
• query tells you what a machine actually sees for one field
• trust tells you why that answer should be believed
• doctor tells you what state your surrounding conventional files are in
• generate --check tells you whether managed or generated surfaces have drifted

That last point matters. A metadata system only becomes useful in practice when it can keep the public answers, the local record, and the compatibility surfaces from slowly drifting apart.

4. Use trust Before You Trust the Story

The biggest mistake would be to treat dotrepo as a prettier manifest and ignore the trust surface.

If you only run validate, you know the record parses. You do not know whether the answer you are about to expose is canonical, inferred, imported, or competing with another visible record.

That is what trust is for.

If you need the same decision in a machine-readable form, use:

dotrepo --root . trust --json

And if you need one field together with selection context rather than a bare scalar, use:

dotrepo --root . query repo.build --json

The project is much more useful once you stop asking only “what value came back?” and start asking “why did this value win?“

5. Claim the Public Story

Local adoption is only half the point.

The other half is making sure the public story for your repository is aligned with the maintainer-controlled one. That is where the hosted surface and the claim model matter.

If a reviewed overlay already exists for your repository, the goal is not to pretend it never existed. The goal is to move the trust story forward from “reviewed public record” toward “maintainer-controlled canonical record” without losing provenance about how that handoff happened.

The ries-rs example in the v1.0.0 release is useful because it shows that path in public: a repository can be visible through the index first, and then a live accepted maintainer claim can tighten the authority story around it.

That is a much healthier model than waiting for universal adoption before anything becomes visible.

6. What Success Looks Like

At the end of the short path, you should have:

• a root .repo you are willing to treat as canonical
• stable answers from query
• explicit trust and conflict visibility from trust
• compatibility surfaces that do not drift silently
• a public story that is moving toward maintainer-controlled truth instead of away from it

That is enough to make dotrepo real in one repository without turning adoption into a thesis project.

If you want the underlying project context, start with the dotrepo project page. If you want the current maintainer contract in the upstream repo, the two most useful docs are the README quick start and the maintainer happy path.