GitHub Timelog

A Python script to fetch commit data from a GitHub organization, filter by committer email, and generate a timelog CSV using AI estimation.

Setup

1. Clone or download the repository.
2. Install dependencies: pip install -r requirements.txt
3. Copy .env.example to .env and fill in your tokens:
   • GITHUB_TOKEN: GitHub Personal Access Token with repo scope.
   • XAI_API_KEY: Your xAI API key.

Usage

Run the script with:

python main.py --org <organization> --email <committer_email> [--since YYYY-MM-DD] [--master <path/to/master.csv>]

• --org: GitHub organization name (required)
• --email: Email of the committer to filter commits (required)
• --since: Optional date to fetch commits from (default: last year)
• --master: Optional path to master worklog CSV to mix with generated data

Example:

python main.py --org mycompany --email developer@mycompany.com --since 2023-01-01

Example with master worklog mixing:

python main.py --org mycompany --email developer@mycompany.com --master master_worklog.csv --since 2023-01-01

Master Worklog Mixing

The script supports mixing AI-generated tasks from commits with authoritative master worklog records using LLM-based intelligent distribution.

When the --master option is provided, the script:

• Reads the master worklog CSV (expected columns: Date, Task Name, Job Done, Time Spent)
• Groups data by date
• For each date, uses an LLM to distribute the total master time proportionally among the generated tasks based on relevance
• Extends each task's description with relevant details from master records
• Ensures the sum of time spent matches the master total

This produces enriched, meaningful tasks suitable for reporting.

The output will be saved to timelog.csv in the current directory.

Output

The CSV contains columns: Date, Task Name, Job Done, Time Spent (hours).

Notes

• Ensure your GitHub token has access to the organization's repositories.
• The script handles pagination and rate limiting automatically.
• Commit messages are processed by xAI Grok API to estimate time spent.