---
title: tld index
description: Index a repository into the local code graph. One-shot snapshots or
  a continuous watcher that follows Git.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

`tld index` reads your source code and turns it into a structured code graph with architectural snapshots. It's the engine behind code-driven diagrams.

```bash
tld index .
```

It runs locally and offline. Scan, index, publish. Then `tld index --watch` keeps it live as you code.

:::caution
The indexing pipeline is under active development. Expect rough edges and long runtimes on large codebases. Start with a small repo or a branch.
:::

## What it does

1. **Discover**: walks the repository and finds source files, skipping excluded paths.
2. **Parse**: Tree-sitter grammars parse every file into syntax trees.
3. **Index symbols**: external SCIP indexers resolve precise symbols and references, with LSP-grade accuracy where a language has one.
4. **Relationships**: builds the edges between symbols, packages, and files.
5. **Infrastructure**: picks up infrastructure definitions where present.
6. **Verify**: checks the result before publishing.
7. **Publish snapshot**: writes an immutable snapshot to the local database.
8. **Save diff diagram**: computes the change overlay against the previous snapshot.
9. **Map graph**: optionally groups the dependency graph into architectural components (`--map`).

Each run publishes a snapshot keyed to the Git revision, so you can compare any two of them later.

## Basic usage

```bash
# Index the current directory
tld index .

# Index a specific path
tld index ./src

# Index a remote repository (cloned into the tld data dir)
tld index github.com/org/repo
tld index https://github.com/org/repo.git

# Watch for Git changes
tld index . --watch

# Group the graph into architectural components
tld index . --map
```

When it finishes you'll see a summary:

```
snapshot 7f3c9a12...
repository  github.com/org/project
revision    abc123def456
sources     1284
projects    12
facts       8452
edges       19033
map         view 42 (9 components, 14 groups, 3 isolated, modularity 0.61)
```

## Watch mode

`--watch` keeps the index in sync with your working tree. The current commit is the **base**, the combined staged, unstaged, and untracked files are the **head**. Git changes trigger an incremental reindex after a debounce, and every new commit becomes an immutable snapshot. Watch always saves the affected-file change overlay you see under **Repositories → Live changes** in the web app.

```bash
tld index . --watch
```

It requires a Git repository. Watch runs in the foreground until you stop it with Ctrl-C, or you can detach it:

```bash
# Start a background watcher and return
tld index . --watch --detach

# Check what's running
tld index status
tld index status --all

# Stop a watcher
tld index stop .
```

Watchers are tracked per checkout, so each developer can watch their own clone. A repository can only have one watcher at a time; the second one exits.

## The map view

By default `tld index` publishes the raw code graph. Pass `--map` to group it into architectural components and materialize a map view you can open in the editor. Grouping and connector budgets come from global `map.*` config, with per-repository overrides on the repository settings page. With `--watch`, the map refreshes after each scan.

## Remote repositories

`tld index` accepts `github.com/owner/repo`, `owner/repo`, or any Git URL. Remote repositories are cloned into tld's data directory and treated as managed checkouts. An explicit URL always wins; `owner/repo` shorthand is only treated as remote when no local directory matches.

## Excludes

Keep generated and vendored code out of the graph:

```bash
tld index . --exclude vendor/ --exclude "**/*.pb.go"
```

Workspace `exclude` patterns in `.tld.yaml` are applied automatically. `tld index --exclude` adds to them for a single run.

## Polling and debounce

The watcher uses fsnotify with a polling failsafe. Tune it for slow or network filesystems:

```bash
tld index . --watch --poll-interval 5s --debounce 1s
```

## Supported languages

| Language | Indexer |
|---|---|
| Go | `scip-go` |
| TypeScript / JavaScript | `scip-typescript` |
| Python | `scip-python` |
| Java | `scip-java` |
| C / C++ | `scip-clang` |
| C# / .NET | `scip-dotnet` |
| Rust | `rust-analyzer` |
| Dart | `scip-dart` |
| PHP | `scip-php` |
| Ruby | `scip-ruby` |

Missing indexers are skipped; run `tld doctor` to see what's available. Tool paths and the per-indexer timeout are configurable under `index.tools.*`.

## Where the results go

Snapshots live in the local tld database. Run `tld serve` and open **Repositories** to browse indexed repositories, inspect the map, and see live changes. To turn snapshots into a diff diagram, use [`tld git compare`](/docs/tld/git-compare).