# 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:

```bash
brew install cloc
```

- Debian or Ubuntu:

```bash
sudo apt install cloc
```

- Red Hat or older Fedora family:

```bash
sudo yum install cloc
```

- Fedora or newer Red Hat family:

```bash
sudo dnf install cloc
```

- npm fallback:

```bash
npm install -g cloc
```

- Windows with Chocolatey:

```powershell
choco install cloc
```

- Windows with Scoop:

```powershell
scoop install cloc
```

- Docker fallback:

```bash
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:

```bash
cloc --version
```

## Good Default Commands

Count tracked files in the current repository:

```bash
cloc --vcs=git
```

Count common .NET repo languages only:

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

Count only C# by file:

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

Compare branch delta for C#:

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

Count a bounded subtree:

```bash
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:

```bash
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:

```bash
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

```bash
# 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

```bash
# .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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```yaml
# 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@v4
  with:
    name: code-metrics
    path: cloc-report.json
```

## Scenario: Pre-Refactor Baseline

Goal: Establish metrics before a major refactoring effort.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

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