tldr-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TLDR-Code: Complete Reference

TLDR-Code：完整参考手册

Token-efficient code analysis. 95% savings vs raw file reads.

高效Token代码分析。与直接读取原始文件相比，可节省95%的Token用量。

Quick Reference

快速参考

Task	Command
File tree	`tldr tree src/`
Code structure	`tldr structure . --lang python`
Search code	`tldr search "pattern" .`
Call graph	`tldr calls src/`
Who calls X?	`tldr impact func_name .`
Control flow	`tldr cfg file.py func`
Data flow	`tldr dfg file.py func`
Program slice	`tldr slice file.py func 42`
Dead code	`tldr dead src/`
Architecture	`tldr arch src/`
Imports	`tldr imports file.py`
Who imports X?	`tldr importers module_name .`
Affected tests	`tldr change-impact --git`
Type check	`tldr diagnostics file.py`
Semantic search	`tldr semantic search "auth flow"`

任务	命令
文件树	`tldr tree src/`
代码结构	`tldr structure . --lang python`
代码搜索	`tldr search "pattern" .`
调用图	`tldr calls src/`
谁调用了X？	`tldr impact func_name .`
控制流	`tldr cfg file.py func`
数据流	`tldr dfg file.py func`
程序切片	`tldr slice file.py func 42`
死代码	`tldr dead src/`
架构分析	`tldr arch src/`
导入语句	`tldr imports file.py`
谁导入了X？	`tldr importers module_name .`
受影响的测试	`tldr change-impact --git`
类型检查	`tldr diagnostics file.py`
语义搜索	`tldr semantic search "auth flow"`

The 5-Layer Stack

5层堆栈结构

Layer 1: AST         ~500 tokens   Function signatures, imports
Layer 2: Call Graph  +440 tokens   What calls what (cross-file)
Layer 3: CFG         +110 tokens   Complexity, branches, loops
Layer 4: DFG         +130 tokens   Variable definitions/uses
Layer 5: PDG         +150 tokens   Dependencies, slicing
───────────────────────────────────────────────────────────────
Total:              ~1,200 tokens  vs 23,000 raw = 95% savings

Layer 1: AST         ~500 tokens   Function signatures, imports
Layer 2: Call Graph  +440 tokens   What calls what (cross-file)
Layer 3: CFG         +110 tokens   Complexity, branches, loops
Layer 4: DFG         +130 tokens   Variable definitions/uses
Layer 5: PDG         +150 tokens   Dependencies, slicing
───────────────────────────────────────────────────────────────
Total:              ~1,200 tokens  vs 23,000 raw = 95% savings

CLI Commands

CLI命令

Navigation

导航功能

bash

undefined

bash

undefined

File tree

文件树

tldr tree [path] tldr tree src/ --ext .py .ts # Filter extensions tldr tree . --show-hidden # Include hidden files

tldr tree [path] tldr tree src/ --ext .py .ts # 过滤文件扩展名 tldr tree . --show-hidden # 包含隐藏文件

Code structure (codemaps)

代码结构（代码映射）

tldr structure [path] --lang python tldr structure src/ --max 100 # Max files to analyze

undefined

tldr structure [path] --lang python tldr structure src/ --max 100 # 最多分析的文件数量

undefined

Search

搜索功能

bash

undefined

bash

undefined

Text search

文本搜索

tldr search <pattern> [path] tldr search "def process" src/ tldr search "class.*Error" . --ext .py tldr search "TODO" . -C 3 # 3 lines context tldr search "func" . --max 50 # Limit results

tldr search <pattern> [path] tldr search "def process" src/ tldr search "class.*Error" . --ext .py tldr search "TODO" . -C 3 # 显示3行上下文 tldr search "func" . --max 50 # 限制结果数量

Semantic search (natural language)

语义搜索（自然语言）

tldr semantic search "authentication flow" tldr semantic search "error handling" --k 10 tldr semantic search "database queries" --expand # Include call graph

undefined

tldr semantic search "authentication flow" tldr semantic search "error handling" --k 10 tldr semantic search "database queries" --expand # 包含调用图

undefined

File Analysis

文件分析

bash

undefined

bash

undefined

Full file info

完整文件信息

tldr extract <file> tldr extract src/api.py tldr extract src/api.py --class UserService # Filter to class tldr extract src/api.py --function process # Filter to function tldr extract src/api.py --method UserService.get # Filter to method

