← Writing

Set up repository metadata with dotrepo

Tutorial

Create a .repo file, validate its contents, and inspect the sources behind its answers.

protocolmetadatamcpdeveloper-tools

This guide covers local setup: create a .repo file, review its facts, and check what tools will read from it. Run the commands from your repository’s root directory.

1. Install dotrepo

This guide selects stable 1.0.3. Download the matching bundle from the 1.0.3 release, or install cargo install dotrepo-cli --version 1.0.3 --locked. Extract a bundle and put the binaries from bin/ on your PATH. The release-matched installation guide covers packages and source builds. Development main is a separate, unreleased 2.0.0-alpha.0 line.

2. Create and review the record

Choose one starting point. To create a .repo file from scratch:

dotrepo --root . init

To import an initial record from existing README.md, CODEOWNERS, and SECURITY.md content:

dotrepo --root . import

Open .repo and review the imported or starter values. Check the project description, build and test commands, ownership, and documentation links against your repository. Imported guesses need review before you treat them as maintainer-declared facts.

Once reviewed, keep those facts in .repo. If you choose to generate documentation from it, update the facts there and regenerate the affected files or managed sections.

3. Check the record and surrounding files

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 checks whether .repo is structurally valid.
  • query prints the selected build command without executing it.
  • trust shows the selected record, its sources, and any competing records.
  • doctor reports which supported files are generated, partly managed, or unmanaged, and identifies malformed managed sections.
  • generate --check checks whether generated files and managed sections agree with .repo.

Passing validation confirms the record’s structure. You still need to check that the returned build command describes the build you intend. If files have drifted, inspect doctor before deciding which files or sections dotrepo should manage. Existing handwritten documentation can remain unmanaged.

On a fresh record, generate --check can exit with code 2 because selected output does not exist yet. After reviewing the generation plan and choosing the files to manage, run dotrepo --root . generate, inspect its diff, then repeat the check. It should now exit successfully.

4. Inspect sources and conflicts

For a machine-readable report of record selection and conflicts, use:

dotrepo --root . trust --json

For the build command together with the context behind its selection, use:

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

Check which record was selected, where its values came from, and whether alternatives remain unresolved. A maintainer-declared command carries useful source information, but that declaration does not establish permission to execute it.

What you should have now

You should have a reviewed root .repo, successful validation, a build query that returns the intended command, and an explanation of the selected record’s sources and conflicts. Any files or sections you have chosen to generate should pass the drift check. If anything here disagrees with the reference docs, the docs win — and I’d like to hear about it: get in touch.

Publishing a claim to the public index is a separate workflow. Local setup does not submit or accept a claim. Follow the maintainer guide for claim preparation, submission, and review. The project page describes the current hosted service and its limits.

Related Project

View all →