GitTrace

Trace every commit, report every day.

Transform chaotic, fragmented local Git commit histories into polished, audit-ready daily activity logbooks and monthly internship reports in seconds — powered by Local & Cloud AI.

---

📖 Overview

Interns, junior software developers, and research fellows often face the tedious chore of compiling monthly work reports from scattered Git commits across multiple repositories. Raw commits are frequently cryptic (wip, fix typo, rebase master), dates with no commits look like unproductive days, and manual formatting takes hours away from actual engineering.

GitTrace is a high-performance cross-platform Flutter Desktop application (Linux, Windows, macOS) designed to automate this entire pipeline:

1. Recursively scans your local workspaces to aggregate commits across multi-repo environments.
2. Visualizes productivity on an interactive monthly calendar with unique per-repository color tagging.
3. Applies advanced LLM prompt engineering (using local offline Ollama models or Cloud APIs) to translate raw commit histories into natural, professional Indonesian activity reports.
4. Fills empty calendar gaps intelligently by deducing preparatory research or post-implementation testing/QA tasks without hallucinating or duplicating entries.
5. Exports directly into formatted Excel (.xlsx), customizable institution Word templates (.docx), and print-perfect A4 PDFs (.pdf).

---

🗺️ Visual Workflow & Key Features

1. Automated Repository Discovery & Interactive Calendar Dashboard

Point GitTrace to your root projects directory. It automatically scans subdirectories, identifies all .git repositories, and maps all commits across selected projects onto a clean, interactive monthly calendar.

• Multi-Repository Selector: Filter specific client projects or work repositories dynamically via the sidebar.
• Distinct Color Palette: Each repository receives an identifiable color badge to clearly trace concurrent multi-repo development.
• Productivity Metrics: Real-time stats calculating active work days, total commits, and recorded working hours.

---

2. Working Hours & Inspection Table (Draft Persistence)

Clicking Export leads to a comprehensive inspection table where every working day is aligned with check-in, check-out, and aggregated commit logs.

• Bulk Working Hours Configuration: Set uniform check-in/out schedules across custom date ranges with a single click.
• Real-Time Draft Auto-Save: Any inline edits to activity descriptions or hours are saved immediately to local storage (shared_preferences). Your report drafts persist across app restarts without data loss.
• Duplicate Commit Resolver: Easily merge or split duplicate commit messages resulting from rebasing or cherry-picking.

---

3. AI Intelligence Engine (Local Ollama & Cloud LLMs)

Raw commit messages should not go directly into an official employer or university report. GitTrace integrates an advanced AI synthesis pipeline capable of transforming raw code logs into concise, formal, action-oriented activity descriptions.

⚙️ Flexible AI Configuration & Privacy-First Architecture

Choose between 100% private offline local inference via Ollama or high-throughput Cloud AI providers (DeepSeek, OpenCode).

• Local Offline Inference: Run models like qwen3:1.7b locally on your machine or private network. Your proprietary code commits never leave your workstation.
• VRAM & KV Cache Optimization: Configured with num_ctx: 2048 to ensure lightweight models fit within limited consumer GPU memory (e.g. 2 GB VRAM on GeForce 940MX) without CPU offload bottlenecking.
• Cloud API Fallbacks: Native support for DeepSeek Chat / Reasoner and OpenCode Zen with bearer token authentication.

⚡ Real-Time Streaming & Visual Progress

During generation, non-blocking streaming overlays report real-time parsing progress and reasoning steps.

✨ Context-Aware, Zero-Duplicate Results

The AI generator does not merely translate commit text; it structures full-month chronological narratives:

• Pre-Structured JSON Infill: Sends calendar date skeletons to the model, eliminating skipped or hallucinated calendar dates.
• Hybrid Recovery Engine: If any date is left unparsed, a secondary precision pass fills the gap using contextual hints.
• Intelligent Gap Filling:
  • Mid-Sprint Days (Pre-Commit): Allocates research, architectural planning, and database modeling leading up to the next upcoming commit.
  • End-of-Month Days (Post-Commit): Allocates comprehensive functional testing, system stability audits, code reviews, and technical documentation based on recent completed commits.
• Anti-Duplication Sliding Memory: An 8-sentence memory buffer prevents monotonous, repetitive phrases across long zero-commit periods.

---

4. Institution Word (.docx) Template Customization

Universities and organizations typically demand specific cover pages, header fonts, and signatory blocks for internship logbooks.

