我的博客

gh看板功能

GitHub CLI（gh project）看板完整使用文档

我将整合所有 gh project 看板核心命令，搭配统一虚拟示例（仓库名：bacai）、详细释义、实操案例，整理成一份完整可直接复用的 GitHub CLI 看板使用文档，内容通俗、适配个人 ToDo 跨仓库任务管理场景。

一、前置说明

  1. 环境：已安装、登录 GitHub CLI（gh）
  2. 统一虚拟示例：个人仓库 bacai，所有命令可直接替换复用
  3. 核心特性：GitHub 看板为账号级独立工具，不绑定仓库、支持跨仓库管理、支持纯个人草稿 ToDo 任务
  4. 输出格式区别：
    • 默认输出：人性化表格文本（适合日常查看）
      • --format json：输出完整原始数据（适合脚本批量操作、精准取值）

二、一、查看所有个人看板

（一）命令

gh project list

（二）详细解释

遍历读取当前登录 GitHub 账号下全部创建的看板，输出看板名称、唯一ID、创建时间，所有后续操作都依赖看板ID，是最基础的前置查询命令。

（三）实操示例

直接执行即可，无需参数，执行后会列出类似结果：

ID      Title               State
123456  个人技术任务看板     open

记录返回的 ID（示例：123456），作为后续所有命令的固定参数。

三、二、查看单个看板基础信息

（一）基础命令（默认文本格式）

gh project view 看板ID

（二）进阶命令（完整JSON数据）

gh project view 看板ID --format json

（三）详细解释

  • 普通模式：展示看板名称、简介、创建人、状态、内置字段（待办/进行中/已完成）
  • JSON模式：输出全部隐藏参数（字段ID、列ID、权限、配置信息），用于高级修改、自动化脚本

（四）实操示例

gh project view 123456

四、三、新建独立个人看板（核心：无仓库绑定）

（一）命令

gh project create --title "看板名称" --readme "看板简介说明"

（二）详细解释

  1. 该命令创建账号级独立看板，不绑定任何代码仓库，纯任务管理工具
  2. --title：看板展示名称（必填）
  3. --readme：看板简介文案（重点！不是仓库README文件）
    • 仅展示在看板网页顶部介绍区域
      • 不会生成任何本地/仓库文件，仅云端文字备注

（三）实操示例（个人跨仓库Todo看板）

gh project create --title "霸彩个人技术任务总看板" --readme "统一管理bacai仓库及所有个人技术调试、运维、学习待办任务"

五、四、查看看板内所有任务卡片

（一）基础命令

gh project item-list 看板ID

（二）进阶JSON格式

gh project item-list 看板ID --format json

（三）详细解释

读取指定看板内所有任务卡片，包含：手动新建草稿任务、关联的Issue、关联的PR，展示任务标题、状态、创建时间、卡片唯一ID。 日常查看看板全部待办、进度，最常用这条命令。

（四）实操示例

gh project item-list 123456

六、五、新建纯个人草稿任务（无仓库、纯ToDo）

（一）命令

gh project item-create 看板ID --title "任务内容"

（二）详细解释

核心万能功能！创建独立草稿任务卡片：

  1. 不归属任何仓库、不需要Issue、不产生代码记录
  2. 仅作为个人待办、日常任务使用，完美替代TodoList
  3. 支持后续修改状态、归档、删除

（三）实操示例（bacai仓库运维任务）

gh project item-create 123456 --title "调试bacai仓库KVM虚拟化脚本"
gh project item-create 123456 --title "整理bacai仓库gh命令学习笔记"

七、六、将仓库Issue添加到看板（绑定仓库任务）

（一）命令

gh project item-add 看板ID --url Issue完整链接

（二）详细解释

将 bacai仓库真实的Issue缺陷/需求工单 拉入看板统一管理，支持跨仓库拉入多个Issue，实现多项目任务汇总。

（三）实操示例

假设 bacai 仓库第3号Issue，链接直接填入：

gh project item-add 123456 --url [https://github.com/](https://github.com/)你的用户名/bacai/issues/3

八、七、修改任务卡片状态（拖拽等效命令）

（一）命令

gh project item-edit 看板ID --url 任务链接 --field "Status" --value "状态名称"

（二）详细解释

等效网页端拖拽卡片切换列，修改任务进度状态，默认三大状态：待办、进行中、已完成。

（三）实操示例

# 将bacai仓库Issue任务改为【进行中】
gh project item-edit 123456 --url [https://github.com/](https://github.com/)你的用户名/bacai/issues/3 --field "Status" --value "进行中"

九、八、归档已完成任务（保留记录、隐藏看板）

（一）命令

gh project item-archive 看板ID --id 卡片ID

（二）详细解释

  1. 归档≠删除：任务数据保留云端，可随时恢复
  2. 归档后自动移出看板主界面，适合清理已完成任务，保持看板整洁

（三）实操示例

gh project item-archive 123456 --id 987654

十、九、彻底删除看板任务卡片

（一）命令

gh project item-delete 看板ID --id 卡片ID

（二）详细解释

永久删除看板内指定卡片，不可恢复，仅用于无效、废弃任务清理。

（三）实操示例

gh project item-delete 123456 --id 987654

十一、十、终端一键打开网页看板

（一）命令

gh project view 看板ID --web

（二）详细解释

无需手动打开浏览器、查找地址，终端一键唤起浏览器，直达看板网页端，方便可视化拖拽、编辑复杂内容。

（三）实操示例

gh project view 123456 --web

十二、补充：终端可视化看板（增强工具）

（一）安装扩展

gh extension install dlvhdr/gh-dash

（二）启动终端全功能看板

gh dash

（三）作用

终端内可视化展示：看板任务、Issue、PR，全程不用打开浏览器，纯终端管理所有GitHub任务。

十三、核心总结

  1. 看板独立于仓库，可做全局个人Todo清单，远超单一仓库管理
  2. item-create 草稿任务 = 纯个人待办，无任何仓库依赖
  3. item-add = 绑定仓库正式Issue任务，实现工作任务汇总
  4. 日常运维、代码学习、跨项目统筹，完全可以只用这一套命令全覆盖