tldr extract <file> tldr extract src/api.py tldr extract src/api.py --class UserService # 过滤指定类 tldr extract src/api.py --function process # 过滤指定函数 tldr extract src/api.py --method UserService.get # 过滤指定方法

Relevant context (follows call graph)

Control flow graph (complexity)

控制流图（复杂度分析）

tldr cfg <file> <function> tldr cfg src/processor.py process_data

Returns: cyclomatic complexity, blocks, branches, loops

返回结果：圈复杂度、代码块、分支、循环

Data flow graph (variable tracking)

数据流图（变量追踪）

tldr dfg <file> <function> tldr dfg src/processor.py process_data

Returns: where variables are defined, read, modified

返回结果：变量的定义、读取、修改位置

Program slice (what affects line X)

程序切片（哪些代码影响第X行）

tldr slice <file> <function> <line> tldr slice src/processor.py process_data 42 tldr slice src/processor.py process_data 42 --direction forward tldr slice src/processor.py process_data 42 --var result

undefined

undefined

Codebase Analysis

代码库分析

bash

undefined

bash

undefined

Build cross-file call graph

构建跨文件调用图

tldr calls [path] tldr calls src/ --lang python

Reverse call graph (who calls this function?)

反向调用图（哪些函数调用了当前函数？）

tldr impact <func> [path] tldr impact process_data src/ --depth 5 tldr impact authenticate . --file auth # Filter by file

tldr impact <func> [path] tldr impact process_data src/ --depth 5 tldr impact authenticate . --file auth # 按文件过滤

Find dead/unreachable code

查找死代码/不可达代码

tldr dead [path] tldr dead src/ --entry main cli test_ # Specify entry points tldr dead . --lang typescript

tldr dead [path] tldr dead src/ --entry main cli test_ # 指定入口点 tldr dead . --lang typescript

Detect architectural layers

检测架构分层

tldr arch [path] tldr arch src/ --lang python

Returns: entry layer, middle layer, leaf layer, circular deps

返回结果：入口层、中间层、叶子层、循环依赖

undefined

undefined

Import Analysis

导入分析

bash

undefined

bash

undefined

Parse imports from file

解析文件中的导入语句

tldr imports <file> tldr imports src/api.py tldr imports src/api.ts --lang typescript

Reverse import lookup (who imports this module?)

反向导入查找（哪些文件导入了该模块？）

tldr importers <module> [path] tldr importers datetime src/ tldr importers UserService . --lang typescript

undefined

tldr importers <module> [path] tldr importers datetime src/ tldr importers UserService . --lang typescript

undefined

Quality & Testing

质量与测试

bash

undefined

bash

undefined

Type check + lint

类型检查 + 代码规范检查

tldr diagnostics <file|path> tldr diagnostics src/api.py tldr diagnostics . --project # Whole project tldr diagnostics src/ --no-lint # Type check only tldr diagnostics src/ --format text # Human-readable

tldr diagnostics <file|path> tldr diagnostics src/api.py tldr diagnostics . --project # 整个项目 tldr diagnostics src/ --no-lint # 仅类型检查 tldr diagnostics src/ --format text # 人类可读格式

Find affected tests

查找受影响的测试

tldr change-impact [files...] tldr change-impact # Auto-detect (session/git) tldr change-impact src/api.py # Explicit files tldr change-impact --session # Session-modified files tldr change-impact --git # Git diff files tldr change-impact --git --git-base main # Diff against branch tldr change-impact --run # Actually run affected tests

undefined

tldr change-impact [files...] tldr change-impact # 自动检测（会话/Git） tldr change-impact src/api.py # 指定文件 tldr change-impact --session # 会话中修改的文件 tldr change-impact --git # Git差异文件 tldr change-impact --git --git-base main # 与指定分支对比差异 tldr change-impact --run # 实际运行受影响的测试

undefined

Caching

缓存功能

bash

undefined

bash

undefined

Pre-build call graph cache

预构建调用图缓存

tldr warm <path> tldr warm src/ --lang python tldr warm . --background # Build in background

tldr warm <path> tldr warm src/ --lang python tldr warm . --background # 后台构建

Build semantic index (one-time)

构建语义索引（一次性操作）

