Configuration and monorepo targets

Quarry keeps its configuration in .quarry/.config at the source Git worktree root. Despite the filename, it is a JSON document, not an environment file or TOML. Commit it with .quarry/.gitignore so other developers and CI share the same link and target definitions.

Complete configuration shape#

Illustrative configuration:

{
  "default_branch": "main",
  "docs_dir": "docs/capstone",
  "permalink_template": null,
  "targets": [
    {"name": "billing", "docs_dir": "services/billing/docs/capstone"},
    {"name": "orders", "docs_dir": "services/orders/docs/capstone"}
  ],
  "sync_on_read": true,
  "url": "git@github.com:acme/docs-quarry.git"
}

Key	Type and default	Meaning
`url`	Required string	Shared docs repository clone/push URL. Prefer the `.git` suffix with the bundled GitHub workflow.
`docs_dir`	Required string in stored JSON; `init` defaults to `docs/capstone`	Source docs directory relative to the source root. With targets, also the optional umbrella docs directory.
`default_branch`	Required string in stored JSON; derived by `init`	Source remote branch whose reachable commits may be imported. It is not the branch of the shared docs clone.
`permalink_template`	Optional string or `null`; defaults to `null`	Override source-pointer URLs; configured by editing JSON.
`targets`	Optional array, defaults to empty	Independently imported docs directories with their own shared-repo folder names.
`sync_on_read`	Optional Boolean, defaults to `false`	Attempt a docs-clone refresh before queries and `check`. Edit JSON to enable it.

init pretty-prints JSON and appends a newline. It always emits permalink_template, including null; empty targets and false sync_on_read are omitted. The current struct serialization order is default_branch, docs_dir, permalink_template, optional targets, optional sync_on_read, url.

Unknown keys are ignored on load and are lost when init rewrites the config. Missing required fields or incorrect JSON types fail loading. A malformed config can prevent any non-help command from running; correct the JSON directly before retrying init.

Flags and environment precedence#

The init options are:

quarry init [--url URL] [--docs-dir DIR] [--name NAME]
            [--default-branch BRANCH] [--force]

Option	Environment equivalent	Effect
`--url`	`QUARRY_DOCS_REPO`	Choose or relink the docs repository.
`--docs-dir`	`QUARRY_DOCS_DIR`	Set the root docs directory, or the named target's directory when `--name` is present.
`--default-branch`	`QUARRY_DEFAULT_BRANCH`	Set source ancestry eligibility branch.
`--name`	None	Add a target or update the existing target with that name; requires a docs-dir input.
`--force`	None	Permit changing to a different docs URL.

For these init fields, precedence is explicit flag → environment → existing configuration → derived/default value. Environment variables can override an existing config on a later init; they are not limited to first-time setup. Ordinary add, update, check, and docs commands do not read these environment variables as replacement config values.

Input strings pass through trimming; empty values become absent. The default-branch derivation first checks refs/remotes/origin/HEAD, then asks git ls-remote --symref origin HEAD, then tries existing origin/main, origin/master, origin/trunk, and origin/develop, finally falling back to main. A saved branch survives later initialization unless overridden.

If neither a URL input nor an existing config is available, terminal stdin triggers Docs repo URL: . With nonterminal stdin the command refuses and explains --url/QUARRY_DOCS_REPO. Provide the URL or commit config for automation; --json does not itself disable the terminal prompt.

Global read policy#

quarry --sync docs list
quarry --offline docs list

--sync forces a refresh attempt before reads. --offline suppresses that attempt even with sync_on_read: true. They conflict with each other. Without either, sync_on_read decides.

This policy applies to check and docs queries except docs index. docs index always stays local. The flags are accepted globally, but --offline does not stop the explicit sync command or the network operations performed by init, add, update, and remove.

Identity and ownership#

A source repository's default folder name is the final path component of its origin URL, with .git removed; its case is preserved. It is not configurable as a single-repository display name. --name defines a monorepo target instead.

For git@github.com:Acme/Record-Store.git, the folder is Record-Store and the normalized ownership origin is github.com/acme/record-store. The owner is the penultimate URL path component. For nested GitLab groups, this implementation therefore keeps only the final group as owner, a limitation that matters for ownership and default source URLs. See Implementation details.

