cloc — Count Lines of Code Across Any Project

Introduction

cloc (Count Lines of Code) is a portable command-line utility that tallies blank lines, comment lines, and physical source lines across more than 250 programming languages. It is widely used in code audits, migration planning, and engineering dashboards.

What cloc Does

• Counts code, comments, and blank lines for 250+ languages
• Diffs two directory trees to show added, removed, and modified lines per language
• Processes files, directories, compressed archives, and git commit ranges
• Outputs plain text, JSON, XML, YAML, CSV, or SQL insert statements
• Filters by language, extension, directory, or custom regex

Architecture Overview

cloc is a single self-contained Perl script. It walks the file tree, identifies each file's language via extension tables and shebang heuristics, strips comments using language-specific regex rules, and accumulates per-language tallies. Diff mode pairs files between two trees and reports net changes. No daemon or database is involved.

Self-Hosting & Configuration

• Install via package manager (apt, brew, choco), npm, or download the standalone Perl script
• Runs as a one-shot CLI with no service or config file required
• Use a .clocignore file to exclude paths, similar to .gitignore
• Pass --exclude-dir, --exclude-lang, or --exclude-ext for fine-grained filtering
• Add custom language definitions with --read-lang-def or --force-lang-def

Key Features

• Zero-dependency single Perl file that runs on any OS with Perl installed
• Recognizes 250+ programming and markup languages out of the box
• Diff mode compares two codebases and reports net line changes per language
• Multiple output formats (JSON, YAML, XML, CSV, SQL) for CI pipeline integration
• Handles tar/zip archives and git commit ranges without manual extraction

Comparison with Similar Tools

• Tokei — Rust-based, significantly faster on large repos but fewer output format options
• scc — Go-based, adds COCOMO cost estimates and complexity metrics
• SLOCCount — Early predecessor to cloc, now unmaintained
• loc — Minimal Rust counter, fast but limited language coverage
• wc -l — Unix built-in that counts raw lines without language awareness

FAQ

Q: How accurate is cloc for polyglot repositories? A: cloc identifies languages by file extension and shebang lines. Ambiguous cases like .h files use heuristics. Override with --force-lang.

Q: Can cloc count lines inside a git history range? A: Yes. Use cloc --git --diff v1.0 v2.0 to compare two tags, branches, or commits.

Q: Does cloc count generated or vendored code? A: By default yes. Use --exclude-dir=vendor,node_modules or a .clocignore to skip them.

Q: How does cloc handle binary files? A: cloc auto-detects and skips binary files. Use --binary-check to tune the heuristic threshold.

Sources

• https://github.com/AlDanial/cloc
• https://cloc.sourceforge.net/