Cloc

CLOC for .NET Repositories

Trigger On

• the repo wants cloc
• the team needs repeatable LOC, language, or branch diff statistics for a .NET repo
• the user asks about C# codebase size, solution composition, or code-count deltas between refs

Value

• produce a concrete project delta: code, docs, config, tests, CI, or review artifact
• reduce ambiguity through explicit planning, verification, and final validation skills
• leave reusable project context so future tasks are faster and safer

Do Not Use For

• judging developer productivity from raw LOC
• replacing behavioral verification, architecture review, or complexity analysis
• counting generated or vendored files without an explicit reason

Inputs

• the nearest AGENTS.md
• target repository, solution, project, or subtree
• the question being answered: footprint, composition, diff, or trend

Quick Start

1. Read the nearest AGENTS.md and confirm scope and constraints. 2. Run this skill's Workflow through the Ralph Loop until outcomes are acceptable. 3. Return the Required Result Format with concrete artifacts and verification evidence.

Workflow

1. Choose the counting mode deliberately:

• --vcs=git for repo-respecting counts
• path-based counting for bounded folders
• --git --diff BASE HEAD for change deltas

2. Prefer .NET-relevant views first:

• C# footprint
• test versus production footprint
• solution language mix such as C#, Razor, XML, JSON, YAML, and MSBuild files

3. Exclude noise before trusting the numbers:

• bin
• obj
• .git
• vendored or generated folders when they are not part of the decision

4. Use machine-readable output when the numbers feed docs, CI, or follow-up automation:

• --json
• --csv
• --yaml
• --md

5. Treat cloc as a sizing and comparison tool, not as evidence that the design is good. 6. When using diff mode, compare named refs that match the review question:

• origin/main..HEAD
• release branch versus main
• before and after a refactor

7. After any code cleanup based on cloc findings, run the repo's normal quality pass.

Bootstrap When Missing

If cloc is not available yet:

1. Detect current state:

• command -v cloc
• cloc --version
• perl --version

2. Choose the install path deliberately:

• macOS with Homebrew: brew install cloc
• Debian or Ubuntu: sudo apt install cloc
• Red Hat or older Fedora family: sudo yum install cloc
• Fedora or newer Red Hat family: sudo dnf install cloc
• npm fallback: npm install -g cloc
• Windows with Chocolatey: choco install cloc
• Windows with Scoop: scoop install cloc
• Docker fallback: docker run --rm -v $PWD:/tmp aldanial/cloc .

3. If package-manager builds are not acceptable, install from the latest upstream release or source and verify with cloc --version. 4. Record exact counting commands in AGENTS.md, for example:

• cloc --vcs=git --include-lang="C#,MSBuild,JSON,XML,YAML"
• cloc --by-file --vcs=git --include-lang="C#"
• cloc --git --diff origin/main HEAD --include-lang="C#"

5. Run one bounded command and return status: configured or status: improved. 6. If the repo intentionally uses another code-count tool and does not want cloc, return status: not_applicable.

Deliver

• repeatable LOC and language-mix reporting for .NET repos
• explicit include and exclude rules
• branch-diff or bounded-scope commands that answer a concrete engineering question

Validate

• counts match the intended source boundary instead of including build output noise
• command choice matches the reporting question
• any automation or docs that consume the numbers can rerun the same command
• cloc is used as context, not as a substitute for tests or design review

Ralph Loop

Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.

1. Plan first (mandatory):

• analyze current state
• define target outcome, constraints, and risks
• write a detailed execution plan
• list final validation skills to run at the end, with order and reason

2. Execute one planned step and produce a concrete delta. 3. Review the result and capture findings with actionable next fixes. 4. Apply fixes in small batches and rerun the relevant checks or review steps. 5. Update the plan after each iteration. 6. Repeat until outcomes are acceptable or only explicit exceptions remain. 7. If a dependency is missing, bootstrap it or return status: not_applicable with explicit reason and fallback path.

Required Result Format