tldr semantic index [path] tldr semantic index . --lang python tldr semantic index . --model all-MiniLM-L6-v2 # Smaller model (80MB)

---

tldr semantic index [path] tldr semantic index . --lang python tldr semantic index . --model all-MiniLM-L6-v2 # 轻量模型（80MB）

---

Daemon (Faster Queries)

守护进程（更快的查询速度）

The daemon holds indexes in memory for instant repeated queries.

守护进程将索引保存在内存中，实现即时重复查询。

Daemon Commands

守护进程命令

bash

undefined

bash

undefined

Start daemon (backgrounds automatically)

启动守护进程（自动后台运行）

tldr daemon start tldr daemon start --project /path/to/project

Check status

检查状态

tldr daemon status

Stop daemon

停止守护进程

tldr daemon stop

Send raw command

发送原始命令

tldr daemon query ping tldr daemon query status

Notify file change (for hooks)

通知文件变更（用于钩子）

tldr daemon notify <file> tldr daemon notify src/api.py

undefined

tldr daemon notify <file> tldr daemon notify src/api.py

undefined

Daemon Features

守护进程特性

Feature	Description
Auto-shutdown	30 minutes idle
Query caching	SalsaDB memoization
Content hashing	Skip unchanged files
Dirty tracking	Incremental re-indexing
Cross-platform	Unix sockets / Windows TCP

特性	描述
自动关闭	闲置30分钟后自动关闭
查询缓存	SalsaDB记忆化缓存
内容哈希	跳过未变更的文件
脏数据追踪	增量重新索引
跨平台支持	Unix套接字 / Windows TCP

Daemon Socket Protocol

守护进程套接字协议

Send JSON to socket, receive JSON response:

json

// Request
{"cmd": "search", "pattern": "process", "max_results": 10}

// Response
{"status": "ok", "results": [...]}

All 22 daemon commands:

ping, status, shutdown, search, extract, impact, dead, arch,
cfg, dfg, slice, calls, warm, semantic, tree, structure,
context, imports, importers, notify, diagnostics, change_impact

向套接字发送JSON，接收JSON响应：

json

// 请求
{"cmd": "search", "pattern": "process", "max_results": 10}

// 响应
{"status": "ok", "results": [...]}

全部22个守护进程命令：

ping, status, shutdown, search, extract, impact, dead, arch,
cfg, dfg, slice, calls, warm, semantic, tree, structure,
context, imports, importers, notify, diagnostics, change_impact

Semantic Search (P6)

语义搜索（P6）

Natural language code search using embeddings.

使用向量嵌入的自然语言代码搜索。

Setup

配置

bash

undefined

bash

undefined

Build index (downloads model on first run)

构建索引（首次运行时下载模型）

tldr semantic index .

Default model: bge-large-en-v1.5 (1.3GB, best quality)

默认模型：bge-large-en-v1.5（1.3GB，最佳质量）

Smaller model: all-MiniLM-L6-v2 (80MB, faster)

轻量模型：all-MiniLM-L6-v2（80MB，速度更快）

tldr semantic index . --model all-MiniLM-L6-v2

undefined

tldr semantic index . --model all-MiniLM-L6-v2

undefined

Search

搜索

bash

tldr semantic search "authentication flow"
tldr semantic search "error handling patterns" --k 10
tldr semantic search "database connection" --expand  # Follow call graph

bash

tldr semantic search "authentication flow"
tldr semantic search "error handling patterns" --k 10
tldr semantic search "database connection" --expand  # 跟随调用图

Configuration

配置文件

.claude/settings.json

json

{
  "semantic_search": {
    "enabled": true,
    "auto_reindex_threshold": 20,
    "model": "bge-large-en-v1.5"
  }
}

在

.claude/settings.json

中：

json

{
  "semantic_search": {
    "enabled": true,
    "auto_reindex_threshold": 20,
    "model": "bge-large-en-v1.5"
  }
}

Languages Supported

支持的语言

Language	AST	Call Graph	CFG	DFG	PDG
Python	Yes	Yes	Yes	Yes	Yes
TypeScript	Yes	Yes	Yes	Yes	Yes
JavaScript	Yes	Yes	Yes	Yes	Yes
Go	Yes	Yes	Yes	Yes	Yes
Rust	Yes	Yes	Yes	Yes	Yes
Java	Yes	Yes	-	-	-
C/C++	Yes	Yes	-	-	-
Ruby	Yes	-	-	-	-
PHP	Yes	-	-	-	-
Kotlin	Yes	-	-	-	-
Swift	Yes	-	-	-	-
C#	Yes	-	-	-	-
Scala	Yes	-	-	-	-
Lua	Yes	-	-	-	-
Elixir	Yes	-	-	-	-

