# 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.