Git Repository Analysis

Generate markdown documentation for quick understanding of a git repository through systematic top-down analysis.

Analysis Workflow

Phase 1: Repository Overview
         ↓
Phase 2: Architecture Discovery
         ↓
Phase 3: Module Analysis (top-down)
         ↓
Phase 4: Documentation Generation

Phase 1: Repository Overview

Gather high-level repository context:

1. Identify project type - Check for indicator files:

   • package.json → Node.js/JavaScript
   • Cargo.toml → Rust
   • go.mod → Go
   • pyproject.toml/setup.py → Python
   • pom.xml/build.gradle → Java
   • Gemfile → Ruby

2. Read key files - In order:

   • README.md (project purpose, setup)
   • LICENSE (open source? proprietary?)
   • CONTRIBUTING.md (development workflow)
   • CHANGELOG.md (project history)

3. Assess repository state:

   git log --oneline -20          # Recent activity
   git shortlog -sn --max-count=5 # Top contributors
   git branch -a                  # Branch structure
   git tag -l --sort=-creatordate | head -5  # Recent releases
   

4. Record findings for overview section of documentation.

Phase 2: Architecture Discovery

Map the high-level structure:

1. Directory scan - List top-level directories:

   ls -la
   fd -t d --max-depth 1
   

2. Identify architectural layers - Common patterns:

   Directory	Likely Purpose
   src/, lib/	Source code
   cmd/, bin/	Entry points / CLI
   pkg/, internal/	Go package structure
   app/, apps/	Application code
   api/, routes/	API definitions
   models/, entities/	Data models
   services/, core/	Business logic
   utils/, helpers/	Utilities
   config/, settings/	Configuration
   tests/, __tests__/	Test suites
   docs/	Documentation
   scripts/	Build/deploy scripts

3. Find entry points:

   • Look for main.*, index.*, app.*, server.*
   • Check package.json scripts, Makefile targets
   • Identify CLI commands in bin/, cmd/

4. Detect patterns and frameworks:

   • MVC, MVVM, Clean Architecture
   • Monorepo vs single package
   • Microservices vs monolith
   • Framework-specific conventions (Rails, Django, Next.js, etc.)

Phase 3: Module Analysis (Top-Down)

Analyze each module systematically from top to bottom:

Step 3.1: Enumerate Modules

List all modules/packages to analyze:

# For JS/TS
fd -e ts -e tsx -e js -e jsx --max-depth 2 -t f | head -30

# For Python
fd -e py --max-depth 2 -t f | head -30

# For Go
fd -e go --max-depth 2 -t f | head -30

# General approach
fd -t f --max-depth 2 | head -40

Step 3.2: Per-Module Analysis

For each significant module/directory:

1. Purpose identification:

   • Read module's README if present
   • Scan file names for intent
   • Read main/index file first few lines

2. Public interface discovery:

   • Find exported functions/classes/types
   • Identify main entry points
   • Note configuration options

3. Dependency mapping:

   • Internal imports (other modules in project)
   • External dependencies
   • Data flow direction

4. Key implementation details:

   • Core algorithms or logic
   • State management approach
   • Error handling patterns
   • Important data structures

Step 3.3: Cross-Module Relationships

Map how modules interact:

Use ast-grep or ripgrep to trace:
- Import/require statements
- Function calls across modules
- Shared types/interfaces
- Event emissions and subscriptions

Phase 4: Documentation Generation

Generate structured markdown documentation.

Output Structure

Create documentation with this hierarchy:

analysis-docs/
├── README.md              # Quick start and overview
├── ARCHITECTURE.md        # System design and patterns
├── modules/
│   ├── module-a.md        # Per-module documentation
│   ├── module-b.md
│   └── ...
└── diagrams/              # Optional: architecture diagrams

Template: README.md (Quick Overview)

# {Project Name}

> {One-line description from original README or inferred}

## What This Project Does

{2-3 sentence explanation of purpose and main functionality}

## Quick Start

{Essential commands to get running - copied/adapted from source}

## Project Structure

{High-level directory overview with purpose of each}

## Key Concepts

{3-5 core concepts needed to understand the codebase}

## Where to Start Reading

{Recommended entry points for understanding the code}

Template: ARCHITECTURE.md

# Architecture Overview

## System Design

{Describe the overall architecture pattern (MVC, microservices, etc.)}

## Component Diagram

{Text-based diagram using ASCII or mermaid syntax}

## Data Flow

{How data moves through the system}

## Key Design Decisions

{Important architectural choices and their rationale}

## Dependencies

### External Services
{APIs, databases, third-party services}

### Internal Dependencies
{Module dependency graph}

Template: Module Documentation

# {Module Name}

## Purpose

{What this module does and why it exists}

## Public API

### Functions/Methods
- `functionName(params)` - {brief description}

### Types/Interfaces
- `TypeName` - {what it represents}

## Usage Examples

{Code snippets showing how to use this module}

## Internal Architecture

{How the module is organized internally}

## Dependencies

- Uses: {other modules this depends on}
- Used by: {modules that depend on this}

## Key Files

| File | Purpose |
|------|---------|
| `main.ts` | Entry point |
| `types.ts` | Type definitions |

Analysis Heuristics

Prioritization Rules

1. Start with entry points - main, index, app files
2. Follow the imports - Trace from entry to dependencies
3. Focus on public interfaces first - Understand API before internals
4. Skip generated code - *.min.js, *.d.ts, build/, dist/
5. Identify core vs peripheral - Business logic over utilities

Depth Guidelines

Pattern Recognition

Signs of important modules:

• Many inbound imports
• Located in core/, lib/, services/
• Contains business domain terminology
• Has its own tests

Signs of utility/helper modules:

• Generic names (utils, helpers, common)
• Few or no inbound imports
• Stateless functions

Output Checklist

Before finalizing documentation, verify:

• Project purpose is clearly stated
• Entry points are identified
• Module purposes are documented
• Dependencies are mapped
• Key concepts are explained
• No internal jargon left unexplained
• Someone new can start navigating with this doc