Convert Code Line Counter Data: CSV Metrics Minus Mistakes

Why does your meticulously counted lines-of-code data turn into an unreadable mess the moment you try to put it in a spreadsheet?

You ran your line counter. You got numbers. You pasted them into Excel. And now you're staring at a single column that says src/main.js:342 repeated four hundred times, with no headers, no structure, and your sprint review is in forty minutes. Sound familiar?

Here's the thing most code metrics guides won't tell you: the line counter isn't broken. Your conversion pipeline is. Raw output from tools like cloc, scc, or tokei is designed for terminal reading, not for the CSV ingest your metrics dashboard actually needs. And that gap—between what the tool spits out and what your stakeholder reporting pipeline can digest—is where engineering managers lose entire afternoons.

Let's fix that. From scratch, mistake by mistake.

What does raw code line counter output actually look like?

Run cloc src/ on a mid-sized TypeScript project and you'll get something like this:

Language: TypeScript
files: 47
blank: 612
comment: 389
code: 4,218

Pretty in the terminal. Useless in a spreadsheet. The first mistake people make is copy-pasting terminal output directly into a file and calling it a CSV. It's not. It's formatted text with colons, inconsistent spacing, and no delimiter strategy. When Excel opens it, everything collapses into column A because there's no comma separating values.

The fix is simple but non-obvious: most line counters have a built-in output flag you're probably ignoring.

The flags you should be using

Here are the ones that matter for CSV conversion:

• cloc: --csv or --json (JSON is actually better, more on that in a moment)
• scc: -f csv or --format csv
• tokei: -o csv or -o json

So cloc src/ --csv > metrics.csv gives you actual comma-separated data. But here's mistake number two: the default CSV output often omits metadata you need for trend tracking—like the timestamp, the commit hash, or the repository name. Without those, you're collecting snapshots with no way to sequence them into a time series.

How do I structure CSV columns for actual software development metrics?

This is where most engineering managers face-plant. They export the raw CSV, dump it into a dashboard, and wonder why their "code velocity" chart looks like a heart monitor. The problem isn't the chart. It's the schema.

Here's the mistake: treating line count as a single flat metric. Lines of code is not one number. It's a composite. And your CSV needs to reflect that composition or your downstream analysis will be meaningless.

The column schema that actually works

For sprint-level code metrics tracking on a legacy codebase, your CSV should have these columns at minimum:

date,commit_hash,repo,language,file_path,blank_lines,comment_lines,code_lines,total_lines,complexity_score

Let's break down why each matters, especially if you're managing a codebase that's been through three teams and two rewrites:

• date: Without this, you can't build a trend line. Use ISO 8601 (2024-01-15), not your locale's format. Excel mangles dates otherwise.
• commit_hash: This anchors your line count to a specific code state. Critical for answering "which commit caused the codebase to balloon by 2,000 lines?"
• language: Legacy codebases are polyglot. If you're not separating TypeScript from SQL migrations from YAML configs, your "code growth" metric is lying to you.
• file_path: Aggregate-level numbers hide problem files. You need file-level granularity to spot the utils.js that's grown to 3,400 lines across six sprints.

Why does JSON output give me better CSV data than the CSV flag?

This sounds backwards, right? Why would JSON produce better CSV? Here's the answer: structured data lets you control the transformation.

When you use --csv, the tool decides the schema. When you use --json, you decide the schema. And for code metrics, you need control because you're almost certainly merging data from multiple sources.

Here's a concrete example. Run cloc src/ --json and you get a nested structure. A fifteen-line Python script converts it into exactly the CSV schema defined above:

import json, csv, sys
from datetime import date

data = json.load(sys.stdin)
writer = csv.writer(sys.stdout)
writer.writerow(['date','repo','language','file_path','code_lines','blank_lines','comment_lines'])

today = date.today().isoformat()
for lang, stats in data.items():
    if lang not in ('header', 'SUM'):
        for filepath, fstats in stats.get('files', {}).items():
            writer.writerow([today, 'my-repo', lang, filepath, fstats['code'], fstats['blank'], fstats['comment']])

That script takes thirty seconds to write and saves you from manually cleaning CSV exports every sprint. The mistake here would be doing this conversion by hand in Excel each time. If you're running line counts more than once a month, automate it. Your future self will thank you during quarterly reviews.

How do I merge multiple line counter runs into a single CSV for trend analysis?

So you've been good. You've been running your line counter every Friday for three months. You have twelve CSV files. Now what?

Mistake number three: opening each file and copy-pasting rows into a master spreadsheet. Beyond being soul-crushing, this introduces human error. A stray paste offset, a deleted header row, a date entered as 15/01/24 instead of 2024-01-15—any of these corrupts your time series.

The fix is a simple concatenation script that preserves headers only from the first file:

head -n 1 first_run.csv > merged_metrics.csv
for f in *.csv; do tail -n +2 "$f" >> merged_metrics.csv; done

Two lines. Handles twelve files or twelve hundred. The tail -n +2 skips the header row on every file except the first, so you get clean, continuous data.

Now you can import merged_metrics.csv into whatever dashboard tool your org uses—Metabase, Grafana, even a pivot table in Excel—and actually see code growth trends over time.

What's the biggest mistake when using line count CSVs for engineering metrics?

Here's the one that bites everyone eventually: equating more lines of code with more productivity.

You've built a clean CSV pipeline. Your dashboard shows code lines increasing 15% sprint over sprint. Leadership is thrilled. But nobody noticed that 4,200 of those new lines are generated boilerplate from a schema change, and actual hand-written logic decreased by 800 lines.

The fix isn't in the CSV format. It's in how you contextualize the data. Your CSV should include a generated_flag column—marking files that are auto-generated—so you can filter them out when calculating human-authored code metrics. Without that filter, you're measuring file generation, not engineering output.

Run your line counter with file exclusion patterns: cloc src/ --exclude-dir=node_modules,dist,generated --csv. This strips the noise before it ever reaches your spreadsheet.

Code metrics only matter when they measure something real. A well-structured CSV makes that possible. A poorly structured one makes it look like you're measuring something real when you're actually just counting noise.