• status: complete | clean | improved | configured | not_applicable | blocked
• plan: concise plan and current iteration step
• actions_taken: concrete changes made
• validation_skills: final skills run, or skipped with reasons
• verification: commands, checks, or review evidence summary
• remaining: top unresolved items or none

For setup-only requests with no execution, return status: configured and exact next commands.

Load References

• references/commands.md
• references/examples.md
• references/cloc.md

Example Requests

• "Add cloc reporting to this .NET repo."
• "Compare code size between main and this branch."
• "Count C# versus test footprint in this solution."
• "Give me a machine-readable line-count report for CI."

cloc for .NET Repositories

What It Is

cloc counts blank lines, comment lines, and physical lines of code across many languages. In a .NET repository, it is useful for footprint reporting, solution composition, branch diffs, and bounded-scope comparisons.

Use it to answer specific questions, not to rate developer output.

Installation Paths

Use the official upstream install paths and keep the chosen command in AGENTS.md:

• macOS with Homebrew:

brew install cloc

• Debian or Ubuntu:

sudo apt install cloc

• Red Hat or older Fedora family:

sudo yum install cloc

• Fedora or newer Red Hat family:

sudo dnf install cloc

• npm fallback:

npm install -g cloc

• Windows with Chocolatey:

choco install cloc

• Windows with Scoop:

scoop install cloc

• Docker fallback:

docker run --rm -v $PWD:/tmp aldanial/cloc .

If package-manager builds are not acceptable, use the latest upstream release from AlDanial/cloc and verify:

cloc --version

Good Default Commands

Count tracked files in the current repository:

cloc --vcs=git

Count common .NET repo languages only:

cloc --vcs=git --include-lang="C#,MSBuild,JSON,XML,YAML"

Count only C# by file:

cloc --by-file --vcs=git --include-lang="C#"

Compare branch delta for C#:

cloc --git --diff origin/main HEAD --include-lang="C#"

Count a bounded subtree:

cloc src --include-lang="C#,MSBuild,JSON,XML,YAML"

Excludes That Usually Matter

Start with repo-respecting or explicit excludes so the numbers are not polluted by build artifacts:

• bin
• obj
• .git
• vendored folders
• generated folders when they are not part of the question

Example:

cloc . --exclude-dir=bin,obj,.git

Output Modes

Use machine-readable output when the numbers feed docs or automation:

• --json
• --csv
• --yaml
• --md
• --xml

Example:

cloc --vcs=git --include-lang="C#" --json

When It Helps

Use cloc when you need:

• a quick footprint of production versus test code
• a branch-to-branch size diff after a refactor
• a codebase language mix for docs or governance
• a stable command that humans and CI can rerun

When It Does Not Help

Do not use cloc to conclude that:

• a larger change is better or worse by itself
• a smaller file is automatically simpler
• test quality is good because test LOC is high

Pair cloc with the repo's real verification flow: tests, analyzers, architecture checks, and maintainability review.

CLOC CLI Commands Reference

Basic Counting

# Count all files in current directory
cloc .

# Count with Git awareness (respects .gitignore)
cloc --vcs=git

# Count specific directory or file
cloc src/
cloc src/MyProject.cs

Language Filtering

# .NET-focused counting
cloc --vcs=git --include-lang="C#,MSBuild,JSON,XML,YAML"

# C# only
cloc --vcs=git --include-lang="C#"

# Razor and web files
cloc --vcs=git --include-lang="C#,Razor,CSS,JavaScript,TypeScript"

# Exclude specific languages
cloc --vcs=git --exclude-lang="Markdown,Text"

Directory and File Exclusions

# Exclude build output directories
cloc --vcs=git --exclude-dir=bin,obj

# Exclude vendored or generated folders
cloc --vcs=git --exclude-dir=bin,obj,node_modules,packages,.nuget

# Exclude test directories
cloc --vcs=git --exclude-dir=bin,obj,tests,test

