EKOSdocs
Docs / Guides Build

Indexing a Repository

Compile a Git repository — code, history, docs and dependencies — into a knowledge index.

Goal: a searchable, evidenced model of one repository.

Steps

cd /path/to/repo
ekos init --detect      # writes an ekos.toml from what is in the tree: SQL dialects, exclusions, inputs

Or keep the configuration and the compiled state outside the repository, in the EKOS home (~/.ekos). Nothing is then written into the source tree:

ekos project add shop --source /path/to/repo --detect
ekos --project shop build      # every command takes --project

Check ekos.toml so [observe] covers the repository root and skips everything that is not your source:

[observe]
paths = ["."]                       # keep "." — see the warning below
ignore-patterns = [".ekos", ".git", "target", "node_modules", ".venv", "venv", "site-packages", "__pycache__", "dist"]
ekos config preview-scan            # counts what build would observe, reads nothing
ekos build && ekos recover && ekos resolve && ekos compile && ekos commit

Use paths = ["."]. The Git observer only checks for a .git directory directly under an observe path. If paths lists subdirectories, there are zero Git commits in the index and nothing warns you.

Ignore patterns are names, of a directory or a file (venv, mysql-sakila-insert-data.sql), not paths or globs: *.lock matches nothing. ekos config validate warns about paths, globs and bare extensions.

What you get

Analyzer Recovers
Rust / Python / JavaScript / Elixir / Perl modules, symbols, imports, Calls, inheritance (Extends), doc comments, source spans
Java types and methods with signatures and Javadoc, inheritance and imports, SQL built in method bodies — see Indexing Java Applications
SQL tables, views, routines, triggers, migration scripts — see Indexing a Database
Python ORM SQLAlchemy models as Table objects with same-file foreign keys
crate_topology, cicd Cargo.toml crates and GitHub Actions workflows
dependency scan declared dependencies as Technology objects
Git commits and authors (Person); with [tickets] keys, one Ticket per tracker id a commit names
localdocs Markdown/PDF/DOCX/HTML sections, with heading-aware structure and links between documents

Add GitHub issues and pull requests

Set environment variables before ekos build:

export EKOS_GITHUB_OWNER=alexeyban EKOS_GITHUB_REPO=EKOS
export EKOS_GITHUB_TOKEN=…          # optional; raises rate limits

Verify

ekos query find "main"
ekos ledger status
ekos coverage          # which input kinds compiled into objects, and which silently produced nothing

Contamination check. If counts look far too large, something you did not mean to index was observed (virtualenvs and vendored code are the usual cause). Fix ignore-patterns, ekos clean, and rebuild.