语言	AST	Call Graph	CFG	DFG	PDG
Python	是	是	是	是	是
TypeScript	是	是	是	是	是
JavaScript	是	是	是	是	是
Go	是	是	是	是	是
Rust	是	是	是	是	是
Java	是	是	-	-	-
C/C++	是	是	-	-	-
Ruby	是	-	-	-	-
PHP	是	-	-	-	-
Kotlin	是	-	-	-	-
Swift	是	-	-	-	-
C#	是	-	-	-	-
Scala	是	-	-	-	-
Lua	是	-	-	-	-
Elixir	是	-	-	-	-

Ignore Patterns

忽略规则

TLDR respects

.tldrignore

(gitignore syntax):

gitignore

undefined

TLDR 遵循

.tldrignore

（Gitignore语法）：

gitignore

undefined

.tldrignore

.venv/ pycache/ node_modules/ *.min.js dist/


First run creates `.tldrignore` with sensible defaults.
Use `--no-ignore` to bypass.

---

.venv/ pycache/ node_modules/ *.min.js dist/


首次运行会创建包含合理默认值的 `.tldrignore` 文件。
使用 `--no-ignore` 参数可绕过忽略规则。

---

When to Use TLDR vs Other Tools

TLDR与其他工具的适用场景对比

Task	Use TLDR	Use Grep
Find function definition	`tldr extract file --function X`	-
Search code patterns	`tldr search "pattern"`	-
String literal search	-	`grep "literal"`
Config values	-	`grep "KEY="`
Cross-file calls	`tldr calls`	-
Reverse deps	`tldr impact func`	-
Complexity analysis	`tldr cfg file func`	-
Variable tracking	`tldr dfg file func`	-
Natural language query	`tldr semantic search`	-

任务	使用TLDR	使用Grep
查找函数定义	`tldr extract file --function X`	-
搜索代码模式	`tldr search "pattern"`	-
字符串字面量搜索	-	`grep "literal"`
配置值搜索	-	`grep "KEY="`
跨文件调用关系	`tldr calls`	-
反向依赖	`tldr impact func`	-
复杂度分析	`tldr cfg file func`	-
变量追踪	`tldr dfg file func`	-
自然语言查询	`tldr semantic search`	-

Python API

python

from tldr.api import (
    # L1: AST
    extract_file, extract_functions, get_imports,
    # L2: Call Graph
    build_project_call_graph, get_intra_file_calls,
    # L3: CFG
    get_cfg_context,
    # L4: DFG
    get_dfg_context,
    # L5: PDG
    get_slice, get_pdg_context,
    # Unified
    get_relevant_context,
    # Analysis
    analyze_dead_code, analyze_architecture, analyze_impact,
)

python

from tldr.api import (
    # L1: AST
    extract_file, extract_functions, get_imports,
    # L2: Call Graph
    build_project_call_graph, get_intra_file_calls,
    # L3: CFG
    get_cfg_context,
    # L4: DFG
    get_dfg_context,
    # L5: PDG
    get_slice, get_pdg_context,
    # 统一接口
    get_relevant_context,
    # 分析功能
    analyze_dead_code, analyze_architecture, analyze_impact,
)

Example: Get context for LLM

示例：为LLM获取上下文

ctx = get_relevant_context("src/", "main", depth=2, language="python") print(ctx.to_llm_string())

---

ctx = get_relevant_context("src/", "main", depth=2, language="python") print(ctx.to_llm_string())

---

Bug Fixing Workflow (Navigation + Read)

缺陷修复工作流（导航 + 阅读）

Key insight: TLDR navigates, then you read. Don't try to fix bugs from summaries alone.

核心思路： TLDR负责导航定位，然后你再阅读具体代码。不要仅通过摘要尝试修复缺陷。

The Pattern

流程模式

bash

undefined

bash

undefined

1. NAVIGATE: Find which files matter

1. 导航：找到相关文件

tldr imports file.py # What does buggy file depend on? tldr impact func_name . # Who calls the buggy function? tldr calls . # Cross-file edges (follow 2-hop for models)