The shared clone's folder name comes from the last component of the docs URL. Linking to git@github.com:acme/docs-quarry.git creates .quarry/docs-quarry/.

Register targets#

quarry init --url git@github.com:acme/docs-quarry.git \
  --name billing --docs-dir services/billing/docs/capstone
quarry init --name orders --docs-dir services/orders/docs/capstone

Each call adds or replaces one target entry. init sorts targets by name. Calling it again without --name preserves targets; --docs-dir without --name changes the root docs directory.

After committing the config/docs and merging them to the source default branch:

quarry add --strict
quarry docs show billing
quarry docs deps orders --upstream

add, update, remove, and check operate on all configured targets. There is no per-command --target selector and no init --remove-target option. One target without an umbrella still changes add, update, and remove JSON result into an array. check keeps an object and includes target on contract and break rows.

Valid names and paths#

A target name must be a nonempty single path segment. It cannot be ., .., contain / or \, equal the source repo's own name, or equal root-owned 00-index.md or observed-edges.json.

Docs paths must be nonempty relative paths inside the source repository. Absolute paths, leading separators, Windows drive/UNC forms, and any .. path component using either separator are refused. The normalizer trims surrounding whitespace and trailing /, then removes one leading ./.

Two targets cannot share a name or normalized docs path. A target docs path cannot equal the root docs path. Targets cannot nest inside one another. A target may sit inside the root docs directory; the umbrella copy then omits that subtree to prevent duplication.

Use conventional forward-slash paths and ordinary directory names. Validation is not a complete cross-platform filesystem-name validator. Hand-edited configs are validated by init and target-consuming operations; config loading itself only deserializes JSON.

Optional umbrella folder#

When targets exist and the root docs_dir/00-index.md exists in the working tree, Quarry also imports the root docs folder under the source repo's own name. It imports all its files except target subtrees; it is not restricted to copying only 00-index.md.

In the umbrella's 00-index.md, supported inline links into configured target docs are rewritten to sibling folders:

[Billing](../../services/billing/docs/capstone/00-index.md#overview)

becomes, illustratively:

[Billing](../billing/00-index.md#overview)

The resolver tries a path relative to the root docs directory, then the path as written from the source root. It preserves fragments and supported quoted link titles, leaves reference-style link definitions alone, and skips fenced code/frontmatter.

Adding a new target can cause an existing umbrella to be rebuilt even at the same source commit: its links depend on the configured/imported target set. A newly registered target needs quarry add; update refuses any configured folder that is not yet registered.

With no root index, the umbrella is omitted from imports. Removing the root index does not automatically delete a previously imported umbrella folder. check always skips the umbrella.

Moving, renaming, and retiring targets#

A stamp claims a folder for a normalized source origin and a docs directory. Changing billing from services/billing/docs/capstone to another directory in config alone does not transfer ownership; the next import refuses the existing stamp. update --force does not bypass this check.

Retirement is explicit. quarry remove removes every currently configured target, so it is not a single-target retirement command. For a planned whole-repo relayout, remove the old configured set first, change and commit the config, then add the new set. For a selective target retirement, maintainers can make a reviewed change in a separate shared-repository clone, deleting the obsolete folder and updating the root catalog, then remove the target from source config. Coordinate its remaining edges and CI before doing so.

Deleting an entry from targets does not garbage-collect that target's old shared folder. Renaming a target can leave both old and new folders until the old one is explicitly removed.

Relink a repository#

quarry init --url git@github.com:acme/new-docs.git --force

URL comparison is literal: changing an SSH spelling to HTTPS can require --force even when they address the same remote. Relinking deletes the previous managed clone, rewrites config/ignore files, clones the new URL, and rebuilds. It does not migrate old imported folders into the new remote. If cloning fails, config may already point to the new URL; resolve credentials or URL, then rerun init.

Source basis#

Verified against Quarry 0.2.0, source revision 78c71fa. src/config.rs src/cli.rs src/context.rs src/identity.rs src/commands.rs src/importer.rs tests/s12_init.rs tests/s17_targets.rs