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.gitdirectory directly under an observe path. Ifpathslists 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:*.lockmatches nothing.ekos config validatewarns 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.