cloc

cloc (Count Lines of Code) is a command-line tool that counts lines of source code in files and directories across many programming languages. This npm package provides an easy way to install and use the popular cloc tool by Al Danial through npm/npx without requiring manual downloads or Perl environment setup.

Package Information

• Package Name: cloc
• Package Type: npm
• Language: Perl (distributed via npm)
• Installation: npm install -g cloc or use npx cloc
• Requirements: Perl runtime environment

Core Imports

This package provides a binary rather than a programming API. Access the tool through command-line execution:

# Using npx (recommended)
npx cloc [options] <files/directories>

# Global installation
npm install -g cloc
cloc [options] <files/directories>

# Local installation  
npm install cloc
./node_modules/.bin/cloc [options] <files/directories>

Basic Usage

# Count lines in current directory
npx cloc .

# Count lines in specific files
npx cloc src/main.js src/utils.js

# Count lines with specific language
npx cloc --include-lang=JavaScript .

# Generate JSON output
npx cloc --json . > report.json

# Compare two directories
npx cloc --diff old-version/ new-version/

Capabilities

Line Counting

Count physical lines of source code in files and directories, with automatic language detection and support for compressed archives.

cloc [options] <file(s)/dir(s)/git hash(es)> | <set 1> <set 2> | <report files>

Input Options:

• --extract-with=<cmd>: Custom extraction command for binary archives
• --list-file=<file>: Read file/directory names from file (one per line)
• --diff-list-file=<file>: File pairs for diff analysis matching --diff-alignment output
• --diff-list-files <file1> <file2>: Compute differences between files listed in two files
• --vcs=<VCS>: Invoke version control system to get file list (git, svn, auto)
• --unicode: Check binary files for Unicode expanded ASCII text

Processing Options:

• --autoconf: Count .in files processed by GNU autoconf
• --by-file: Report results for every source file encountered
• --by-file-by-lang: Report results per file and per language
• --config <file>: Read command line switches from configuration file
• --count-and-diff <set1> <set2>: Count and diff two sets of files
• --diff <set1> <set2>: Compute code and comment differences between sets
• --diff-timeout <N>: Ignore files taking more than N seconds to process (default: 10)
• --docstring-as-code: Count docstrings as code instead of comments
• --follow-links: Follow symbolic links to directories (Unix only)
• --force-lang=<lang>[,<ext>]: Process files with extension as specified language
• --force-lang-def=<file>: Load custom language processing filters
• --git: Interpret inputs as git targets (commit hashes, branch names)
• --git-diff-rel: Git diff strategy comparing only changed files
• --git-diff-all: Git diff strategy comparing all repository files
• --ignore-whitespace: Ignore horizontal whitespace when comparing files
• --ignore-case: Ignore case changes when comparing files with --diff
• --ignore-case-ext: Ignore case of file name extensions
• --lang-no-ext=<lang>: Count extensionless files using specified language counter
• --max-file-size=<MB>: Skip files larger than specified megabytes (default: 100)
• --no-autogen[=list]: Ignore auto-generated files (run with 'list' to see patterns)
• --no-recurse: Count files without recursively descending directories
• --original-dir: Write stripped files to same directory as originals
• --read-binary-files: Process binary files in addition to text files
• --read-lang-def=<file>: Load additional language processing filters
• --script-lang=<lang>,<s>: Process #! scripts with specified language counter
• --sdir=<dir>: Use custom scratch directory instead of system temp
• --skip-leading=<N[,ext]>: Skip first N lines of files, optionally by extension
• --skip-uniqueness: Skip file uniqueness check for performance boost
• --stat: Force directory stat for correct counts on certain filesystems
• --stdin-name=<file>: Specify filename for standard input language detection
• --strip-comments=<ext>: Write comment-stripped versions with specified extension
• --strip-str-comments: Replace embedded comment markers in strings with 'xx'
• --sum-reports: Sum data from multiple report files
• --timeout <N>: Ignore files taking more than N seconds at filter stages
• --processes=NUM: Set maximum cores for multiprocessing (Unix only, default: 0)
• --unix: Force Unix operating system mode
• --use-sloccount: Use SLOCCount compiled executables when available
• --windows: Force Microsoft Windows operating system mode

Filter Options:

• --exclude-content=<regex>: Exclude files containing text matching regex
• --exclude-dir=<D1>[,D2,...]: Exclude specified directories from scanning
• --exclude-ext=<ext1>[,<ext2>[...]]: Exclude files with specified extensions
• --exclude-lang=<L1>[,L2[...]]: Exclude specified languages from counting
• --exclude-list-file=<file>: Ignore files/directories listed in file
• --fullpath: Include full path in regex matching for --match-f, --not-match-f, --not-match-d
• --include-ext=<ext1>[,ext2[...]]: Count only files with specified extensions
• --include-lang=<L1>[,L2[...]]: Count only specified languages
• --match-d=<regex>: Count only files in directories matching Perl regex
• --not-match-d=<regex>: Exclude files in directories matching Perl regex
• --match-f=<regex>: Count only files whose basenames match Perl regex
• --not-match-f=<regex>: Exclude files whose basenames match Perl regex
• --skip-archive=<regex>: Ignore archives ending with specified Perl regex
• --skip-win-hidden: Skip hidden files on Windows

Debug Options:

