Cloc's totals depend on what you ask it to count
Cloc separates physical source lines, comments and blanks into a language report. Pointing it at a repository can answer a useful maintenance question: what source is here, and how has that inventory changed? The answer becomes less useful if generated files enter one report and disappear from the next.
The README documents directory exclusions, Git-based file selection and per-file output. Those controls are the reason to consider cloc for an inventory. Before adopting a total as a baseline, decide whether vendored code and generated assets belong in it. The counting command should preserve that decision alongside the report.
Physical lines also need a careful label. Reformatting a file can change its line count without adding behavior. A repository inventory is useful context for a migration or cleanup, but the total alone cannot establish engineering effort, maintainability or the value of a contributor's work.
What happened when we ran it
The October 29, 2026 lab record contains no execution result for cloc at commit f46c2c1: Perl was outside the harness's supported ecosystems. We did not run it, and have no installation duration, build result, passing-test count or throughput measurement to report. The scan did find a Dockerfile.
The recorded sandbox configuration listed 3 CPUs and 8 GB RAM, with the image field marked n/a. Neither that configuration nor the Dockerfile establishes a working deployment route. This boundary belongs to our harness, so it would be wrong to describe the missing run as a cloc failure.
The documentation describes a Perl source route, a Windows executable and Docker. These give a prospective user places to start, without supplying an independently verified setup outcome here. Choose the route you intend to use and check a small set of files whose expected classification you can inspect by hand.
Keep file selection with the report
Cloc's documented --vcs=git option invokes Git to obtain a file list. --exclude-dir omits named directories, while --by-file exposes individual results. That combination gives you a way to investigate a surprising total instead of accepting the language summary as a complete explanation.
For a tracked-source inventory, the following is a documentation-based starting point, not a command reproduced in our lab:
cloc --vcs=git --exclude-dir=vendor,dist --by-file --json
Here, excluding vendor and dist is an example policy. Use the directories that match your repository and intended question. If the review is about everything you distribute, excluding vendored code may be inappropriate. Check the file list before deciding the command answers your question.
The README also documents duplicate-file handling and an option to skip its uniqueness check. Identical copies can therefore affect how you interpret the output. Keep that policy stable when comparing snapshots, along with the cloc version and selected revision. Otherwise a change in counting rules can look like a change in source size.
Embedded languages and docstrings can change the interpretation
The limitations section says embedded languages are not recognized: JavaScript inside an HTML file is counted entirely as HTML. For a project with substantial inline scripts, the language report therefore describes cloc's classification of files rather than a precise division of every language used within them.
Python docstrings create another explicit boundary. By default cloc treats all docstrings as comments, and --docstring-as-code treats all of them as code. It does not infer their meaning from context. Choose a convention that matches the report's purpose and record it, especially if someone will compare the result with another counter.
The README warns about comment markers inside strings and nested comments, and says cloc does not parse the languages it counts. These are substantive reasons to walk away if an audit demands syntax-aware accuracy. For an approximate inventory, they are reasons to inspect representative tricky files before trusting the aggregate.
Comparison mode is useful when the rules stay fixed
Cloc documents comparing two versions of a codebase and reporting differences in blank, comment and source lines. That can support a review of repository changes if the inputs and exclusions stay consistent. It does not tell you whether an added line is useful, whether a deletion removed a defect or whether a rewrite is easier to maintain.
Tokei is worth evaluating when code counting needs to live inside another application: its README documents a library interface. scc adds complexity and cost estimates to counting. Neither alternative has a comparative result in this review. Use the same representative files to judge classification differences, rather than treating unlike totals as evidence that one counter is faster or more accurate.
Recent maintenance does not replace an accuracy check
GitHub recorded cloc's last push on October 26, 2026. The recent activity feed included parsing-related issues and pull requests updated that day. The latest release endpoint returned v2.10, published July 4, 2026. The later push and issue activity provide evidence of work beyond that release, without establishing that every reported parsing problem is fixed.
Documentation receives 4 on an editorial scale where 1 means major practical omissions, 3 means usable guidance with material gaps, and 5 means detailed guidance independently corroborated within the assessed scope. The README explains both controls and known counting limitations. Setup, community support and operational maturity remain unassessed, rather than receiving invented middle scores.
Save the chosen revision, exclusions and docstring policy with your first report. When a later total changes unexpectedly, inspect the affected files before turning the number into a claim about the project.