# Exclude by file extension
cloc --vcs=git --exclude-ext=Designer.cs,g.cs

Output Formats

# JSON output
cloc --vcs=git --json

# JSON to file
cloc --vcs=git --json --report-file=cloc-report.json

# CSV output
cloc --vcs=git --csv

# YAML output
cloc --vcs=git --yaml

# Markdown output
cloc --vcs=git --md

# SQL output for database import
cloc --vcs=git --sql=1 --sql-project=MyProject

Detailed File Reports

# Report by file
cloc --vcs=git --by-file

# Report by file with percentages
cloc --vcs=git --by-file --by-percent c

# Sort by code lines descending
cloc --vcs=git --by-file --sort=code

# Show only top N files
cloc --vcs=git --by-file | head -50

Git Diff Counting

# Diff between branches
cloc --git --diff origin/main HEAD

# Diff with language filter
cloc --git --diff origin/main HEAD --include-lang="C#"

# Diff between specific commits
cloc --git --diff abc1234 def5678

# Diff between tags
cloc --git --diff v1.0.0 v2.0.0

# Diff output as JSON
cloc --git --diff origin/main HEAD --json

Solution and Project Scope

# Count a specific solution
cloc MySolution.sln

# Count multiple projects
cloc src/Project1/ src/Project2/

# Count with solution file and exclusions
cloc --vcs=git --exclude-dir=bin,obj,tests src/

Advanced Options

# Skip duplicate files
cloc --vcs=git --skip-uniqueness

# Force language detection
cloc --vcs=git --force-lang="C#",cs

# Show processing progress
cloc --vcs=git --progress-rate=10

# Count blank lines and comments separately
cloc --vcs=git --by-file-by-lang

# Ignore whitespace differences in diff
cloc --git --diff origin/main HEAD --ignore-whitespace

# Use multiple cores for faster counting
cloc --vcs=git --processes=4

Verification Commands

# Check cloc installation
command -v cloc

# Show version
cloc --version

# Show help
cloc --help

# List recognized languages
cloc --show-lang

# Show language extensions
cloc --show-ext

CI/CD Integration

# JSON output for parsing in CI
cloc --vcs=git --json --quiet > cloc-results.json

# Quiet mode (suppress header)
cloc --vcs=git --quiet

# Exit with error if threshold exceeded
cloc --vcs=git --json | jq '.SUM.code' | xargs -I {} test {} -lt 100000

# Save to artifact
cloc --vcs=git --md --report-file=code-metrics.md

CLOC Usage Examples for .NET Repositories

Scenario: Initial Codebase Assessment

Goal: Understand the size and composition of a .NET solution.

# Full language breakdown
cloc --vcs=git --exclude-dir=bin,obj

# Sample output:
#      Language          files     blank   comment      code
# ---------------------------------------------------------
#      C#                  142      3200      1850     18500
#      MSBuild              15       120        80       890
#      JSON                 12        50         0       420
#      XML                   8        30        10       280
#      YAML                  5        20         5       150
# ---------------------------------------------------------
#      SUM:                182      3420      1945     20240

Scenario: Test vs Production Code Ratio

Goal: Compare test code to production code.

# Count production code
cloc --vcs=git --exclude-dir=bin,obj,tests,test,Tests,Test,*.Tests,*.Test --include-lang="C#"

