Sloc 4.1.0

<a id="english"></a>

Sloc

---

English | 中文

Sloc (Source Lines Of Code) is a .NET global command-line tool for counting lines of source code.

Features

• Count code / comment / blank / total lines
• Correctly handles single-line comments, block comments, and multi-line block comments
• Built-in comment rules for 66 common languages (auto-detected by file extension or name, e.g. Makefile, Dockerfile, CMakeLists.txt)
• Recursive directory scanning with --include / --exclude glob filters
• Automatically excludes bin, obj, artifacts, .git, .vs, .vscode, .idea, node_modules, and similar directories by default
• Five output formats: colored table (default), JSON, HTML, CSV, and Markdown
• Comment Health column in table output showing comment-density indicator (None / Low / Fair / Good / High / Dense)
• Format auto-detected from the --output file extension (.json → JSON, .html / .htm → HTML)
• Honors .gitignore files (including nested ones, and, when path is inside a git repository, the ones in the directories above it up to the repository root) by default; --no-gitignore disables it
• Parallel analysis across CPU cores (--jobs), with deterministic output
• CI-friendly: JSON to stdout for piping (e.g. | jq), meaningful exit codes, and a --min-comment-pct threshold gate
• Compare against a saved JSON report with --baseline, or directly against another commit with --compare-to, to see how line counts changed
• Sort and limit the language summary with --sort (including by comment percentage) / --top
• Files or directories that cannot be read, and binary files (detected by NUL bytes), are skipped gracefully; a summary of skipped paths and reasons is shown at the end (in every format except Csv, which stays a single machine-parsable table)

Installation

Install via winget (Windows):

winget install coldhighsun.sloc

Or install as a .NET global tool (requires .NET 10 SDK):

dotnet tool install --global Sloc

Update or uninstall:

winget upgrade coldhighsun.sloc
winget uninstall coldhighsun.sloc

dotnet tool update --global Sloc
dotnet tool uninstall --global Sloc

Usage

sloc <path> [options]

Examples

# Count current directory (recursive)
sloc .

# Count a specific directory
sloc ./src

# Count a single file
sloc ./src/Program.cs

# Only count C# files
sloc ./src --include "**/*.cs"

# Exclude test directories
sloc . --exclude "**/tests/**"

# Show per-file details
sloc ./src --by-file

# Output as JSON
sloc ./src --format json

# Save results as an HTML report (opens in a browser)
sloc ./src --format html --output report.html

# HTML printed to stdout (default when --output is omitted)
sloc ./src --format html

# Auto-detect format from file extension
sloc ./src --output sloc-report.json

# Include files with unknown extensions
sloc . --all

# Do not recurse into subdirectories
sloc ./src --no-recursive

# Exclude a directory by name, at any depth
sloc . --exclude-dir vendor

# Watch for file changes and live-refresh the table
sloc ./src --watch

# Count byte-identical files only once
sloc . --unique

# Pipe JSON to jq
sloc . --format json | jq .total

# Fail CI if comments are below 10% of lines
sloc . --min-comment-pct 10

# Save a baseline, then diff a later run against it
sloc . --format json --output baseline.json
sloc . --baseline baseline.json

# Diff the current working tree directly against a commit, no baseline file needed
sloc . --compare-to HEAD~5

# Diff two commits directly, without checking either out
sloc . --git-hash HEAD --compare-to main

# Analyze a specific commit's tree without checking it out
sloc . --git-hash v1.2.0

# Analyze exactly the files listed in a text file
sloc --list-file files.txt

# Sort by comment lines and show only the top 5 languages
sloc . --sort comment --top 5

# Sort by comment percentage, descending
sloc . --sort commentpct

# Markdown report with both language summary and per-file breakdown, printed to stdout
sloc . --format markdown --detailed -o -

Options

