cloc

name	cloc
description	统计代码量——包括代码行数、注释行数、空白行数，按语言/文件维度汇总。支持目录、压缩包、Git 仓库、两个版本差异对比。当用户说"统计代码量"、"代码行数"、"loc"、"cloc"、"看下代码规模"、"这个项目多大"、"代码行数统计"时触发。

cloc — 代码行数统计工具

cloc 是一个 Perl 脚本，统计物理代码行数（排除空行和注释）。支持 200+ 编程语言。通过 npx cloc 即可运行，无需安装。

快速上手

# 统计当前目录
npx cloc .

# 统计指定目录
npx cloc /path/to/project

# 统计单个文件
npx cloc src/index.ts src/utils/helper.ts

# 统计压缩包
npx cloc project.tar.gz

输出格式

纯文本（默认）

───────────────────────────────────────────────────────────────
Language                     files          blank        comment           code
───────────────────────────────────────────────────────────────
TypeScript                      42           1234            567           5678
CSS                              8            234             89           1234
JSON                            12              0              0            890
───────────────────────────────────────────────────────────────
SUM:                            62           1468            656           7802
───────────────────────────────────────────────────────────────

常用格式

# Markdown（适合嵌入文档/PR）
npx cloc . --md

# JSON（适合脚本处理）
npx cloc . --json

# CSV
npx cloc . --csv

# 按文件输出（精细到每个文件）
npx cloc . --by-file

# 按文件+语言输出
npx cloc . --by-file-by-lang

自定义输出

# 隐藏速率信息（使输出确定性的，适合对比）
npx cloc . --hide-rate

# 百分比显示
npx cloc . --percent

# 只显示代码行数百分比（横向）
npx cloc . --by-percent c

# 写入文件
npx cloc . --report-file=report.txt
npx cloc . --md --report-file=report.md

# 千位分隔符（大项目易读）
npx cloc . --fmt=1 --thousands-delimiter=,

过滤与排除

# 排除目录（可指定多个）
npx cloc . --exclude-dir=node_modules,dist,.cache,.git

# 排除文件扩展名
npx cloc . --exclude-ext=json,svg,md

# 排除语言
npx cloc . --exclude-lang=JSON,Markdown,YAML

# 只统计特定扩展名
npx cloc . --include-ext=ts,tsx,js,jsx

# 只统计特定语言
npx cloc . --include-lang=TypeScript,JavaScript,CSS

# 从文件读取排除列表
echo ".git/" > .clocignore
echo "node_modules/" >> .clocignore
npx cloc . --exclude-list-file=.clocignore

# 正则排除目录路径（会匹配合并路径）
npx cloc . --fullpath --not-match-d='/(__tests__|__mocks__)/'

# 只统计特定目录模式
npx cloc . --match-d='/(src|packages)/'

# 不递归子目录
npx cloc . --no-recurse

# 跳过大文件（默认跳过 >100MB）
npx cloc . --max-file-size=10

Git 集成

# 直接从 Git 获取文件列表（自动忽略 .gitignore 内容）
npx cloc . --vcs=git

# 统计特定分支/提交
npx cloc https://github.com/user/repo.git --git
npx cloc <commit-hash> --git
npx cloc <branch-name> --git

# 对比两个分支/提交的代码差异
npx cloc --diff <commit-a> <commit-b>
npx cloc --diff branch-a branch-b

# 只对比有变化的文件（Git diff 策略 #1）
npx cloc --git-diff-rel <commit-a> <commit-b>

# 对比所有文件（Git diff 策略 #2）
npx cloc --git-diff-all <commit-a> <commit-b>

Git 对比输出示例

───────────────────────────────────────────────────────────────
Language                     files          blank        comment           code
───────────────────────────────────────────────────────────────
TypeScript                       3             -5              2             42
CSS                              1              0              0             12
───────────────────────────────────────────────────────────────
SUM:                             4             -5              2             54
───────────────────────────────────────────────────────────────

正数表示增加，负数表示减少。

高级用法

统计多个项目并求和

# 分别生成报告
npx cloc project-a/ --report-file=report-a.txt
npx cloc project-b/ --report-file=report-b.txt

# 汇总
npx cloc --sum-reports report-a.txt report-b.txt

自定义语言定义

# 导出当前语言定义（方便自定义）
npx cloc --write-lang-def=my-lang-def.txt

# 使用自定义语言定义
npx cloc . --read-lang-def=my-lang-def.txt

# 强制指定文件扩展名的语言
npx cloc . --force-lang="TypeScript,vue"

对比两个代码库

# 对比目录
npx cloc --diff /path/to/old/ /path/to/new/

# 对比压缩包
npx cloc --diff old.tar.gz new.tar.gz

# 同时计数并对比（生成三份输出）
npx cloc --count-and-diff old/ new/ --report-file=result
# 会生成 result.old, result.new, result.diff 三个文件

# 忽略空白/大小写差异
npx cloc --diff --ignore-whitespace old/ new/
npx cloc --diff --ignore-case old/ new/

常用场景速查

场景	命令
统计项目（排除 node_modules 和 dist）	npx cloc . --exclude-dir=node_modules,dist
只统计生产代码	npx cloc src/ --exclude-dir=__tests__
统计新增代码	npx cloc --diff main feature-branch
导出为 Markdown 报告	npx cloc . --exclude-dir=node_modules --md --report-file=cloc-report.md
按维度汇总（代码行数 < 1000 归到 Other）	npx cloc . --summary-cutoff=c:1000
只统计 TypeScript 文件	npx cloc src/ --include-ext=ts,tsx
查看 cloc 支持的语言	npx cloc --show-lang | head -30
查看支持的文件扩展名	npx cloc --show-ext
并行处理（多核加速）	npx cloc . --processes=0（0=自动）
忽略 auto-generated 文件	npx cloc . --no-autogen

注意事项

• cloc 统计的是物理行数（physical lines），不是逻辑行数（logical lines）。意味着格式化换行也会被计入代码行。
• 首次运行 npx cloc 会下载 cloc 的 Perl 脚本（约 10MB），之后会缓存。
• --git 模式只能统计已提交的文件，未跟踪的更改不会被统计。
• 大项目建议加 --exclude-dir=node_modules，否则会扫描所有依赖。
• --diff 模式下大型文件可能超时，可以用 --diff-timeout=30 调整。
• --vcs=git 和 --git 的区别：前者用 git ls-files 获取文件列表（只包含 tracked 文件）；后者把参数当作 git commit hash/branch 来解析。