重新发明问题跟踪:本地优先与Git原生

Lobsters Hottest 工具

摘要

本文讨论了为Manganin设计的Git原生、本地优先的问题跟踪系统,重点是将问题存储在Git中以避免依赖,并支持离线、符合人体工学的工作流程。

<p><a href="https://lobste.rs/s/4tb4nk/reinventing_issue_tracking_local_first">评论</a></p>
查看原文
查看缓存全文

缓存时间: 2026/09/16 11:24

# 本地优先与Git原生设计——Manganin 来源:https://blog.manganin.dev/blog/reinventing-issue-tracking/ 协作的核心要素在于共享的问题追踪环境。在为Manganin设计问题追踪系统时,我已明确了一些核心需求: - 问题数据必须存储于Git中,且需充分发挥Git工具的优势而非与之对抗。Git虽是强大的版本控制工具,却非传统数据库的理想选择。接入Postgres虽是常规做法,但会引入供应商锁定问题、增加依赖关系(https://github.com/tigerbeetle/tigerbeetle/blob/main/docs/TIGER_STYLE.md#dependencies)并使部署复杂化。 - 必须支持通过命令行操作问题,且在断网期间仍能符合人体工学地工作,**无需**安装额外工具。这正是我将"本地优先"作为Manganin核心原则的含义——所有核心功能都应在本地设备实现,无需网络连接或复杂配置。工作流应与你已熟悉并精心配置的成熟工具无缝集成。一款凝聚数十年工程师心血的开源工具,在体验上必然优于用专有技术栈快速拼凑的Electron应用。 我很快意识到,同时满足这两点并保持可用性,难度远超预期。本篇开发日志将阐述我针对这些问题追踪需求提出的解决方案,并记录过程中遭遇的(诸多)失败尝试。 ## 问题与代码共存 最直接的方案是在项目根目录设立`.issues/`目录,每个文件对应一个问题。这看似巧妙——问题与代码绑定,每个分支维护独立的问题状态,可在同一提交中关闭问题。但当我推演这个方案至逻辑终点时,发现它也隐藏着致命缺陷:当新问题在(主分支)上创建时,应如何关联到各个活跃分支?难道要不断变基以同步新问题?这显然不可行—— ### 变基问题 问题更新频率通常远高于代码提交。每当有人创建、编辑、关闭或重新打开问题,都必须执行拉取操作。一旦项目进入快速开发期,这种模式将迅速变得难以维护。 ## 特殊引用机制 Git通过引用(refs)存储跟踪信息。分支存储在`refs/heads`,标签通常记录在`refs/tags`。我在Recurse Center(https://recurse.com/)了解到一个技巧:通过非传统命名的引用指向任意数据,可在Git中存储数据,且完全不会干扰(但能正常传播至)GitHub等仓库托管平台。可以将问题追踪信息存放于此,既能避免污染源代码树,又随仓库一起克隆。每个问题会被分配自增整数ID,通过`refs/issues/12`这类地址进行引用。 但这种方法会使本地编辑问题变得异常繁琐。实际开发中采用此方案可能需下载专用工具来管理复杂性。Git的设计初衷并非如此,其操作便捷性问题暴露无遗。本质上只是小型文本文件,却被多层复杂结构包裹——层数越多,故障概率越高,信息冗余越严重(单个问题实际对应4种不同ID)。 编辑问题的技术流程 Git使用对象ID(OID)寻址存储对象。我们需要先将数据存入Git数据库,再通过引用指向它,以便其他命令或工具发现,同时防止其被垃圾回收。首先使用`git hash-object -w`将数据存入数据库,获得"blob"的OID。接着需要将blob转化为树对象,再将树对象转化为提交对象。最后通过`git update-ref`让引用指向该提交。若未执行最后一步,新对象将无法被引用,在流程中途失败时所有对象都会被垃圾回收,确保原子性。```bash # 返回新写入blob的OID git hash-object -w {新内容} # 上一步获得了"blob"的OID # 若树对象中存在其他内容,需重新添加 echo "100644 blob {issue_oid}\tissue.txt\n" | git mktree # 注意该命令与`git commit`的相似性 git commit-tree -m " " {树对象OID} git update-ref refs/issues/{id} {提交对象OID} ``` 注:此为简化流程。实际`git update-ref`命令需要额外参数防止数据竞争。此方法还存在其他问题,尤其涉及避免多人编辑同一问题时的冲突与竞态条件。实现该方法引发了诸多思考:应如何处理冲突与无效数据?问题ID究竟代表什么? ## 简单至上 我暂停开发数周重新思考。由于长期使用为SQL后端构建的现有软件,我形成了对问题追踪的固有认知。如果抛开这些预设观念,尝试与Git*协同*工作会怎样?事后看来解决方案显而易见:按理想方式工作,构建支持该工作流的工具。 强行让Git模拟关系数据库会导致系统过度复杂化。若要让Git跟踪与源代码分离的内容,就应将其独立存储。与其强制将两种不同事物耦合存储,不如采用最符合人体工学的方式分离存储,再通过工具弥合间隙。 Manganin现在使用独立仓库存储问题数据。创建新仓库时会自动生成隐藏的姊妹仓库用于问题追踪。该仓库不会出现在前端的仓库列表中,而是解析内部数据并以类似其他代码托管平台的方式呈现:展示问题标题与内容的列表。该仓库可通过特殊路径克隆,因此并非所有代码库克隆者都需要下载全部问题追踪数据。 问题本身以透明文件形式存储。文件各部分均为语义化设计:文件名即问题标题(合法路径的构成可能会让你惊讶),文件内容即问题详情。此类工作流应用广泛,Git、文件系统及其他工具都能良好支持。我在Neovim中使用FZF进行日常问题浏览与分类管理。 无需为问题ID设计自增整数——文件系统本身保证文件名唯一。若文件名作为标识符不足(目前尚未遇到不适用场景),也可使用Git对象ID。 ## 精简之道 将复杂思想提炼为精简方案需要时间沉淀。寻找最优雅解决方案必须经过反复试错。最终产出的系统应当自然天成,令人感受不到背后的匠心。理想的工具应默默辅助,让你专注创造。 优化过程是迭代的。在使用Manganin进行问题追踪时,我持续记录痛点——这些正是需要精妙工具来优化工作流的环节。提升而非复杂化的关键在于:从用户体验反向设计架构以提供支撑。

相似文章

Manganin:工具至关重要

Lobsters Hottest

Manganin 是一个用 Zig 编写的新 Git 伪造,它通过基于信任的担保树和自托管设计重新构想了源代码管理,从而避免了供应商锁定。

Show HN:Epiq – 基于Git的分布式问题追踪器TUI

Hacker News Top

Epiq 是一款终端原生、基于Git的问题追踪器,具有 ASCII 看板、不可变事件日志,并支持 MCP 以实现代理工作流。它允许以本地优先的方式进行分布式协作,无需中心服务。

@itsclelia: I have one big problem with agentic engineering: I want agents to operate autonomously, but I also want granular, rever…

X AI KOLs Timeline

I have one big problem with agentic engineering: I want agents to operate autonomously, but I also want granular, reversible control over every change they make. I could solve this by committing every intermediate step to Git, but that would completely pollute my repo history. So I built 𝗮𝗴𝗴𝗶𝘁: a Git-like CLI for local and remote (S3-backed) agent artifact storage, written in Rust . With aggit, my agents can stash intermediate work, create branches safely, restore previous states, and back