# Count test code only
cloc --vcs=git --exclude-dir=bin,obj --include-lang="C#" tests/ src/*.Tests/

Analysis approach: 1. Run both commands 2. Compare code line counts 3. Typical healthy ratio is 1:1 to 2:1 (production to test)

Scenario: PR Size Assessment

Goal: Quantify changes in a pull request.

# Compare current branch to main
cloc --git --diff origin/main HEAD --include-lang="C#,MSBuild,JSON"

# Sample output:
#                    same  modified  added  removed
# ------------------------------------------------
# C#                  150        12     45       20
# MSBuild               8         2      1        0
# JSON                  5         1      3        0
# ------------------------------------------------
# SUM:                163        15     49       20

Interpretation:

• same: files unchanged
• modified: files with changes
• added: new lines added
• removed: lines deleted

Scenario: Release-to-Release Comparison

Goal: Measure growth between releases.

# Compare two tagged releases
cloc --git --diff v1.0.0 v2.0.0 --include-lang="C#" --json > release-diff.json

# Extract summary
cat release-diff.json | jq '.SUM'

Scenario: Identify Largest Files

Goal: Find files that might need refactoring.

# List all C# files by size
cloc --vcs=git --by-file --include-lang="C#" --exclude-dir=bin,obj | sort -t'|' -k4 -nr | head -20

# Alternative with JSON processing
cloc --vcs=git --by-file --include-lang="C#" --json | jq '.[] | select(.language == "C#") | {file: .file, code: .code}' | sort -t':' -k2 -nr

Scenario: Solution Composition Report

Goal: Document the technology mix for architecture review.

# Generate markdown report
cloc --vcs=git --exclude-dir=bin,obj,node_modules --md --report-file=codebase-composition.md

# Include in docs or PR description
cat codebase-composition.md

Scenario: CI Pipeline Metrics

Goal: Track code size over time in CI.

# GitHub Actions example
- name: Generate code metrics
  run: |
    cloc --vcs=git --json --exclude-dir=bin,obj > cloc-report.json
    echo "Total lines: $(jq '.SUM.code' cloc-report.json)"

- name: Upload metrics artifact
  uses: actions/upload-artifact@v7
  with:
    name: code-metrics
    path: cloc-report.json

Scenario: Pre-Refactor Baseline

Goal: Establish metrics before a major refactoring effort.

# Create baseline snapshot
cloc --vcs=git --by-file --include-lang="C#" --json > baseline-before-refactor.json

# After refactoring, compare
cloc --vcs=git --by-file --include-lang="C#" --json > baseline-after-refactor.json

# Diff the reports
diff <(jq '.SUM' baseline-before-refactor.json) <(jq '.SUM' baseline-after-refactor.json)

Scenario: Exclude Generated Code

Goal: Count only hand-written code.

# Exclude common generated file patterns
cloc --vcs=git --exclude-dir=bin,obj,Generated,Migrations \
     --not-match-f='\.Designer\.cs$|\.g\.cs$|\.generated\.cs$' \
     --include-lang="C#"

Scenario: Multi-Project Solution Analysis

Goal: Compare sizes across projects in a solution.

# Count each project directory separately
for dir in src/*/; do
    echo "=== $dir ==="
    cloc --vcs=git "$dir" --include-lang="C#" --quiet
done

Scenario: Documentation Coverage Assessment

Goal: Compare documentation to code volume.

# Count documentation files
cloc --vcs=git --include-lang="Markdown,XML" docs/ README.md

# Count code files
cloc --vcs=git --include-lang="C#" src/

# Calculate ratio manually or with script

Scenario: Verify Cleanup Success

Goal: Confirm dead code removal reduced codebase size.

# Before cleanup (commit hash: abc1234)
git stash
git checkout abc1234
cloc --vcs=git --include-lang="C#" --json > before-cleanup.json

# After cleanup (current HEAD)
git checkout -
git stash pop
cloc --vcs=git --include-lang="C#" --json > after-cleanup.json

# Compare
echo "Before: $(jq '.SUM.code' before-cleanup.json) lines"
echo "After: $(jq '.SUM.code' after-cleanup.json) lines"

Scenario: Excluding Specific Vendored Libraries

Goal: Count only first-party code.

# Exclude vendored directories
cloc --vcs=git \
     --exclude-dir=bin,obj,vendor,external,third-party,packages \
     --include-lang="C#,MSBuild"

Scenario: Quick Health Check

Goal: Fast assessment of repo state for code review.

# One-liner summary
cloc --vcs=git --quiet --exclude-dir=bin,obj | tail -n 5