gh-dhofheinz-open-plugins-plugins-git-commit-assistant/commands/commit-analysis/file-stats.md

description

description
Get detailed file change statistics for commit analysis

Operation: File Statistics

Retrieve detailed statistics about file changes including counts, line changes, and file types.

Parameters from $ARGUMENTS

Optional parameters:

• format:json|text - Output format (default: text)
• detailed:true|false - Include per-file breakdown (default: false)

Workflow

Step 1: Verify Repository

git rev-parse --git-dir 2>/dev/null

Step 2: Collect File Statistics

# Get file status
git status --short

# Get statistics
git diff --stat HEAD

# Get detailed stats per file
git diff --numstat HEAD

# Count file types
git diff --name-only HEAD | wc -l

Step 3: Categorize Files

Group files by status and type:

By Status:

• New files (A)
• Modified files (M)
• Deleted files (D)
• Renamed files (R)

By Type:

• Source code (.js, .ts, .py, .java, etc.)
• Tests (.test.js, .spec.ts, _test.py, etc.)
• Documentation (.md, .txt)
• Configuration (.json, .yml, .toml, .config.js)
• Styles (.css, .scss, .less)

Step 4: Calculate Metrics

METRICS:
- Total files changed
- Total insertions (lines added)
- Total deletions (lines removed)
- Net change (insertions - deletions)
- Largest files (by lines changed)
- Files by type distribution
- New vs Modified vs Deleted ratio

Step 5: Format Statistics Report

Text Format (default):

FILE STATISTICS
═══════════════════════════════════════════════

OVERVIEW:
───────────────────────────────────────────────
Total Files: X
Insertions: +XXX lines
Deletions: -XXX lines
Net Change: ±XXX lines

STATUS BREAKDOWN:
───────────────────────────────────────────────
New Files: X
Modified Files: X
Deleted Files: X
Renamed Files: X

FILE TYPE BREAKDOWN:
───────────────────────────────────────────────
Source Code: X files (+XXX -XXX lines)
Tests: X files (+XXX -XXX lines)
Documentation: X files (+XXX -XXX lines)
Configuration: X files (+XXX -XXX lines)
Styles: X files (+XXX -XXX lines)
Other: X files (+XXX -XXX lines)

TOP CHANGED FILES:
───────────────────────────────────────────────
1. <filename> (+XXX -XXX) = XXX lines
2. <filename> (+XXX -XXX) = XXX lines
3. <filename> (+XXX -XXX) = XXX lines
4. <filename> (+XXX -XXX) = XXX lines
5. <filename> (+XXX -XXX) = XXX lines

<if detailed:true>
PER-FILE BREAKDOWN:
───────────────────────────────────────────────
<status> <filename>
  Insertions: +XXX
  Deletions: -XXX
  Net: ±XXX

<status> <filename>
  Insertions: +XXX
  Deletions: -XXX
  Net: ±XXX

═══════════════════════════════════════════════

JSON Format (if format:json):

{
  "overview": {
    "total_files": X,
    "insertions": XXX,
    "deletions": XXX,
    "net_change": XXX
  },
  "status_breakdown": {
    "new": X,
    "modified": X,
    "deleted": X,
    "renamed": X
  },
  "type_breakdown": {
    "source": {
      "count": X,
      "insertions": XXX,
      "deletions": XXX
    },
    "tests": {
      "count": X,
      "insertions": XXX,
      "deletions": XXX
    },
    "docs": {
      "count": X,
      "insertions": XXX,
      "deletions": XXX
    },
    "config": {
      "count": X,
      "insertions": XXX,
      "deletions": XXX
    }
  },
  "top_files": [
    {
      "path": "<filename>",
      "insertions": XXX,
      "deletions": XXX,
      "net": XXX
    }
  ],
  "files": [
    {
      "path": "<filename>",
      "status": "<status>",
      "insertions": XXX,
      "deletions": XXX,
      "net": XXX,
      "type": "<file-type>"
    }
  ]
}

File Type Detection

Source Code:

.js, .jsx, .ts, .tsx (JavaScript/TypeScript)
.py (Python)
.java (Java)
.go (Go)
.rs (Rust)
.rb (Ruby)
.php (PHP)
.c, .cpp, .h (C/C++)
.swift (Swift)
.kt (Kotlin)

Tests:

.test.js, .spec.js
.test.ts, .spec.ts
_test.py, test_*.py
.test.jsx, .spec.tsx

Documentation:

.md (Markdown)
.txt (Text)
.rst (reStructuredText)
.adoc (AsciiDoc)

Configuration:

.json, .yml, .yaml, .toml
.config.js, .config.ts
.env, .env.*
.editorconfig, .gitignore
package.json, tsconfig.json

Styles:

.css, .scss, .sass, .less

Statistical Insights

Provide insights based on stats:

Large Changes:

INSIGHT: Large change detected
You've changed 500+ lines across 15 files.
Consider splitting into smaller commits.

Many New Files:

INSIGHT: Many new files added
8 new files suggest a new feature (feat).

Deletion Heavy:

INSIGHT: More deletions than insertions
Significant code removal suggests refactoring or cleanup.

Test Heavy:

INSIGHT: High test coverage
40% of changes are in test files.
Good practice to include tests with features.

Documentation Heavy:

INSIGHT: Documentation focused
60% of changes are documentation.
Consider "docs" commit type.

Usage Examples

Basic stats:

/commit-analysis file-stats

JSON output:

/commit-analysis file-stats format:json

Detailed breakdown:

/commit-analysis file-stats detailed:true

JSON with details:

/commit-analysis file-stats format:json detailed:true

Output Format

Return:

• Overview statistics
• Status breakdown
• File type breakdown
• Top changed files
• Per-file details (if detailed:true)
• Statistical insights
• Format as specified (text or JSON)

Error Handling

No changes:

NO CHANGES
Working tree is clean. No statistics to display.

Invalid format parameter:

ERROR: Invalid format
Valid formats: text, json

Integration with Agent

The commit-assistant agent uses this operation to:

1. Understand change magnitude
2. Identify dominant change types
3. Provide context for commit decisions
4. Generate statistics for reports

Usage Example

# Agent gathers stats before analysis
# User: "how big are my changes?"
# Agent: Invokes file-stats
# Operation: Returns comprehensive statistics
# Agent: "You've changed 15 files with 500+ lines"