tldr imports file.py # 有问题的文件依赖了哪些模块？ tldr impact func_name . # 哪些函数调用了有问题的函数？ tldr calls . # 跨文件调用关系（跟随2跳找到模型相关代码）

2. READ: Get actual code for critical files (2-4 files, not all 50)

2. 阅读：获取关键文件的实际代码（2-4个文件，而非全部50个）

Use Read tool or tldr search -C for code with context

使用阅读工具或

tldr search -C

获取带上下文的代码

tldr search "def buggy_func" . -C 20

undefined

tldr search "def buggy_func" . -C 20

undefined

Why This Works

为什么这种方式有效

For cross-file bugs (e.g., wrong field name, type mismatch), you need to see:

The file with the bug (handler accessing
```
task.user_id
```
)
The file with the contract (model defining
```
owner_id
```
)

TLDR finds which files matter. Then you read them.

对于跨文件缺陷（例如：错误的字段名、类型不匹配），你需要查看：

存在缺陷的文件（处理器访问
```
task.user_id
```
）
定义契约的文件（模型定义了
```
owner_id
```
）

TLDR负责定位相关文件，然后你再阅读具体内容。

Getting More Context

获取更多上下文

If TLDR output isn't enough:

```
tldr search "pattern" . -C 20
```
- Get actual code with 20 lines context
```
tldr imports file.py
```
- See what a file depends on
Read the file directly if you need the full implementation

如果TLDR的输出不够：

```
tldr search "pattern" . -C 20
```
- 获取带20行上下文的实际代码
```
tldr imports file.py
```
- 查看文件的依赖
如果需要完整实现，直接阅读文件

Token Savings Evidence

Token节省数据

Raw file read:    23,314 tokens
TLDR all layers:   1,189 tokens
─────────────────────────────────
Savings:              95%

The insight: Call graph navigates to relevant code, then layers give structured summaries. You don't read irrelevant code.

Raw file read:    23,314 tokens
TLDR all layers:   1,189 tokens
─────────────────────────────────
Savings:              95%

核心思路：调用图导航到相关代码，然后各层提供结构化摘要。你无需阅读无关代码。

tldr-code

Original

Translation

TLDR-Code: Complete Reference

TLDR-Code：完整参考手册

Quick Reference

快速参考

The 5-Layer Stack

5层堆栈结构

CLI Commands

CLI命令

Navigation

导航功能

File tree

文件树

Code structure (codemaps)

代码结构（代码映射）

Search

搜索功能

Text search

文本搜索

Semantic search (natural language)

语义搜索（自然语言）

File Analysis

文件分析

Full file info

完整文件信息

Relevant context (follows call graph)

相关上下文（跟随调用图）

Flow Analysis

流分析

Control flow graph (complexity)

控制流图（复杂度分析）

Returns: cyclomatic complexity, blocks, branches, loops

返回结果：圈复杂度、代码块、分支、循环

Data flow graph (variable tracking)

数据流图（变量追踪）

Returns: where variables are defined, read, modified

返回结果：变量的定义、读取、修改位置

Program slice (what affects line X)

程序切片（哪些代码影响第X行）

Codebase Analysis

代码库分析

Build cross-file call graph

构建跨文件调用图

Reverse call graph (who calls this function?)

反向调用图（哪些函数调用了当前函数？）

Find dead/unreachable code

查找死代码/不可达代码

Detect architectural layers

检测架构分层

Returns: entry layer, middle layer, leaf layer, circular deps

返回结果：入口层、中间层、叶子层、循环依赖

Import Analysis

导入分析

Parse imports from file

解析文件中的导入语句

Reverse import lookup (who imports this module?)

反向导入查找（哪些文件导入了该模块？）

Quality & Testing

质量与测试

Type check + lint

类型检查 + 代码规范检查

Find affected tests

查找受影响的测试

Caching

缓存功能

Pre-build call graph cache

预构建调用图缓存

Build semantic index (one-time)

构建语义索引（一次性操作）

Daemon (Faster Queries)

守护进程（更快的查询速度）

Daemon Commands

守护进程命令

Start daemon (backgrounds automatically)

启动守护进程（自动后台运行）

Check status

检查状态

Stop daemon

使用阅读工具或
`tldr search -C`
获取带上下文的代码