gitodo 0.1.1

Git-based local TODO management

Gitodo CLI

基于 Git 的本地 TODO 管理工具，所有数据存放在 ~/.gitodo 并由 Git 记录历史。

安装

• 使用 uv（推荐）：uv pip install .
• 或使用 pip：pip install .

默认数据目录

• ~/.gitodo/（启动或命令首次运行时自动创建并 git init）
• 主要文件：TODO.md、archive/、resources/、.storage.lock、gitodo.toml

配置（可选）

~/.gitodo/gitodo.toml（如不存在会自动生成）示例：

debug = false
log_level = "INFO"
repo_path = "~/.gitodo"
auto_commit = true
commit_message_template = "gitodo {action}: {summary}"
plain_output = false
show_pins_default = true
show_preview_default = false

常用命令

（所有命令默认作用于 ~/.gitodo，如需自定义目录可设置环境变量 GITODO_REPO_PATH 或 --config 指定）

• 初始化：gitodo init
• 查看状态：gitodo status
• 切换/创建分支：gitodo checkout <branch>；查看分支：gitodo branch
• 固定说明（pin）：gitodo pin "分支长期说明"（写入 TODO.md 顶部 PINS 块，支持 --tags/#tag --context/@ctx --priority/!P1，遵循自动提交策略）
• 追加任务：gitodo add "写方案" [--done] [--tags #tag ...] [--context @home] [--priority !P1] [--resource resources/x.png] [--commit|--no-commit]
  • 快捷追加（等价 add）：gitodo "写方案"
• 完成任务：gitodo done <id或序号> [--status todo|done|all] [--commit|--no-commit]
• 列出任务：gitodo list [--limit N] [--status todo|done|all] [--with-id] [--no-id] [--with-pin|--no-pin] [--preview|--no-preview]
  • 默认 limit=7，展示最新 N 条任务（倒序）；PINS 块默认展示，可用 --no-pin 或配置 show_pins_default=false 关闭；原文预览默认关闭，可用 --preview 或配置 show_preview_default=true 开启
• 查看差异：gitodo diff [path] [--cached]
• 归档完成项：gitodo archive [--date YYYY-MM-DD | --since ... --until ...] [--dry-run] [--commit|--no-commit] [-m msg]
• 手动提交：gitodo commit [-m msg]
• 输出模式：默认使用简化 Rich 样式，纯文本回退由配置 plain_output 控制（不再提供命令行开关）；主要输出遵循轻量 Table/Markdown，无大面积 Panel。

任务行格式（TODO.md）

• 每日块：## YYYY-MM-DD
• 任务行：- [ ] HH:MM 描述 #tag @ctx !P1 (id:xxxx) +res:resources/file
  • [ ]/[x]/[-]/[?] 表示 待办/完成/取消/阻塞
  • 完成时自动追加 @done(YYYY-MM-DD HH:MM)

归档规则

• archive 将已完成/取消的任务移至 archive/YYYY/MM/DD/TODO.md，并复制引用的 resources/。
• --dry-run 仅预览，不落盘；自动去重同一行。

自动提交

• 默认开启，提交信息模板 gitodo {action}: {summary}；可通过 --no-commit 或配置 auto_commit=false 关闭。