Skip to main content

Indexing Folders

The problem​

Querying hundreds of .it files means parsing every file on every query. As your document collection grows, this gets slow.

The solution​

Build a .it-index for each folder. The index pre-parses every .it file and stores the results as JSON. Queries read the index instead of parsing each file.

Build an index​

# Single folder
intenttext index ./contracts

# All subfolders
intenttext index ./company --recursive

The --recursive flag creates one .it-index per subfolder — not one giant index.

What gets indexed​

Every block is indexed except layout and structural blocks:

IndexedSkipped
text:, quote:, warning:, tip:page:, font:
contact:, deadline:, metric:header:, footer:
approve:, sign:, freeze:, amendment:watermark:, break:
step:, gate:, policy:meta:, toc:
def:, figure:, ref:, cite:

Index structure​

{
  "version": "1",
  "scope": "shallow",
  "folder": "contracts/active",
  "built_at": "2026-03-15T10:30:00Z",
  "core_version": "3.1.0",
  "files": {
    "acme-service.it": {
      "hash": "abc123",
      "modified_at": "2026-03-14T09:00:00Z",
      "metadata": { "title": "Service Agreement — Acme Corp" },
      "blocks": [
        {
          "type": "deadline",
          "content": "Payment due",
          "section": "Payment",
          "properties": { "due": "2026-04-15" }
        }
      ]
    }
  }
}

Staleness detection​

The index tracks file hashes. On rebuild, only changed files are re-parsed:

# Rebuild — unchanged files are skipped
intenttext index ./contracts

New files → added to the index. Modified files → re-indexed. Deleted files → removed from the index.

When to rebuild​

EventAction
Added a new .it fileintenttext index ./folder
Edited an existing fileintenttext index ./folder
Deleted a fileintenttext index ./folder
Nothing changedNo action needed — index is reused

Rebuilding is fast because only stale entries are updated.

Automatic query speedup​

Queries use the index automatically when .it-index exists:

# Without index: parses every .it file in contracts/
intenttext query ./contracts --type deadline --format table

# With index: reads .it-index, returns results instantly
intenttext query ./contracts --type deadline --format table

No flag needed. If .it-index exists and is fresh, it's used.

Next steps​