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):

.timesheetrc in the current directory
timesheet.ini in the current directory
.timesheetrc in the user’s home directory
timesheet.ini in the user’s .config directory
config.ini in the user’s .config/git-timesheet directory

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
ggts generate [OPTIONS]

# Initialize configuration
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

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 with specific author pattern

ggts generate --author="michael mcgarrah" --since="2 weeks ago"

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

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”)