Option	Short	Description
path (argument)		File or directory to analyze, defaults to current directory .. Running sloc with no arguments at all shows help instead.
--list-file		Analyze exactly the files listed one-per-line in this file instead of scanning path; use - to read the list from stdin
--include	-i	File glob pattern to include, can be specified multiple times
--exclude	-e	File glob pattern to exclude, can be specified multiple times
--exclude-dir		Directory name to exclude at any depth (e.g. vendor); shorthand for --exclude "**/<name>/**", can be specified multiple times
--include-lang		Language display name to include (e.g. "C#"), matched case-insensitively; can be specified multiple times
--exclude-lang		Language display name to exclude, matched case-insensitively; can be specified multiple times
--unique		Count byte-identical files only once; later duplicates are reported as skipped
--format	-f	Output format: Table (default), Json, Html, Csv, or Markdown
--output	-o	Output file path for Json / Html / Csv / Markdown formats; use - to write to stdout; format is inferred from the file extension when --format is not specified
--no-recursive		Do not recurse into subdirectories
--no-health		Hide the Comment Health column and percentage breakdowns
--by-file		Show per-file details in addition to the language summary
--detailed		In Json / Html / Markdown output, include both the language summary and the per-file breakdown. In Csv output it selects the language summary only (a single well-formed table)
--paged	-p	Show paged output
--all		Include files with unknown extensions (grouped as Other)
--quiet	-q	Suppress the banner, progress UI, and Saved to message
--no-progress		Suppress the live table and progress bar
--watch	-w	Watch the path for file changes and re-run the analysis, refreshing the table (Table format only; press Ctrl+C to stop)
--min-comment-pct		Fail (exit code 2) if the overall comment percentage is below this value
--jobs	-j	Max files to analyze in parallel (default: processor count; 1 = sequential)
--no-gitignore		Do not honor .gitignore files (they are respected by default, including those above path in its repository, the repository's info/exclude, and the global core.excludesFile); also scans nested repositories such as submodules, which are otherwise skipped (and listed as skipped) when path is inside a repository (--compare-to always skips them, since the commit holds none of their files)
--no-gitattributes		Do not honor .gitattributes files (linguist-vendored/linguist-generated files are excluded by default, including by the .gitattributes files above path in its repository)
--git-hash		Analyze the repository tree as of this commit/tree-ish, without checking it out; path is used as the repo root; requires git on PATH; symlinked and submodule tree entries are skipped; files with a smudge filter (e.g. Git LFS) or a working-tree-encoding attribute are converted as a checkout would (Git LFS may download objects), and a file whose filter fails is skipped; --include/--exclude, --no-recursive, --follow-symlinks, --no-gitignore, and --no-gitattributes have no effect in this mode; mutually exclusive with --list-file
--follow-symlinks		Include symlinked/junctioned directories and symlinked files instead of skipping them; a directory symlink that loops back to one of its own ancestors (or points at a directory containing one) is still skipped, as is a link whose target is already inside path; a file reached through several links is counted once
--baseline		Compare against a previously saved JSON report and show the line-count diff
--compare-to		Diff the current analysis against path as of this other commit/tree-ish, without checking it out or saving a baseline file first; requires git on PATH; path may be a directory or a single file; the commit's files are filtered the same way as the working tree (--include/--exclude, .gitignore, .gitattributes, …) so unchanged files diff to zero; combine with --git-hash to diff two commits directly; mutually exclusive with --baseline, --watch, and --list-file
--sort		Order the language summary by Total (default), Code, Comment, Blank, Files, Name, or CommentPct
--top		Show only the top N languages in the summary
--no-update-check		Do not check GitHub for a newer release (checked by default, with a 2 second timeout)
--help	-h	Show help
--version		Show version

Supported language display names (for --include-lang/--exclude-lang):

Assembly, Astro, BASIC, Batch, Bazel/Starlark, C, C#, C# Designer, C++, Clojure, CMake, Crystal, CSS, D, Dart, Dockerfile, Elixir, Elm, Erlang, F#, Go, GraphQL, Groovy, Haskell, HTML, INI, Java, JavaScript, JSON, Julia, Jupyter Notebook, Kotlin, Lua, Makefile, Markdown, MDX, MSBuild script, Nim, Nix, Objective-C, OCaml, Pascal, Perl, PHP, PowerShell, Protobuf, Python, R, Ruby, Rust, Scala, SCSS/Less, Shell, Solidity, SQL, Svelte, Swift, Terraform, Text, TOML, TypeScript, Visual Basic, Vue, XML, YAML, Zig

All non-table formats (Json, Html, Csv, Markdown) are written to stdout by default (so they can be piped, e.g. sloc . -f json | jq); pass --output <path> to write a file instead.

.gitignore files (including nested ones) are honored by default; pass --no-gitignore to disable. Save a JSON report and pass it to --baseline on a later run to see how line counts changed, or skip the saved report entirely and pass a commit/tree-ish to --compare-to. Diff output (from either --baseline or --compare-to) is only rendered as a console table or as JSON (-f json); other formats fall back to the table.

Exit Codes

Code	Meaning
0	Success
1	Path not found or unreadable, or invalid command-line arguments
2	A threshold (e.g. --min-comment-pct) was not met
3	Unexpected error

Sample Output

With --by-file (tree view per file):

Supported Languages

• Programming languages: C#, C# Designer, C, C++, Java, Kotlin, Swift, JavaScript, TypeScript, Python, Go, Rust, PHP, Ruby, F#, Visual Basic, Scala, Dart, R, Lua, Perl, Elixir, Haskell, Objective-C, Groovy, Julia, Clojure, BASIC, Pascal, Zig, Nim, OCaml, Erlang, Elm, D, Crystal, Solidity
• Web & templates: HTML, CSS, SCSS/Less, Vue, Svelte, Astro, MDX
• Data & config formats: JSON, YAML, XML, TOML, INI, Markdown, Protobuf, GraphQL
• Shell, build & infra: Shell, PowerShell, Batch, SQL, Makefile, Dockerfile, CMake, Terraform, Bazel/Starlark, Nix, MSBuild script
• Other: Assembly, Jupyter Notebook, Text

Files without an extension (e.g. Makefile, Dockerfile, CMakeLists.txt, Rakefile, Gemfile) are recognized by name.

Files with unknown extensions are grouped as Other when using --all, with only code lines and blank lines distinguished.

Building from Source

# Restore and build
dotnet build

# Run tests
dotnet test

# Pack as a NuGet tool package (output to ./nupkg)
dotnet pack src/Sloc.Cli/Sloc.Cli.csproj -c Release -o ./nupkg

# Install from local package and verify
dotnet tool install --global --add-source ./nupkg Sloc
sloc ./src

Known Limitations

• Line classification is based on text matching of comment symbols, not a full lexer.
• String literals are recognized for most languages, so comment markers inside strings (e.g. "// not a comment") are counted as code, and escaped quotes are handled, including C# verbatim strings (@"…""…"), C# raw string literals and Java text blocks ("""…"""), Rust raw strings (r"…", r#"…"#), and C++ raw strings (R"(…)"). Rust raw strings with more than one #, C# raw strings delimited by four or more quotes, and C++ raw strings with a custom delimiter (R"x(…)x") are not modeled, and interpolation expressions inside strings are not analyzed. C/C++ digit separators (1'000) are not mistaken for character literals.
• Lua long-bracket comments are recognized up to level 4 (--[====[ … ]====]), and Perl POD blocks only when opened by a common command (=pod, =head1–=head6, =over, =item, =back, =begin, =end, =for, =encoding) at column 0.
• JavaScript/TypeScript regex literals are recognized, so comment markers inside them (e.g. /\/*$/) are counted as code, and PHP 8 attributes (#[…]) are code rather than # comments.
• Python triple-quoted strings are counted as comments only when they begin a statement (docstrings, including r"""…"""/u"""…"""); used as a value (e.g. x = """…"""), inside brackets left open by an earlier line, or after a trailing \ line continuation they are counted as code.
• The complexity metric counts branch tokens textually, so a token that is not a branch in context still adds to it: TypeScript's optional-member ?: (name?: string), Rust's empty closure parameter list || (|| x), and C++'s rvalue/forwarding reference && (T&&).

License

This project is released under the MIT License.

---

<a id="中文"></a>

Sloc

English | 中文

Sloc（Source Lines Of Code）是一个用于统计源代码行数的 .NET 全局命令行工具。

功能特性

• 统计代码行 / 注释行 / 空行 / 总行数
• 正确处理单行注释、块注释以及跨多行的块注释
• 内置 66 种常见语言的注释规则（按文件扩展名或文件名自动识别，如 Makefile、Dockerfile、CMakeLists.txt）
• 递归扫描目录，支持 --include / --exclude glob 过滤
• 默认排除 bin、obj、artifacts、.git、.vs、.vscode、.idea、node_modules 等目录
• 五种输出格式：彩色表格（默认）、JSON、HTML、CSV 与 Markdown
• 表格输出新增注释健康度列，显示注释密度指标（无 / 低 / 一般 / 良好 / 较高 / 过密）
• 未指定 --format 时，可根据 --output 文件扩展名自动推断格式（.json → JSON，.html / .htm → HTML）
• 默认遵循 .gitignore 文件（含子目录中的；path 位于 git 仓库内时，也包括其上层直到仓库根目录的）；--no-gitignore 可禁用
• 跨 CPU 核心并行分析（--jobs），输出保持确定性
• 适配 CI：JSON 可输出到标准输出便于管道处理（例如 | jq）、提供有意义的退出码、以及 --min-comment-pct 阈值门禁
• 通过 --baseline 与已保存的 JSON 报告对比，或用 --compare-to 直接与另一个 commit 对比，查看行数变化
• 通过 --sort（支持按注释占比排序）/ --top 对语言汇总排序和限制条数
• 无法读取的文件或目录，以及二进制文件（通过 NUL 字节检测），会被自动跳过，并在最终结果中列出所有跳过的路径及原因（除 Csv 外的所有格式;CSV 保持为单张可机器解析的表格）

安装

通过 winget 安装（Windows）：

winget install coldhighsun.sloc

或作为 .NET 全局工具安装（需要 .NET 10 SDK）：

dotnet tool install --global Sloc

更新或卸载：

winget upgrade coldhighsun.sloc
winget uninstall coldhighsun.sloc

dotnet tool update --global Sloc
dotnet tool uninstall --global Sloc

使用方法

sloc <path> [options]

示例

# 统计当前目录（递归）
sloc .

# 统计指定目录
sloc ./src

# 统计单个文件
sloc ./src/Program.cs

# 仅统计 C# 文件
sloc ./src --include "**/*.cs"

# 排除测试目录
sloc . --exclude "**/tests/**"

# 显示逐文件明细
sloc ./src --by-file

# 以 JSON 格式输出
sloc ./src --format json

# 保存为 HTML 报告（可在浏览器中打开）
sloc ./src --format html --output report.html

# HTML 输出到标准输出（省略 --output 时的默认行为）
sloc ./src --format html

# 根据文件扩展名自动推断格式
sloc ./src --output sloc-report.json

# 包含未知扩展名的文件
sloc . --all

# 不递归子目录
sloc ./src --no-recursive

# 按名称排除任意深度的目录
sloc . --exclude-dir vendor

# 监视文件变化并实时刷新表格
sloc ./src --watch

# 内容字节完全相同的文件只计一次
sloc . --unique

# 将 JSON 通过管道传给 jq
sloc . --format json | jq .total

# 若注释占比低于 10% 则让 CI 失败
sloc . --min-comment-pct 10

# 保存基线，之后与后续运行对比
sloc . --format json --output baseline.json
sloc . --baseline baseline.json

# 直接与某个 commit 对比当前工作区，无需先保存基线文件
sloc . --compare-to HEAD~5

# 直接对比两个 commit，无需检出任何一个
sloc . --git-hash HEAD --compare-to main

# 分析某个 commit 时的树状态，无需检出
sloc . --git-hash v1.2.0

# 分析文本文件中逐行列出的文件列表
sloc --list-file files.txt

# 按注释行排序，仅显示前 5 种语言
sloc . --sort comment --top 5

# 按注释占比降序排序
sloc . --sort commentpct

# 生成同时包含语言汇总和逐文件明细的 Markdown 报告，输出到标准输出
sloc . --format markdown --detailed -o -

选项

选项	简写	说明
path（参数）		要分析的文件或目录，默认为当前目录 .。不带任何参数运行 sloc 时会显示帮助信息。
--list-file		分析该文件中逐行列出的文件列表,而不是扫描 path;用 - 表示从标准输入读取列表
--include	-i	要包含的文件 glob 模式，可多次指定
--exclude	-e	要排除的文件 glob 模式，可多次指定
--exclude-dir		要在任意深度排除的目录名(如 vendor);等价于 --exclude "**/<name>/**",可多次指定
--include-lang		要包含的语言显示名称(如 "C#"),大小写不敏感匹配;可多次指定
--exclude-lang		要排除的语言显示名称,大小写不敏感匹配;可多次指定
--unique		内容字节完全相同的文件只计一次;后出现的重复文件计入跳过列表
--format	-f	输出格式：Table（默认）、Json、Html、Csv 或 Markdown
--output	-o	Json / Html / Csv / Markdown 格式的输出文件路径；用 - 表示写到标准输出；未指定 --format 时根据文件扩展名自动推断格式
--no-recursive		不递归扫描子目录
--no-health		隐藏注释健康度列及百分比数据
--by-file		在语言汇总之外额外显示逐文件明细
--detailed		在 Json / Html / Markdown 输出中同时包含语言汇总和逐文件明细;在 Csv 输出中仅选择语言汇总(保持单张规范表格)
--paged	-p	显示分页输出
--all		包含扩展名未知的文件（归入 Other）
--quiet	-q	抑制横幅、进度 UI 和 Saved to 提示
--no-progress		抑制实时表格和进度条
--watch	-w	监视路径下的文件变化并自动重新分析,刷新表格(仅支持 Table 格式;按 Ctrl+C 停止)
--min-comment-pct		若整体注释占比低于该值,则失败(退出码 2)
--jobs	-j	并行分析的最大文件数(默认为处理器核数;1 表示串行)
--no-gitignore		不遵循 .gitignore 文件(默认遵循,包括 path 所在仓库中其上层目录的 .gitignore、仓库的 info/exclude 以及全局 core.excludesFile);同时会扫描子模块等嵌套仓库——默认情况下,path 位于仓库内时它们会被跳过(并列入跳过列表)
--no-gitattributes		不遵循 .gitattributes 文件(默认会排除标记为 linguist-vendored/linguist-generated 的文件,包括由 path 所在仓库中其上层目录的 .gitattributes 标记的)
--git-hash		分析仓库在该 commit/tree-ish 时的树状态,无需检出;path 作为仓库根目录;需要 git 在 PATH 中;符号链接与子模块条目会被跳过;带有 smudge 过滤器(如 Git LFS)或 working-tree-encoding 属性的文件会像检出时一样转换(Git LFS 可能会下载对象),过滤器失败的文件会被跳过;此模式下 --include/--exclude、--no-recursive、--follow-symlinks、--no-gitignore、--no-gitattributes 均不生效;与 --list-file 互斥
--follow-symlinks		包含符号链接/联接目录以及符号链接文件,而不是跳过它们;指向自身祖先目录(或包含祖先目录的目录)的循环链接仍会被跳过,目标已位于 path 内的链接同样跳过;经多个链接到达的同一文件只统计一次
--baseline		与之前保存的 JSON 报告对比,显示行数增减
--compare-to		将当前分析与 path 在另一个 commit/tree-ish 时的状态对比,无需检出该 commit 或先保存基线文件;需要 git 在 PATH 中;path 可以是目录或单个文件;该 commit 的文件会按与工作区相同的规则过滤(--include/--exclude、.gitignore、.gitattributes 等),未改动的文件差异为零;可与 --git-hash 组合直接对比两个 commit;与 --baseline、--watch、--list-file 互斥
--sort		语言汇总排序依据:Total(默认)、Code、Comment、Blank、Files、Name 或 CommentPct
--top		仅显示汇总中排名前 N 的语言
--no-update-check		不检查 GitHub 上是否有新版本(默认检查,超时时间为 2 秒)
--help	-h	显示帮助
--version		显示版本

支持的语言显示名称（用于 --include-lang/--exclude-lang）：

Assembly, Astro, BASIC, Batch, Bazel/Starlark, C, C#, C# Designer, C++, Clojure, CMake, Crystal, CSS, D, Dart, Dockerfile, Elixir, Elm, Erlang, F#, Go, GraphQL, Groovy, Haskell, HTML, INI, Java, JavaScript, JSON, Julia, Jupyter Notebook, Kotlin, Lua, Makefile, Markdown, MDX, MSBuild script, Nim, Nix, Objective-C, OCaml, Pascal, Perl, PHP, PowerShell, Protobuf, Python, R, Ruby, Rust, Scala, SCSS/Less, Shell, Solidity, SQL, Svelte, Swift, Terraform, Text, TOML, TypeScript, Visual Basic, Vue, XML, YAML, Zig

所有非表格格式(Json、Html、Csv、Markdown)默认都会输出到标准输出(便于管道处理,例如 sloc . -f json | jq);传入 --output <路径> 则写入文件。

默认遵循 .gitignore 文件(含子目录中的);传入 --no-gitignore 可禁用。先保存一份 JSON 报告,之后用 --baseline 传入即可查看行数变化,也可以跳过保存报告这一步,直接把 commit/tree-ish 传给 --compare-to。差异输出(无论来自 --baseline 还是 --compare-to)仅支持控制台表格或 JSON(-f json)输出;其它格式会回退为表格。

退出码

码	含义
0	成功
1	路径不存在或不可读,或命令行参数无效
2	未达到阈值(如 --min-comment-pct)
3	意外错误

输出示例

使用 --by-file 选项（按文件树形展示）：

支持的语言

• 编程语言：C#、C# Designer、C、C++、Java、Kotlin、Swift、JavaScript、TypeScript、Python、Go、Rust、PHP、Ruby、F#、Visual Basic、Scala、Dart、R、Lua、Perl、Elixir、Haskell、Objective-C、Groovy、Julia、Clojure、BASIC、Pascal、Zig、Nim、OCaml、Erlang、Elm、D、Crystal、Solidity
• 前端与模板：HTML、CSS、SCSS/Less、Vue、Svelte、Astro、MDX
• 数据与配置格式：JSON、YAML、XML、TOML、INI、Markdown、Protobuf、GraphQL
• 脚本、构建与基础设施：Shell、PowerShell、Batch、SQL、Makefile、Dockerfile、CMake、Terraform、Bazel/Starlark、Nix、MSBuild script
• 其他：Assembly、Jupyter Notebook、Text

无扩展名的文件（如 Makefile、Dockerfile、CMakeLists.txt、Rakefile、Gemfile）按文件名识别。

扩展名未知的文件在使用 --all 时会被归入 Other 类别，仅区分代码行与空行。

从源码构建

# 还原与构建
dotnet build

# 运行测试
dotnet test

# 打包为 NuGet 工具包（输出到 ./nupkg）
dotnet pack src/Sloc.Cli/Sloc.Cli.csproj -c Release -o ./nupkg

# 从本地包安装并验证
dotnet tool install --global --add-source ./nupkg Sloc
sloc ./src

已知限制

• 行的分类基于注释符号的文本匹配，不是完整的词法分析器。
• 大多数语言已识别字符串字面量，因此字符串内部的注释符号（例如 "// 这不是注释"）会被计为代码，转义引号也能正确处理，包括 C# 逐字字符串（@"…""…"）、C# 原始字符串与 Java 文本块（"""…"""）、Rust 原始字符串（r"…"、r#"…"#）以及 C++ 原始字符串（R"(…)"）。带多个 # 的 Rust 原始字符串、以四个及以上引号定界的 C# 原始字符串和带自定义定界符的 C++ 原始字符串（R"x(…)x"）暂不支持，字符串内的插值表达式也不做分析。C/C++ 数字分隔符（1'000）不会被误认为字符字面量。
• Lua 长括号注释最多识别到第 4 级（--[====[ … ]====]）；Perl POD 块仅在第 0 列以常见指令（=pod、=head1–=head6、=over、=item、=back、=begin、=end、=for、=encoding）开头时识别。
• 已识别 JavaScript/TypeScript 正则字面量，因此其中的注释符号（例如 /\/*$/）会被计为代码；PHP 8 属性（#[…]）计为代码，而不是 # 注释。
• Python 三引号字符串仅在作为语句开头（docstring，包括 r"""…"""/u"""…"""）时计为注释；作为值使用时（例如 x = """…"""）、位于前面行未闭合的括号内或跟在行尾 \ 续行之后时计为代码。
• 复杂度指标按文本统计分支记号，因此在上下文中并非分支的同名记号也会计入：TypeScript 可选成员的 ?:（name?: string）、Rust 空参数闭包的 ||（|| x）以及 C++ 右值/转发引用的 &&（T&&）。

许可证

本项目基于 MIT 许可证 发布。