ProjectTracker

Multi-repository state tracker and coordinator for managing multiple Git projects.

ProjectTracker scans all tracked repositories, detects changes, pulls updates, identifies conflicts, and generates human-readable summaries of the entire ecosystem state.

Purpose

Managing 15+ active Git repositories manually is tedious and error-prone. ProjectTracker automates:

• State Tracking: Which repos have new commits, uncommitted changes, conflicts
• Activity Monitoring: Which projects are active vs dormant
• Conflict Detection: Automatic merge conflict identification
• Categorization: Organize projects by status (WIP, CONSTANT, PAUSE, etc.)
• Reporting: Generate readable summaries for quick ecosystem overview

Structure

ProjectTracker/
├── tools/
│   ├── config.json          # Repository configuration and tracking settings
│   ├── scan.sh              # Main scanner script (bash)
│   └── analyze.py           # Summary generator (Python)
├── projects/
│   ├── META/                # Meta-projects (planning, infrastructure)
│   ├── CONSTANT/            # Ongoing/maintenance projects
│   ├── WIP/                 # Active development projects
│   ├── CONCEPT/             # Early-stage ideas
│   ├── PAUSE/               # Paused projects
│   └── DONE/                # Completed projects
├── .planning/               # Generated state files (auto-created)
│   ├── state.json           # Machine-readable repo state
│   ├── summary.md           # Human-readable summary
│   ├── scan.log             # Detailed scan logs
│   └── conflicts.txt        # List of repos with conflicts
├── .env                     # Gitea credentials and configuration
└── README.md                # This file

Configuration

1. Environment Variables (.env)

GITEA_URL=https://git.etheryale.com
GITEA_TOKEN=your_token_here

Note: Use wget instead of curl for API calls due to proxy compatibility.

2. Repository Tracking (tools/config.json)

Define which repos to track, exclude, and categorize:

{
  "repos_root": "C:/Users/alexi/Documents/projects",
  "tracked_repos": ["civjdr", "ChineseClass", "seogeneratorserver", ...],
  "excluded_repos": ["couple-repo", "vba-mcp-demo", ...],
  "project_mapping": {
    "civjdr": "projects/CONSTANT/civjdr.md",
    "ChineseClass": "projects/CONSTANT/ChineseClass.md",
    ...
  }
}

Scan Options:

• auto_pull: Automatically pull updates (default: true)
• commits_lookback_days: Activity window for "recent" commits (default: 21)
• detect_uncommitted_changes: Check for unstaged/uncommitted files (default: true)

Usage

Full Scan and Summary

cd ProjectTracker
bash tools/scan.sh

This will:

1. Fetch updates from all tracked repos
2. Pull changes (if auto_pull: true)
3. Detect conflicts, uncommitted changes, ahead/behind status
4. Generate .planning/state.json with full repo state
5. Run analyze.py to generate .planning/summary.md

Generate Summary Only

If you already have a state.json and want to regenerate the summary:

python tools/analyze.py

View Summary

cat .planning/summary.md

Output Files

state.json (Machine-Readable)

JSON snapshot of all repos with detailed metrics:

{
  "last_scan": "2026-01-18T14:30:00+00:00",
  "repos": {
    "civjdr": {
      "last_commit": "abc1234",
      "branch": "main",
      "commits_3w": 8,
      "new_commits_since_last_scan": 2,
      "has_uncommitted_changes": false,
      "has_conflict": false,
      "needs_attention": true,
      ...
    }
  },
  "stats": {
    "total_repos": 18,
    "active_3w": 12,
    "needs_attention": 5,
    "conflicts": 1
  }
}

summary.md (Human-Readable)

Markdown report with:

• Global Stats: Total repos, active count, attention needed, conflicts
• Needs Attention: Prioritized list (conflicts → uncommitted → new commits → behind)
• By Category: Repos organized by status (META, CONSTANT, WIP, etc.)
• Recent Activity: Commit counts for active repos (last 3 weeks)

Example:

## ⚠️  Needs Attention

- **seogeneratorserver** (develop) - ❌ CONFLICT | 📝 7 uncommitted | 🆕 5 new
  Last: Update SEO templates (3 days ago)
- **ChineseClass** (main) - 📝 3 uncommitted | 🆕 2 new
  Last: Add vocabulary list (2 days ago)

Project Categorization

Projects are organized by development status:

• META: Infrastructure, planning, coordination projects
• CONSTANT: Ongoing/maintenance projects (no end date)
• WIP: Active development (work in progress)
• CONCEPT: Early-stage ideas, prototypes
• PAUSE: Temporarily paused projects
• DONE: Completed projects (archived)

Each project has a corresponding .md file in projects/<CATEGORY>/ with:

• Description
• Current status
• Repository URL
• Next steps
• Notes

Workflow

1. Daily/Weekly: Run scan.sh to check ecosystem state
2. Review: Check summary.md for repos needing attention
3. Act: Address conflicts, commit changes, pull updates
4. Repeat: Keep repos synchronized and tracked

Requirements

• Bash: For scan.sh (Git Bash on Windows, native on Linux/Mac)
• Python 3.7+: For analyze.py
• jq: JSON processor for bash script parsing
• Git: Obviously :)

Notes

• Scanner automatically fetches before pulling
• Conflicts are never auto-resolved (manual intervention required)
• state.json tracks previous scan state to detect "new" commits
• All timestamps use ISO 8601 format
• UTF-8 encoding support for emoji indicators on all platforms

---

Created: 2026-01-18 (Cycle 2 - External Exploration) Purpose: Coordinate multi-project ecosystem efficiently Maintained: Active