---
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.

This feature requires external dependencies to function. SCIP indexers and language servers are used to resolve symbols and references.

```bash
#Run in project root
tld index .
```

Indexing runs locally; cloning remote repositories and indexer dependency setup may need network access. 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` lets you track what changes in your working tree, either by you or your agent. 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 saves the affected-file change overlay under **Repositories → Watch**. See the [Repositories guide](/docs/ui/repositories) for snapshots, mapping, and comparisons.

```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.

Go, TypeScript, Python, and Rust watches also use language servers (`gopls`, `typescript-language-server`, `pyright-langserver`, and `rust-analyzer`) for incremental updates. Other languages are reindexed from scratch on each change.

Check availability with `tld doctor`.

## Mapping

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. 

This is meant to give you building blocks for your diagrams. They are grounded and derived from source code, with some metadata fields pre-filled. You can copy paste or link to them in your architecture diagrams.

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).