time-reports

# time-reports

Guide to generating and interpreting time reports with terminal-time-tracker.

## Report Types

### Daily Report (default)

```bash
ttm report
```

Shows all projects with time logged today. Running timers are included with a `+` indicator.

### Weekly Report

```bash
ttm report --week
```

Current week Monday through Sunday. All projects with totals.

### Monthly Report

```bash
ttm report --month
```

Current calendar month totals.

### Custom Date Range

```bash
ttm report --from 2026-03-01 --to 2026-03-20
ttm report --from 2026-03-01              # from date to today
```

### Per-Project Breakdown

```bash
ttm report --project myproject
ttm report --week --project myproject    # daily breakdown this week
ttm report --month --project myproject  # daily breakdown this month
```

Shows day-by-day entries for the project instead of project totals.

## Reading the Report Table

```
  PROJECT            DURATION     ENTRIES   PERCENT
  myproject          18h 45m      12         61%
  docs               6h 30m       8          21%
  infra              3h 00m       3           9%
  meetings           2h 45m       5           9%

  total: 31h 00m  |  28 entries  |  4 projects
```

- DURATION: total time for all entries in range
- ENTRIES: number of individual log entries
- PERCENT: share of total time for the period
- Running timers show `+` after duration and `*` before percent

## Exporting for Invoicing

```bash
# Export all entries for a month as CSV
ttm export --from 2026-03-01 --to 2026-03-31 --output march.csv

# Export as JSON for processing
ttm export --from 2026-03-01 --to 2026-03-31 --format json --output march.json

# Filter by project for a client
ttm export --project clientproject --from 2026-03-01 --to 2026-03-31
```

CSV columns: `id, project, note, started_at, stopped_at, duration_seconds`

## Bar Chart Summary

```bash
ttm stats --week
```

Shows ASCII bar chart with hours per day for the current week. Useful for spotting patterns in daily work habits.

## Common Queries

```bash
# How long did I work today?
ttm report

# How long did I work this week?
ttm report --week

# How much time on a specific project this month?
ttm report --month --project myproject

# Top projects all-time
ttm stats

# What did I work on yesterday?
ttm list --from yesterday --to yesterday
```

## Interpreting Percentages

Percentages in the report are computed as (project duration / total duration * 100) rounded to the nearest whole number. They sum to 100% within rounding. Running timers are included using their current elapsed time as a snapshot.