The Problem

Developers need a quick, offline way to understand who contributed what, where activity concentrates, and how a repository evolved over time. Existing tools often require cloud services, proprietary APIs, or manual data wrangling, making it hard to audit large or sensitive codebases.

What This Does

git-truck scans a local Git repository and produces interactive visualizations of contribution density, file‑level activity, and temporal changes. The core CLI lives in src/cli.ts, which boots the server defined in src/server/app.ts. UI components such as src/components/TimeSlider.tsx and src/components/Chart.tsx render the data, while route handlers in src/routes/ (e.g., src/routes/view.tsx, src/routes/browse.tsx) serve JSON endpoints for the front‑end. Persistent data is stored in src/analyzer/MetadataDB.server.ts and src/analyzer/DB.server.ts, which wrap a SQLite (or similar) backend.

How It Is Wired

  1. Entry – Execution starts at src/cli.ts. The CLI parses command‑line arguments (defaulting to the current working directory) and invokes startServer() from src/server/app.ts.
  2. Server Setup – app.ts creates an Express/Koa instance, registers middleware, and mounts the router tree from src/routes/*.tsx.
  3. Routing – Requests hit routes such as src/routes/view.tsx (visualization page) or src/routes/commits.tsx (commit list). Each route imports the analyzer layer (src/analyzer/*.server.ts) to fetch data.
  4. Analyzer Layer – The most‑connected modules are src/analyzer/ServerInstance.server.ts (imports 2 other analyzer services) and src/analyzer/InstanceManager.server.ts (imports 2 services but is not imported elsewhere). These modules coordinate SQLite access via MetadataDB.server.ts and DB.server.ts.
  5. Data Flow – src/analyzer/git-caller.server.ts runs Git commands, pipes results into metric calculators (src/metrics/*.ts), and stores aggregates in the DB. UI components consume the JSON payloads, rendering charts with src/components/BarChart.tsx, src/components/TimeSlider.tsx, etc.
  6. Exit – The server runs until the process is terminated; no background workers are spawned.

The import graph shows 112 internal modules with only 13 import edges and no circular dependencies, meaning most changes are localized. However, the hub modules (ServerInstance.server.ts, InstanceManager.server.ts) have the highest instability (0.67‑1.0) and therefore represent the biggest blast radius for refactoring.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/git-truck.git
cd git-truck

# Install globally (as documented) or run via npx
npm install -g git-truck@latest
# or: npx -y git-truck

# Run the CLI (starts the local server)
git truck
# Open the displayed URL (default http://localhost:3000) in a browser

Docker – The repository ships a Dockerfile and a helper script run-with-docker.sh. Build and run with:

docker build -t git-truck .
./run-with-docker.sh   # pulls the image, starts the container

Configuration – A template .env.example is provided; copy it to .env if you need to override defaults (e.g., DB path). No secrets are checked in.

Testing – Run the test suite with npm test; 7 test files reside under src/**.test.ts and src/shared/**.test.ts.

Real‑World Use

A security‑focused organization can embed git-truck in its CI pipeline to generate a nightly HTML report of contribution hotspots. The report is stored as an artifact, and because the tool works entirely offline, no external data is leaked.

git-truck --output ./report.html
# Upload ./report.html as a CI artifact

Code Health & Issues

  • High – Pin GitHub Action versions to commit SHAs (.github/workflows/*).
  • High – Use PR workflow instead of direct pushes in bump-version-and-publish.yml.
  • Medium – Declare least‑privilege permissions for GITHUB_TOKEN (.github/workflows/check-bun.yml).
  • Medium – Pin Docker base image by digest (Dockerfile).
  • Medium – Add a dependency‑vulnerability scan step to CI.
  • Medium – Move large binary git_truck_for_VISSOFT-1.pdf (5 MB) to Git LFS or external storage.
  • Medium – Set persist-credentials: false on checkout (check-node.yml).
  • Low – Define timeout-minutes on workflow jobs (bump-version-and-publish.yml).
  • Low/Risk – No lockfile (package.json only) → non‑reproducible builds.
  • Code‑quality – Deep nesting (max depth 8) in src/routes/view.tsx, src/routes/browse.tsx, src/components/TimeSlider.tsx.
  • Oversized file – src/routes/browse.tsx exceeds 600 lines; consider splitting.
  • Duplicated blocks – Repeated logic in src/routes/commits.tsx and src/routes/view.commits.tsx.
  • High branching density – src/metrics/fileExtension.ts has 20 branches in 43 lines.

The Bottom Line

git-truck delivers a functional, offline visual analytics suite for Git repositories with a clear separation between CLI, server, and UI layers. The codebase is modestly sized and free of circular dependencies, but several high‑impact CI and security hardening steps are missing, and a few large, deeply nested files hinder maintainability. It is suitable for teams that need quick, self‑hosted contribution insights and are prepared to address the listed health concerns.