• --categorized=<file>: Save categorized file names to file
• --counted=<file>: Save processed source file names to file
• --diff-alignment=<file>: Write file pair alignment information for --diff
• --explain=<lang>: Print comment removal filters for language and exit
• --help: Print usage information and exit
• --found=<file>: Save all found file names to file
• --ignored=<file>: Save ignored files and reasons to file
• --print-filter-stages: Print source code before/after each filter application
• --show-ext[=<ext>]: Print information about file extensions and exit
• --show-lang[=<lang>]: Print information about languages and exit
• --show-os: Print operating system mode value and exit
• -v[=<n>], --verbose[=<n>]: Verbose output with optional numeric level
• --version: Print program version and exit
• --write-lang-def=<file>: Write language processing filters to file and exit
• --write-lang-def-incl-dup=<file>: Write language filters including duplicates

Output Options:

• --3: Print third-generation language output
• --by-percent X: Show percentages instead of counts (X: c, cm, cb, cmb)
• --csv: Output results as comma separated values
• --csv-delimiter=<C>: Use custom character as CSV delimiter
• --file-encoding=<E>: Write output files using specified encoding
• --hide-rate: Hide line and file processing rates from output header
• --json: Output results as JSON formatted data
• --md: Output results as Markdown formatted text
• --out=<file>, --report-file=<file>: Write results to file instead of STDOUT
• --progress-rate=<n>: Show progress update every n files (default: 100, 0=suppress)
• --quiet: Suppress all information messages except final report
• --summary-cutoff=X:N: Aggregate results below threshold to 'Other' category
• --sql=<file>: Write results as SQL statements for database import
• --sql-append: Append SQL statements without table creation
• --sql-project=<name>: Use specified name as SQL project identifier
• --sql-style=<style>: Write SQL in specified style (Oracle, Named_Columns)
• --sum-one: Show SUM output line even for single input file
• --xml: Output results in XML format
• --xsl=<file>: Reference XSL stylesheet in XML output (1=default stylesheet)
• --yaml: Output results in YAML format

Usage Examples

Basic File Counting:

# Count lines in current directory
npx cloc .

# Count specific file types only
npx cloc --include-ext=js,ts src/

# Exclude test directories
npx cloc --exclude-dir=test,tests,__tests__ .

# Count with detailed per-file output
npx cloc --by-file src/

Git Integration:

# Count lines in git repository
npx cloc --vcs=git

# Compare two git commits
npx cloc --git --diff HEAD~1 HEAD

# Count lines at specific commit
npx cloc --git abc123def

Output Formats:

# JSON output for programmatic use
npx cloc --json . > lines-report.json

# CSV output for spreadsheet analysis  
npx cloc --csv . > lines-report.csv

# Markdown output for documentation
npx cloc --md . > LINES.md

# XML output with custom stylesheet
npx cloc --xml --xsl=mystyle.xsl . > report.xml

Advanced Filtering:

# Only count JavaScript and TypeScript
npx cloc --include-lang="JavaScript,TypeScript" src/

# Exclude auto-generated files
npx cloc --no-autogen .

# Skip large files (over 50MB)
npx cloc --max-file-size=50 .

# Custom language for specific extensions
npx cloc --force-lang="JavaScript,jsx" src/

Diff Analysis:

# Compare two directories
npx cloc --diff old-version/ new-version/

# Compare while ignoring whitespace
npx cloc --diff --ignore-whitespace v1/ v2/

# Count and diff in one operation
npx cloc --count-and-diff src-old/ src-new/

Exit Codes

# Exit codes returned by cloc command
0    # Success - counting completed normally
≠0   # Error conditions (file access, parsing errors, etc.)

Supported Languages

cloc automatically detects and counts lines for hundreds of programming languages including:

Popular Languages: JavaScript, TypeScript, Python, Java, C, C++, C#, Go, Rust, PHP, Ruby, Swift, Kotlin, Scala, HTML, CSS, SQL, Shell scripts, PowerShell, Perl, R, MATLAB, and many more.

Configuration Files: JSON, YAML, XML, TOML, INI, Properties files

Markup & Documentation: Markdown, reStructuredText, LaTeX, DocBook

Build Systems: Makefiles, CMake, Gradle, Maven POM, npm package.json

Database: SQL variants, stored procedures, triggers

Language detection uses file extensions, shebang lines, and content analysis. Use npx cloc --show-lang to see all supported languages or npx cloc --show-ext to see recognized file extensions.

Types

Command Line Interface

# Primary command interface
cloc [options] <inputs>

# Input types supported:
<inputs> ::= <file> | <directory> | <archive> | <git-hash> | <git-branch>

# Archive formats supported: .tar, .tar.gz, .tar.bz2, .tar.xz, .zip, .7z, .Z

# Git integration supports:
<git-hash>   # Commit SHA hashes  
<git-branch> # Branch names
<git-tag>    # Tag names

Output Structure

Default Text Output:

<files>  <blank>  <comment>  <code>  <language>
     ------   -----    -------    ----    --------
          5      10         25     180    JavaScript
          2       5         12      89    TypeScript
     ------   -----    -------    ----    --------
     SUM:      7      15         37     269

JSON Output Structure:

{
  "<language>": {
    "nFiles": <number>,
    "blank": <number>, 
    "comment": <number>,
    "code": <number>
  },
  "SUM": {
    "nFiles": <number>,
    "blank": <number>,
    "comment": <number>, 
    "code": <number>
  }
}

CSV Output: Files, blank lines, comment lines, code lines, language (one row per language)

XML/YAML: Structured equivalents of JSON format with appropriate syntax