mitsuhiko/gh-issue-sync

gh-issue-sync 是做什么的？

将 GitHub Issue 同步到本地的 Markdown 文件，存放在 .issues/open/ 和 .issues/closed/ 目录中。

命令

gh-issue-sync init              # 在 Git 仓库中初始化
gh-issue-sync pull              # 拉取开放的 Issue（加上 --all 可拉取已关闭的）
gh-issue-sync push              # 推送本地修改（加上 --dry-run 预览效果）
gh-issue-sync list              # 列出 Issue（支持 gh issue list 的标志 + --search）
gh-issue-sync new "标题"         # 创建 Issue（支持 --label、--edit）
gh-issue-sync close 42          # 关闭 Issue（支持 --reason completed|not_planned）
gh-issue-sync reopen 42
gh-issue-sync status            # 显示本地修改状态
gh-issue-sync diff 42           # 显示差异（加上 --remote 重新拉取远程版本）

文件格式

.issues/open/42-fix-login-bug.md：

---
title: 修复登录 bug
labels: [bug, priority:high]
assignees: [alice]
milestone: v1.0
state: open
# 对于已关闭的 Issue：state_reason: completed|not_planned
# 可选：parent: 10, blocked_by: [11, 12], blocks: [15]
---

Issue 正文，Markdown 格式。

Issue 编号从文件名中提取，不存储在 frontmatter 中。

临时 Issue

新建 Issue 时会获得一个以 T 为前缀的 ID（例如 T1a2b3c）。文件名必须以 T 开头：

.issues/open/T1a2b3c-my-new-issue.md

在 push 时，文件会被重命名为真实的 Issue 编号（例如 42-my-new-issue.md），并且 frontmatter 中的 number: 会被更新。其他 Issue 中所有 #T1a2b3c 的引用也会被更新为 #42。

评论

若要在推送时添加评论，请在 Issue 文件旁边创建一个 .comment.md 文件：

.issues/open/42.comment.md
.issues/open/42-fix-login-bug.comment.md

内容为纯 Markdown 格式。评论发布后，该文件会被自动删除。

备注

• Pull 操作会跳过冲突；使用 --force 可以覆盖本地文件