• Template Variable Substitution: Upload any institution .docx template. GitTrace parses and replaces placeholders dynamically:
  • {{nama}}, {{nim}}, {{prodi}}, {{mitra}}
  • {{hari_tanggal}}, {{jam_masuk}}, {{jam_pulang}}, {{kegiatan}}
• Keep-Together Layout: Guarantees that student and supervisor signature blocks remain anchored on the same page, preventing orphan signature lines.

---

5. Multi-Format Enterprise Export (Excel & PDF)

📊 Print-Ready Excel Export (.xlsx)

Produces clean, structured spreadsheets styled with professional borders, centered headers, auto-calculated column widths, and enabled word wrapping.

📄 Pixel-Perfect PDF Export (.pdf)

Generates standardized A4 PDF documents following strict 1-inch (72pt) margins, matching official university submission guidelines.

• Direct Native PDF: Clean vector rendering using pdf package for maximum sharpness and minimal file size.
• Headless LibreOffice Bridge: Automatically invokes headless LibreOffice conversion if exporting from a customized .docx template on systems with LibreOffice installed.

---

🏗️ Technical Architecture & Tech Stack

lib/
├── models/             # Immutable data models (CommitModel, ActivityLog, AiSettings)
├── providers/          # Riverpod state providers (Calendar, Repositories, AI State)
├── screens/            # UI Views (HomeScreen Calendar, ExportScreen Inspection Table)
├── services/           # Core Engines:
│   ├── git_service.dart      # Recursive git CLI parsing & author extraction
│   ├── ai_service.dart       # Streaming LLM client, JSON Infill & Hybrid Recovery
│   ├── excel_service.dart    # Binary spreadsheet generation & auto-formatting
│   ├── docx_service.dart     # Word XML template extraction & token replacement
│   └── pdf_service.dart      # Native A4 vector PDF layout & document compilation
├── utils/              # UI Themes, App Constants, Date Formatters
└── widgets/            # Reusable components (CalendarCell, MetricCard, Modals)

Component	Technology	Purpose
Framework	Flutter Desktop (3.x)	Native UI rendering on Linux, Windows, macOS
Language	Dart (>=3.12.0)	Null-safe, compiled language runtime
State Management	flutter_riverpod (v2.5)	Reactive, decoupled state and dependency injection
Local LLM Server	Ollama	Local inference for qwen3:1.7b / custom models
Cloud LLM APIs	DeepSeek / OpenCode	SSE streaming completions with JSON object formatting
Office Tooling	excel, archive, xml	Native document generation without external office suites
PDF Engine	pdf	Vector-precise A4 page rendering
Persistence	shared_preferences	Non-volatile draft auto-save and AI preferences

---

🚀 Getting Started

Prerequisites

• Flutter SDK (>= 3.10.0, recommended 3.22+)
• Git CLI installed and available in system PATH
• (Optional, for Local AI) Ollama installed and running:

  ollama pull qwen3:1.7b
  ollama serve

Installation

1. Clone the repository:

   git clone https://github.com/ekyaaa/git_trace.git
   cd git_trace

2. Install Flutter dependencies:

   flutter pub get

3. Launch the application:

   • Linux:

     flutter run -d linux

   • Windows:

     flutter run -d windows

   • macOS:

     flutter run -d macos

---

⚙️ Local AI (Ollama) Setup & Tips

To utilize offline AI generation without relying on paid API keys:

1. Start your local Ollama daemon:

   ollama run qwen3:1.7b

2. In GitTrace, open AI Settings (sparkle icon):
   • Provider: Ollama (Local)
   • Ollama Host URL: http://localhost:11434 (or your remote Tailscale/LAN IP)
   • Model Name: qwen3:1.7b
3. Click Simpan Pengaturan.

Tip

For GPUs with limited VRAM (e.g. 2 GB VRAM): GitTrace is pre-configured with num_ctx: 2048. This ensures KV Cache allocations remain small (~150 MB), allowing the entire 1.35 GB model weights of qwen3:1.7b to stay in VRAM for lightning-fast inference (< 5 seconds per batch).

---

🤖 CI/CD & Automated Releases

GitTrace utilizes GitHub Actions workflows to automatically compile native binaries across platforms whenever a semver release tag is pushed (e.g. v1.2.0):

• Windows: Generates GitTrace-Setup.exe installer and standalone portable .zip.
• Linux: Generates bundled standalone tarballs (.tar.gz).
• Artifacts are uploaded directly to the GitHub Releases page with automated changelogs.

---

📄 License

This project is open-source software licensed under the MIT License.

---

_{Crafted with ❤️ by ekyaaa for interns and developers everywhere.}