setup_env/docs/task-time-tracking.md

Task & Time Tracking Cheat Sheet

Plain-text todo + time tracking over the ~/hc_notes Obsidian vault. All three surfaces (script, bashrc, nvim) live under ~/setup_env/dotfiles/ via symlinks — edit in dotfiles, changes go live.

Todo-grepping aliases (~/.bashrc)

Search open todos across the vault (- [ ] open, - [x] done, - [~] cancelled):

Alias	Does
td	All open todos
tdp	Prioritized only (🔼 medium or ⏫ high)
tdtp	Top priority only (⏫)
tdo	fzf-pick any open todo → open in nvim at that line
tdop	fzf-pick a prioritized todo → open in nvim at that line

Time-tracking shell functions (~/.bashrc)

Wrappers around the td script. They use command td because td alone is aliased to rg above — don't remove command.

Function	Runs	Purpose
tstart <tid> [--file PATH] [--desc TEXT]	td start	Start a timer on a task
tstop	td stop	Stop the open timer
treport [FILTER]	td report	Show logged time
tweek [--since DATE]	td week	Weekly task log from git history + time.csv

The td script

~/.local/bin/td → ~/setup_env/dotfiles/bin/td (Python 3, stdlib only).

Subcommands: start <tid> [--file PATH] [--desc TEXT], stop, report [FILTER], current, tidgen, week [--since DATE].

• Storage: CSV at $TD_LOG (default ./time.csv, cwd-scoped). Columns: started_at,stopped_at,tid,file,description. One row per entry; stop fills stopped_at on the open row.
• td week: scans git log -p --reverse --no-renames from cwd, pairs -/+ task-line diffs within each commit by ^tid-* to classify events (done / new / done+new / reopen), then joins with time.csv for per-tid duration. Default range = Monday 00:00 of current week. Commit time = event time (git is source of truth).

Nvim integration

Lives in ~/setup_env/dotfiles/nvim/{td.lua,td_mappings.lua} → ~/.config/nvim/lua/. Pulled in by a single require "td_mappings" line in ~/.config/nvim/lua/mappings.lua.

Keymap	Command	Action
<leader>ts	:TdStart	Start timer on current task line; auto-generates a ^tid-* block ref if missing, then starts
<leader>tp	:TdStop	Stop the timer
<leader>tr	:TdReport	Report in a floating window (q / <Esc> to close)
<leader>tw	:TdWeek [--since DATE]	Weekly git-derived task log in a floating window

• :TdStart only acts on lines matching - [.]. Auto-tid format: tid-YYYYMMDD-HHMMSS.
• Finds vault root by walking up from the buffer file for time.csv or .obsidian/; falls back to nvim cwd. CSV is written at the vault root regardless of buffer depth.
• Passes --file (relative to vault root) and --desc (task text, stripped of checkbox + block ref) to td, avoiding the rg-lookup fallback.

Task metadata conventions (Obsidian-Tasks)

➕ YYYY-MM-DD created · 📅 YYYY-MM-DD due · ⏫ high priority · 🔼 medium · plus #Tag and [[WikiLink]].

Known limitation

NvChad defers mappings.lua via vim.schedule, so :TdStart etc. aren't available inside -c args on headless invocations. Interactive use is unaffected.