User Guide
Installation
From PyPI
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install the package
pip install git-timesheet
From Source
# Clone the repository
git clone https://github.com/mcgarrah/git-timesheet.git
cd git-timesheet
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install in development mode
pip install -e .
Configuration
The tool supports configuration files to set default values. It looks for configuration files in the following locations (in order of precedence):
.ggtsrcin the current directoryggts.iniin the current directory.ggtsrcin the user’s home directoryggts.iniin the user’s.configdirectoryconfig.iniin the user’s.config/git-timesheetdirectory
You can create a configuration file using the ggts init command, or manually create one with the following format:
[defaults]
# Author pattern to filter commits
author = michael mcgarrah
# Default timezone for dates
timezone = US/Eastern
# Minutes between commits to consider them part of the same work session
session_timeout = 60
Usage
# Generate a timesheet (default command)
ggts [OPTIONS]
# or explicitly
ggts generate [OPTIONS]
# Initialize configuration
ggts --init
# or
ggts init
Options
--base-dir PATH: Base directory containing git repositories (default: current directory)--since DATE: Show commits more recent than a specific date (e.g., “2 weeks ago”)--until DATE: Show commits older than a specific date--repos REPO: Specific repository names to include (can be used multiple times)--output FORMAT: Output format (text, csv, markdown, or md, default: text)--author PATTERN: Filter commits by author (default from config or “mcgarrah”)--timezone TIMEZONE: Timezone for dates (default from config or “UTC”)--output-file PATH: Write output to file instead of stdout--session-timeout MINUTES: Minutes between commits to consider them part of the same work session (default from config or 60)
Examples
Generate timesheet for the last 2 weeks
# Using default command
ggts --since="2 weeks ago"
# or explicitly
ggts generate --since="2 weeks ago"
Generate timesheet for specific repositories
ggts generate --repos food_service_nutrition --repos food-intelligence-app --since="1 month ago"
Generate timesheet for a specific date range
ggts generate --since="2023-01-01" --until="2023-01-31"
Generate timesheet in US Eastern timezone
ggts generate --since="1 month ago" --timezone="US/Eastern"
Generate CSV output for spreadsheet import
ggts generate --since="1 month ago" --output=csv --output-file=timesheet.csv
Generate markdown output for pretty formatting
ggts generate --since="1 month ago" --output=markdown --output-file=timesheet.md
Initialize configuration
# Using the dedicated command
ggts init
# or using the flag
ggts --init
Output Formats
Text Format
Plain text output organized by weeks and days, showing detailed commit information with timezone abbreviations.
CSV Format
Comma-separated values format suitable for importing into spreadsheet applications like Excel or Google Sheets. Includes timezone information for each entry.
Markdown Format
Pretty markdown format with tables organized by week, suitable for viewing in markdown readers or converting to HTML. Includes time ranges and timezone abbreviations for each task to better understand work sessions.
Time Estimation Logic
Base time: 15 minutes per commit
Bug fixes/issues: +15 minutes
New features/implementations: +30 minutes
Refactoring/improvements: +15 minutes
Commits close together (within 60 minutes by default) are considered part of the same work session
Timezone Support
The tool supports various timezone formats:
IANA timezone names (e.g., “America/New_York”)
Common US timezone aliases (e.g., “US/Eastern”)
Short timezone abbreviations (e.g., “EST”, “EDT”)
Prefixed short timezone abbreviations (e.g., “US/EST”)