Paul Trowbridge
ebe8b31fc9
Standalone reference for the td todo/time-tracking system (aliases, shell functions, script subcommands, nvim keymaps). Linked from README. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
62 lines
4.2 KiB
Markdown
62 lines
4.2 KiB
Markdown
# 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.
|