Time from git history

snag retro reads the commit history of one or more git repositories, groups commits into sittings and turns them into time entries. It is for work that was never tracked and for which commits are the only record.

Dry run first

Without --commit, nothing is written. The command prints the plan: sittings per repository, totals, and how much overlap was removed.

snag retro --repo ~/src/app --repo ~/src/site --author "Sam" --since 2026-06-01

Writing the entries

snag retro --repo ~/src/app --project "App" \
           --repo ~/src/site --project "Website" \
           --author "Sam" --since 2026-06-01 --commit

--commit needs one --project per --repo, in the same order. Projects are given by name.

Flags

Flag	Means
`--repo PATH`	a repository to read; repeatable
`--project NAME`	the project the matching `--repo` maps to; required with `--commit`
`--author TEXT`	only commits whose author matches, as `git log --author`
`--since DATE`, `--until DATE`	limit the range, as `git log --since` and `--until`
`--commit`	write the entries
`--json`	accepted; output is the same as without it in this version

How time is worked out

Rule	Value
commits closer together than this are one sitting	90 minutes
a sitting starts this long before its first commit	30 minutes
no day totals more than this, across all repositories	9 hours (longer days are scaled down evenly)
shorter sittings are dropped	15 minutes

All repositories are planned on one timeline, so an hour spent switching between two repositories is counted once, not twice.

What gets written

Entries go on one task per project per month, named Development, <month>, created if missing. Every entry is marked as an estimate from snag-retro and is not billable, so the whole batch can be found and removed in the app.

Before writing, Snag sends one deliberately invalid entry to check that the server recognises those markers. Nothing is created by the check. If the server does not recognise them, nothing is written.

Running the same command again writes nothing new: each sitting carries a key built from its commits and the rules above. Changing the rules produces different keys, so remove the earlier batch first.

Needs a stored token (snag login) and a project with at least one task for the check.

Next: Settings