Sloc 2.0.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. It analyzes files individually, distinguishing code lines, comment lines, and blank lines, then aggregates results by programming language. It supports 34 auto-detected languages, three output formats (table, JSON, HTML), per-file detail view, and comment health indicators.

Features

• Count code / comment / blank / total lines
• Correctly handles single-line comments, block comments, and multi-line block comments
• Built-in comment rules for 34 common languages (auto-detected by file extension)
• Recursive directory scanning with --include / --exclude glob filters
• Automatically excludes bin, obj, artifacts, .git, .vs, .vscode, .idea, node_modules, and similar directories by default
• Three output formats: colored table (default), JSON, and HTML
• 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) 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 to see how line counts changed
• Sort and limit the language summary with --sort / --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

Installation

Install via winget (Windows):

winget install coldhighsun.sloc

Or install as a .NET global tool (requires .NET 8 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 HTML report (opens in a browser)
sloc ./src --format html --output report.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

# 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

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

Options

Json output is written to stdout by default (so it can be piped, e.g. sloc . -f json | jq); pass --output 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.

Exit Codes

Sample Output

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

Supported Languages

C#, C/C++, Java, Kotlin, Swift, JavaScript, TypeScript, Python, Go, Rust, PHP, Ruby, F#, Visual Basic, SQL, PowerShell, Shell, YAML, JSON, HTML, XML, CSS, SCSS/Less, Dart, Scala, R, Lua, Perl, Elixir, Haskell, Objective-C, TOML, Markdown, Terraform.

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. Verbatim/doubled-quote escaping (e.g. C# @"…""…") is not modeled, and interpolation expressions inside strings are not analyzed.
• Python triple-quoted strings are counted as comments only when they begin a statement (docstrings); used as a value (e.g. x = """…""") they are counted as code.

License

This project is released under the MIT License.

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

Sloc

English | 中文

Sloc（Source Lines Of Code）是一个用于统计源代码行数的 .NET 全局命令行工具。它会逐文件分析代码，区分代码行、注释行和空行，并按编程语言进行聚合汇总，支持 34 种语言自动识别、三种输出格式（表格、JSON、HTML）、逐文件明细视图以及注释健康度指标。

功能特性

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

安装

通过 winget 安装（Windows）：

winget install coldhighsun.sloc

或作为 .NET 全局工具安装（需要 .NET 8 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

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

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

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

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

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

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

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

选项

Json 默认输出到标准输出(便于管道处理,例如 sloc . -f json | jq);传入 --output 则写入文件。

默认遵循 .gitignore 文件(含子目录中的);传入 --no-gitignore 可禁用。先保存一份 JSON 报告,之后用 --baseline 传入即可查看行数变化。

退出码

输出示例

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

支持的语言

C#、C/C++、Java、Kotlin、Swift、JavaScript、TypeScript、Python、Go、Rust、PHP、Ruby、F#、Visual Basic、SQL、PowerShell、Shell、YAML、JSON、HTML、XML、CSS、SCSS/Less、Dart、Scala、R、Lua、Perl、Elixir、Haskell、Objective-C、TOML、Markdown、Terraform。

扩展名未知的文件在使用 --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# 的 @"…""…"）暂不支持，字符串内的插值表达式也不做分析。
• Python 三引号字符串仅在作为语句开头（docstring）时计为注释；作为值使用时（例如 x = """…"""）计为代码。

许可证

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