https://github.com/srdjan/gitodos
A tiny, dependency‑free scanner that collects inline code issues (e.g., TODO/BUG)
https://github.com/srdjan/gitodos
git issues-tracker todo typescript
Last synced: about 2 months ago
JSON representation
A tiny, dependency‑free scanner that collects inline code issues (e.g., TODO/BUG)
- Host: GitHub
- URL: https://github.com/srdjan/gitodos
- Owner: srdjan
- Created: 2025-09-08T19:05:38.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-09T21:32:29.000Z (9 months ago)
- Last Synced: 2026-04-08T12:35:28.897Z (about 2 months ago)
- Topics: git, issues-tracker, todo, typescript
- Language: TypeScript
- Homepage:
- Size: 83 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Inline Code Issues Dashboard
Minimal, dependency‑free tooling to scan inline TODO/BUG/FIXME comments and generate a local HTML
dashboard.
- Scanner: `.git-bin/git-issues.ts` (writes `.git-bin/.issues` and subset `.git-bin/.bugs`)
- Dashboard: `.git-bin/issues-web.ts` → `.git-bin/issues.html`
- Optional: post‑commit hook to auto‑refresh on every commit
## Requirements
- Deno 2.x
- Git on PATH
## Quick start
```
# 1) Generate snapshots
deno task issues:scan # → .git-bin/.issues (full repo)
# 2) Build and open the HTML dashboard
deno task issues:web # builds (if needed) and opens .git-bin/issues.html
# Optional: install a post‑commit hook to auto‑refresh after every commit
deno task issues:hook:install
```
## Outputs
- `.git-bin/.issues` — full snapshot (timestamp, path:line, tag, message)
- `.git-bin/.bugs` — subset snapshot (currently scanning src/)
- `.git-bin/issues.html` — static, responsive dashboard with filtering and sorting
Tip: If the page looks empty, run the scan tasks first, then rebuild the HTML.
---
# Inline Issue & Bug Tracker (.git-bin/git-issues.ts)
This repository includes a tiny, dependency‑free scanner that collects inline code issues (e.g.,
TODO/BUG) and writes a snapshot into files under `.git-bin/`.
- Default scan: whole repo → `.git-bin/.issues`
- Subset scan: `src/` only (TODO/BUG) → `.git-bin/.bugs`
- Optional Git hook: automatically refresh after every commit
The scanner is fast, portable, and works across any language as long as comments contain
recognizable tags (e.g., `// TODO: …`, `# BUG: …`).
## Requirements
- Git available on PATH
- Deno (1.41+ recommended)
## Conventions
- Tags: only `TODO` and `BUG`.
- Priority: tight `!` after the tag means high (e.g., `TODO!:` / `BUG!:`). A single space is allowed
before the colon (e.g., `BUG! : message`).
- Colon: immediate or one space before it (e.g., `TODO:` or `TODO :`).
- Comments scanned (configurable): `// …`, `/* … */`, `# …`, ``.
- Markdown: scanned with a tiny heuristic — fenced code is ignored and inline backticks are stripped
before matching.
## Outputs
Each generated file contains a header with the snapshot time and aligned columns per line:
- `timestamp` — when the snapshot was generated
- `path:line` — file path relative to repo + line number
- `tag` — the matched tag
- `priority` — priority level (high/normal)
- `owner` — assigned person (if specified)
- `date` — due date or date marker (if specified)
- `category` — category/module (if specified)
- `id` — issue/ticket ID (if specified)
- `message` — the textual description
Example excerpt:
```
# Inline-issue snapshot 2025-09-08 19:47:06
# Columns: timestamp path:line tag priority owner date category id message
2025-09-08 19:47:06 test.md:22 TODO high alice 2025-01-10 - - Deploy hotfix for payment processing
2025-09-08 19:47:06 api.ts:14 BUG high - - api #99 Rate limiting not working correctly
```
JSON outputs are also generated alongside the text snapshots for tooling/CI:
- `.git-bin/issues.json` and `.git-bin/bugs.json` — array of entries:
`{ ts, file, line, tag, message, priority, owner?, date?, category?, id? }`.
## Dashboards
- Active: `.git-bin/issues.html` — search, tag filters, sort (priority/file/line/tag/time), group by
directory, keyboard shortcuts (`/`, `g`, `Esc`).
- History: `.git-bin/history.html` — journal-backed view with search, type/status filters, high-only
toggle, and sort (created/completed/priority/type).
Quick usage:
```
deno task issues:scan # write .issues
deno task issues:scan:src # write .bugs
deno task issues:web # build issues.html
deno task issues:web:open # open issues.html (cross‑platform)
deno task issues:history # build and open history.html
```
## Tasks (deno.json)
- `issues:scan`, `issues:scan:src`, `issues:web`, `issues:web:open`
- `issues:history`
- `issues:hook:install` — installs a post‑commit hook to refresh everything
## Git Hook
The hook created by `issues:hook:install` writes a `post-commit` script that regenerates both
snapshots and the HTML dashboard automatically:
```
#!/bin/sh
.git-bin/git-issues.ts --out .git-bin/.issues
.git-bin/git-issues.ts --path src --out .git-bin/.bugs
.git-bin/issues-web.ts
deno run -A .git-bin/history-web.ts
```
Notes:
- The installer also marks the scripts as executable to avoid permission errors.
- You can open the HTML afterwards with `deno task issues:web:open` (macOS) or by opening
`.git-bin/issues.html` directly.
## .gitodos (config)
```ini
# Patterns to ignore (comma-separated)
ignore=vendor/,node_modules/,dist/,.git/,*.min.js
# Comment styles to scan (comma-separated):
# slash (//), block (/* */), hash (#), html ()
comments=slash,block,hash,html
```
## Customization
Command-line options:
- Path scope: `--path ` (default: `.`)
- Output file: `--out ` (default: `.git-bin/.issues`)
You can add more tasks in `deno.json` for frequently used combinations.
## Tips
- Keep comments short and actionable; one TODO/BUG per line is ideal.
- Remove the colon if you want a line ignored: `// TODO later` (no match).
- Use the history page to track completion trends.
## Known limitations
- It matches `TAG:` with a colon; lines like `// TODO something` (no colon) are intentionally
ignored to reduce false positives.
- The per‑line `timestamp` reflects when the snapshot was taken, not when a comment was added.
- Only files listed by `git ls-files --cached --others --exclude-standard` are scanned; ignored
files (per `.gitignore`) are skipped by design.
- Minimal parser: only `TODO:` and `BUG:`. A tight `!` after the tag marks high (e.g., `TODO!:` /
`BUG!:`). Colon may have one space before it. Metadata (`@owner`, `[date|category]`,
`(#id)`/`(ABC-123)`) is parsed only at the start of the message if present.
## Recent Enhancements
✅ **Tight priority marker** — `TODO!:` / `BUG!:` (no space before `!`) ✅ **Colon flexibility** —
allow one space before the colon (`TODO :`) ✅ **Comment toggles** — `.gitodos` controls `//`,
`/* */`, `#`, `` ✅ **Markdown heuristic** — ignore fenced code; strip inline backticks ✅
**JSON snapshots** — `.git-bin/issues.json`, `.git-bin/bugs.json` ✅ **Journal + history** — SQLite
sync and `history.html` ✅ **Dashboards** — search/filters/sort; group-by for active view ✅
**Watch + open** — live rebuild, cross‑platform opener ✅ **Minimal, non‑regex parser** — small,
predictable scanner
## Roadmap ideas
- Context lines - Show code around issues
- Issue age tracking - Using git blame
- Thresholds for CI - Fail build if high-priority issues exist
- Export formats - JSON/CSV/Markdown reports
- VSCode integration - Quick navigation to issues
- Duplicate detection - Find similar issues
- Time tracking - Estimate/actual time metadata