ingest

What It Does

ingest scans supported documents, writes embeddings and records into the canonical store, and produces a snapshot manifest bound to the current commit.

Admission control runs before persistence. Implicit selectors (--all, --since, managed hook-triggered ingest) follow the configured document surface, while explicit selectors (--files, --path, JSON paths[]) may bypass include rules but never bypass admission checks.

When To Use / When Not To Use

When to use it

If you are onboarding a new project, read Getting Started first, then run ingest after init.
You added or changed project docs and want retrieval to see them.
You promoted durable memory into docs/memory/**.
You want to preview which files would be indexed before running a real mutation.

When not to use it

You only need to search existing indexed data. Use query.
You only need the current working state. Use memory recall.

Syntax

pnpm ragit ingest \
  [--all | --since <sha> | --files <glob> | --input <path|->] \
  [--dry-run] [--format text|json|both]

Arguments And Options

--all: Index all supported repository documents.
--since <sha>: Index only changes since a commit.
--files <glob>: Index a targeted glob.
--input <path|->: Provide a structured JSON payload instead of flags.
--dry-run: Validate inputs and compute the plan without writing the store or manifest.
--format text|json|both: Choose the result envelope form.
--cwd <path>: Run against another repository.

Input And Output Contract

Human mode normally uses --all, --since, or --files.
Agent mode should prefer --input <path|-> when multiple selectors are involved.

{
  "all": false,
  "since": "HEAD~1",
  "files": "docs/**/*.md"
}

JSON output reports mode, processed, skipped, masked, commitSha, manifestPath, plannedFiles, deletedDocumentIds, and admission.
--dry-run returns the same planned surface without mutating the store.
In security.admission_mode=enforce, blocked implicit candidates are skipped while blocked explicit candidates fail apply.

Examples

Human terminal flow:

pnpm ragit ingest --all --format both

Agent-oriented flow:

pnpm ragit ingest --input ingest.json --dry-run --format json

Failures And Cautions

Do not mix --input with selector flags in the same call.
Invalid globs and unsafe path patterns are rejected before indexing begins.
ingest only sees searchable corpus docs, not .ragit/memory/** control-plane files.
--all and --since only consider the configured implicit doc surface (doc_globs/include/exclude), not every file in the repository.

ingest

On this page