Package Exports

git-scout
git-scout/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (git-scout) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

🔍 Git Scout

A powerful CLI tool for managing and analyzing multiple Git repositories with advanced statistics and beautiful visualizations.

✨ Key Features

🆕 Auto-Discovery: Automatically find and configure Git repositories with git-scout init
📊 Multi-Repository Management: Track multiple Git projects from a single interface
🌿 Interactive Branch Explorer: Browse branches with detailed commit information
📈 Today's Activity Dashboard: Get instant insights into daily development activity
📋 Comprehensive Statistics: Generate detailed reports with author and file-level analytics
🎨 Beautiful Tables & Colors: ASCII tables with syntax highlighting and intuitive color coding
📅 Flexible Date Parsing: Support for relative dates (7d, today, yesterday) and absolute dates
📤 JSON Export: All commands support JSON output for integration with other tools
🍎 macOS Optimized: Built specifically for macOS with proper timezone handling and safe scanning
🛡️ Privacy-Focused: Avoids sensitive directories (Photos, Music, etc.) - no permission requests

🚀 Quick Installation & Setup

Step 1: Install Git Scout

# Clone the repository
git clone https://github.com/malco-helper/git-scout.git
cd git-scout

# Auto-install everything
./scripts/setup.sh

Or manual installation:

npm install && npm run build && npm link

Step 2: Auto-Configure Your Repositories 🆕

# 🎯 ONE COMMAND TO RULE THEM ALL
git-scout init

What this does:

🔍 Automatically scans for Git repositories in safe directories
📝 Extracts project descriptions from package.json/README files
⚡ Creates configuration instantly - no manual setup needed
🛡️ Respects macOS privacy - no permission requests for Photos/Music/etc.

Step 3: Start Analyzing!

# View today's activity
git-scout today

# Explore branches
git-scout branches

# Generate weekly statistics
git-scout stats --since 7d

🎯 Core Commands

`git-scout init` - Auto Setup 🆕

The easiest way to get started!

git-scout init                           # Auto-discover repositories
git-scout init --scan-path ~/MyProjects # Scan specific directory
git-scout init --global                 # Force global configuration

Safe Scanning:

✅ Scans: ~/Projects, ~/Dev, ~/Code, ~/GitHub, ~/Documents/Projects
❌ Avoids: Photos, Music, Movies, System directories (no permission requests!)

`git-scout today` - Daily Activity

git-scout today                          # Today's activity
git-scout today --author alice           # Filter by author
git-scout today --branch main            # Filter by branch

`git-scout stats` - Comprehensive Analytics

git-scout stats --since 7d               # Weekly statistics
git-scout stats --since "2025-09-01"     # Since specific date
git-scout stats --author alice --json    # JSON output for specific author

`git-scout branches` - Branch Explorer

git-scout branches                       # Interactive branch explorer
git-scout branches --project "My App"    # Specific project
git-scout branches --since 30d          # Show recent activity

`git-scout projects` - Project Management

git-scout projects                       # List and select projects
git-scout projects --json               # JSON output

📊 Sample Output

Author Statistics

┌─────────────────────────┬─────────┬───────┬────────┬────────┐
│ AUTHOR                  │ COMMITS │ FILES │ +LINES │ -LINES │
├─────────────────────────┼─────────┼───────┼────────┼────────┤
│ John Doe                │ 15      │ 23    │ +487   │ -123   │
│ Jane Smith              │ 8       │ 12    │ +234   │ -67    │
└─────────────────────────┴─────────┴───────┴────────┴────────┘

Branch Information

🌿 Branch: develop

Latest commit: a1b2c3d
Author: John Doe
Date: 09/30/2025 14:30
Message: Add user authentication feature
Recent commits: 12

📅 Flexible Date Formats

Git Scout supports natural date expressions:

Relative: today, yesterday, 7d, 30d
Specific: today 09:00, 2025-09-29
ISO Format: 2025-09-29T10:00:00

⚙️ Configuration

Automatic (Recommended)

git-scout init  # One command setup!

Manual Configuration

Create ~/.git-scout/config.json:

{
  "projects": [
    {
      "name": "My App",
      "path": "/Users/yourname/Dev/my-app"
    }
  ],
  "defaultSinceDays": 1
}

🔧 Advanced Usage

JSON Integration

# Export data for other tools
git-scout stats --since 7d --json > weekly-report.json
git-scout today --json | jq '.stats.totalCommits'

Filtering & Analysis

# Team productivity analysis
git-scout stats --since 30d --author "team@company.com"

# Branch comparison
git-scout branches --project "Backend" --since 7d

# File change tracking
git-scout stats --since 7d --limit 50

Multiple Projects Workflow

# 1. Configure multiple projects
git-scout init

# 2. Select projects interactively
git-scout projects

# 3. Analyze across selected projects
git-scout today

🐛 Troubleshooting

Command not found

npm link  # Re-link the package

No repositories found

git-scout init --scan-path ~/your-dev-folder  # Custom scan path

Permission issues

chmod +x scripts/setup.sh  # Make setup script executable

Config issues

rm ~/.git-scout/config.json && git-scout init  # Reset and reconfigure

🗑️ Uninstallation

# Remove global command
npm unlink -g git-scout

# Remove configuration (optional)
rm -rf ~/.git-scout

# Remove source code
rm -rf /path/to/git-scout

🧪 Development & Testing

Prerequisites

Node.js >= 16.0.0
Git
macOS (primary target)

Development Setup

git clone <repository-url>
cd git-scout
npm install
npm run dev -- --help    # Development mode
npm test                 # Run tests
npm run build            # Production build

Architecture

src/
├── commands/           # CLI commands (init, projects, branches, today, stats)
├── git/               # Git integration and parsing
├── ui/                # Table rendering and formatting
├── utils/             # Date parsing and utilities
├── config.ts          # Configuration management
├── types.ts           # TypeScript definitions
└── index.ts           # Main CLI entry point

🤝 Contributing

Fork the repository
Create feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

🌟 Roadmap

GitHub/GitLab API integration
Commit message analysis
Team productivity metrics
CSV/Excel export
Web dashboard
Real-time monitoring
Custom report templates

📝 License

MIT License - see LICENSE file for details.

💡 Pro Tips

Start with git-scout init - it's the fastest way to get up and running
Use --json flag for integrating with other tools and scripts
Combine filters for precise analysis: --author alice --branch main --since 7d
Regular analysis helps track team productivity and code quality trends
Safe scanning means no macOS permission popups - scan worry-free!

Made with ❤️ for developers who love beautiful, insightful Git analytics.

🚀 Get started in 30 seconds: git-scout init

git-scout