Time Tracking Commands

Core commands for recording, viewing, and managing your time entries.

hourgit init

Initialize Hourgit in the current git repository by installing a post-checkout hook.

hourgit init [--project <name>] [--mode <mode>] [--force] [--append] [--yes]
Flag Default Description
-p, --project auto-detect Assign repository to a project by name or ID (creates if needed)
-m, --mode standard Tracking mode: standard or precise (enables filesystem watcher for idle detection)
-f, --force false Overwrite existing post-checkout hook
-a, --append false Append to existing post-checkout hook
-y, --yes false Skip confirmation prompt

hourgit log add

Manually log time for a project. Uses a hybrid mode: provide any combination of flags and you'll be prompted only for the missing pieces.

hourgit log add [MESSAGE] [--duration <dur>] [--from <time>] [--to <time>] [--date <date>] [--task <label>] [--project <name>]
Flag Default Description
-p, --project auto-detect Project name or ID
-d, --duration — Duration to log (e.g. 30m, 3h, 1d3h30m)
-F, --from — Start time (e.g. 9am, 14:00)
-T, --to — End time (e.g. 5pm, 17:00)
-D, --date today Date to log for (YYYY-MM-DD)
-t, --task — Task label for this entry

--duration and --from/--to are mutually exclusive. A message is always required (prompted if not provided).

Examples:

# Fully specified — no prompts
hourgit log add --duration 3h "did some work"
hourgit log add --from 9am --to 12pm "morning work"
hourgit log add --duration 3h --date 2025-01-10 "forgot to log"

# Partial flags — prompted for the rest
hourgit log add --duration 3h          # prompted for message
hourgit log add --from 9am             # prompted for --to and message
hourgit log add "meeting notes"        # prompted for time mode and inputs

# Fully interactive
hourgit log add

hourgit log edit

Edit an existing log entry by its hash. When edit flags are provided, only those changes are applied directly. Without flags, an interactive editor opens with current values pre-filled.

hourgit log edit <hash> [--duration <dur>] [--from <time>] [--to <time>] [--date <date>] [--task <label>] [-m <msg>] [--project <name>]
Flag Default Description
-p, --project auto-detect Project name or ID
-d, --duration — New duration (e.g. 30m, 3h, 3h30m)
-F, --from — New start time (e.g. 9am, 14:00)
-T, --to — New end time (e.g. 5pm, 17:00)
-D, --date — New date (YYYY-MM-DD)
-t, --task — New task label (empty string clears it)
-m, --message — New message
-y, --yes false Skip confirmation prompt

Any combination of --duration, --from, and --to is allowed. With two flags, the third is computed. With all three, they must be consistent (to - from = duration). --from only: keeps duration, shifts the time window. --to only: keeps start, recalculates duration. --duration only: keeps start, shifts end. Entry ID and creation timestamp are preserved.

Examples:

hourgit log edit abc1234 --duration 3h
hourgit log edit abc1234 --from 9am --to 12pm
hourgit log edit abc1234 --task "reviews"
hourgit log edit abc1234 -m "updated message"
hourgit log edit abc1234              # interactive mode

hourgit log remove

Remove a log or checkout entry by its hash.

hourgit log remove <hash> [--project <name>] [--yes]
Flag Default Description
-p, --project auto-detect Project name or ID
-y, --yes false Skip confirmation prompt

Works with both log and checkout entries. Shows entry details and asks for confirmation before deleting.

hourgit sync

Sync branch checkouts and commits from git reflog. Called automatically by the post-checkout hook, or run manually to backfill history. Commits are used to split checkout sessions into finer time blocks with commit messages.

hourgit sync [--project <name>]
Flag Default Description
-p, --project auto-detect Project name or ID

hourgit report

Interactive time report with inline editing. Shows tasks (rows) × days (columns) with time attributed from branch checkouts, commits, and manual log entries. Checkout sessions are automatically split by commits, showing commit messages in a detail panel.

hourgit report [--month <1-12>] [--week <1-53>] [--year <YYYY>] [--project <name>] [--export <format>] [--detail <level>]
Flag Default Description
-m, --month current month Month number 1-12
-w, --week — ISO week number 1-53
-y, --year current year Year
-p, --project auto-detect Project name or ID
-e, --export — Export format (pdf); auto-generates filename
-d, --detail summary Export detail level: summary or full (individual entries with commit messages)

--month and --week cannot be used together.

Interactive keybindings:

Key Action
←/→/↑/↓ or h/l/k/j Navigate cells
Tab or ] / Shift+Tab or [ Cycle through entries in selected cell
e Edit selected cell entry
a Add a new entry to selected cell
r or Del Remove entry from selected cell
s Submit period
q or Esc Quit

Examples:

hourgit report                                    # current month, interactive
hourgit report --week 8                           # ISO week 8
hourgit report --export pdf                       # export PDF
hourgit report --export pdf --week 8              # export week PDF
hourgit report --export pdf --month 1 --year 2025

hourgit history

Show a chronological feed of all recorded activity, newest first.

hourgit history [--project <name>] [--limit <N>]
Flag Default Description
-p, --project all projects Filter by project name or ID
-l, --limit 50 Maximum number of entries to show (use 0 for all)

hourgit status

Show current tracking status — project, branch, time logged today, and schedule state.

hourgit status [--project <name>]
Flag Default Description
-p, --project auto-detect Project name or ID

Output includes: