gh gist 代码片段命令速查手册

开篇：把 Gist 想成办公桌上的便利贴#

办公室桌上有一种便利贴：不用建一个完整文件夹，随手撕一张，写上要点，贴在显示器边上，或者撕下来递给同事，大家都能看到。它轻、快、随处可贴，用完还能撕掉。

Gist（代码片段） 就是 GitHub 上的”便利贴”：不用建仓库、不用写 README，直接把一段代码、一段配置、一段笔记贴上去，立刻获得一个链接，发给任何人就能看。你可以贴公开的（谁都能搜到），也可以贴私密的（只有有链接的人能看到）。

gh gist 系列命令，让你在终端里直接写便利贴、贴便利贴、翻便利贴，全程不用开浏览器。

原理先讲清：Gist 与仓库有什么不同#

特别提醒一个容易搞反的点：gh gist create 默认创建的是”私密（secret）“Gist，想公开必须显式加 --public。私密不等于绝对保密——它只是”不在搜索中公开”，任何拿到链接的人都能看。

场景 1：快速分享代码（分享给朋友/论坛/同事）#

你在写代码时遇到一个报错，想把报错相关的几行代码发给论坛求助，或者把一个小技巧分享到群里。Gist 是最合适的载体。

1.1 创建并公开分享#

# 把一个文件发布为公开 gist（公开 = 可被搜索）
gh gist create --public hello.py

# 加上描述，方便对方一眼看懂
gh gist create hello.py -d "我的第一个 Python 程序"

# 多个文件打包成一个 gist（比如一个需求 + 对应脚本）
gh gist create solve.py README.md

# 用通配符一次选择多个文件
gh gist create *.md *.txt

# 创建后立刻在浏览器打开（--web）
gh gist create --public hello.py -d "分享片段" --web

1.2 从标准输入创建（不需要先存文件）#

有时候内容就在终端里（比如上一条命令的输出），可以直接”管道”给 gist：

# 把命令输出直接变成 gist（cat 文件内容管道给 gh）
cat cool.txt | gh gist create

# 手动粘贴内容，-f 指定文件名（否则会没有文件名）
echo "console.log('hello')" | gh gist create -f script.js

# 从标准输入创建并加描述
printf 'def add(a, b):\n    return a + b\n' | gh gist create -f add.py -d "加法函数"

1.3 拿到链接#

创建成功后终端会打印类似输出：

- https://gist.github.com/fanquanpp/8f1a2b3c4d5e6f7a8b9c0d1e

把这个链接发给对方即可。对方可以看、可以克隆，甚至可以基于它继续编辑（权限允许时）。

场景 2：个人笔记与配置备份（给自己留底）#

每个人的终端都有一堆”宝贝配置”：.bashrc 的别名、.vimrc、某段数据库 SQL、某个环境变量清单。把它们丢进私密 Gist，等于给自己建了一个云端口袋本——换电脑、换环境时一条命令取回。

2.1 创建私密备份#

# 默认就是私密（secret），适合存个人配置
gh gist create .bashrc -d "我的 bash 配置备份"

# 明确强调私密：加 --public=false 或者干脆不加 --public 即可
gh gist create my_sql_notes.sql -d "常用 SQL 备忘"

2.2 列出与查看自己的片段#

# 列出我所有 gist（最近在前）
gh gist list

# 限制显示条数
gh gist list --limit 20

# 查看某个 gist 的内容
gh gist view 8f1a2b3c4d5e6f7a8b9c0d1e

# 只查看其中某一个文件（多文件 gist 时很有用）
gh gist view 8f1a2b3c4d5e6f7a8b9c0d1e --filename .bashrc

# 列出 gist 里有哪些文件
gh gist view 8f1a2b3c4d5e6f7a8b9c0d1e --files

# 看原始内容（不做任何渲染美化，适合管道给其他命令）
gh gist view 8f1a2b3c4d5e6f7a8b9c0d1e --raw

gh gist list 典型输出：

ID                  DESCRIPTION         FILES  VISIBILITY  UPDATED
8f1a2b3c4d5e6f7a8b9c0d1e  我的 bash 配置备份  1      secret      2 minutes ago
1a2b3c4d5e6f7a8b9c0d1e2f  面试算法题整理      3      public      3 days ago

2.3 恢复备份（克隆到本地）#

# 把 gist 克隆为本地目录（它本质是个 git 仓库）
gh gist clone 8f1a2b3c4d5e6f7a8b9c0d1e my-dotfiles

# 克隆后就是一个普通 git 仓库，可以提交修改再推回
cd my-dotfiles
cp ~/.bashrc .
git add .bashrc
git commit -m "更新配置"
git push

场景 3：代码片段管理与复用（维护自己的片段库）#

片段攒多了就要整理：改内容、重命名文件、删掉过时的。这就是”便利贴的日常维护”。

3.1 编辑内容#

# 编辑 gist 内容（默认会用编辑器打开，可逐行修改）
gh gist edit 8f1a2b3c4d5e6f7a8b9c0d1e

# 直接用本地文件的内容替换 gist 中的同名文件
gh gist edit 8f1a2b3c4d5e6f7a8b9c0d1e new_content.py

3.2 重命名文件#

# 把 gist 里的 old.js 改名为 new.js
gh gist rename 8f1a2b3c4d5e6f7a8b9c0d1e old.js new.js

3.3 删除过时片段#

# 删除 gist（--yes 跳过确认；删除不可恢复，谨慎操作）
gh gist delete 8f1a2b3c4d5e6f7a8b9c0d1e --yes

3.4 在浏览器中管理#

# 在浏览器打开某个 gist
gh gist view 8f1a2b3c4d5e6f7a8b9c0d1e --web

# 打开你自己的全部 gist 列表页
gh gist list --web

三个场景的命令地图#

进阶技巧：让 Gist 更好用#

技巧 1：Gist 也是一个 Git 仓库#

每个 Gist 底层就是一个微型 Git 仓库，因此 Git 的版本历史、分支、评论功能都适用：

# 克隆后查看提交历史（每次编辑都是一次提交）
gh gist clone 8f1a2b3c4d5e6f7a8b9c0d1e snippet
cd snippet
git log --oneline

# 拉取最新修改（别人在你的 gist 上提交后）
git pull

技巧 2：用 —json 配合脚本化统计#

# 输出 JSON 格式的 gist 列表（字段：id、description、files、visibility 等）
gh gist list --json id,description,files

# 统计公开 gist 数量
gh gist list --json visibility --jq '[.[] | select(.visibility == "public")] | length'

技巧 3：Gist 可以嵌入网页#

公开 Gist 支持嵌入（embed），把创建成功后得到的 <script src="https://gist.github.com/...js"></script> 代码粘贴到网页/博客/笔记软件中，就能直接展示代码片段——很多技术博客的代码就是这么来的。

技巧 4：命名规范建议#

• 描述（-d）必填：不加描述的 gist 在列表里很难辨认；
• 文件名带后缀：.py、.js、.md 等后缀决定语法高亮，从 stdin 创建时务必用 -f 指定；
• 前缀分类：私密片段可用 todo-、conf-、note- 之类前缀，配合 list --json files 便于检索。

常见错误与对策#

一句话记忆#

Gist 是 GitHub 的”便利贴”：create 写贴纸（默认私密，--public 才公开），view/list 翻贴纸，edit/rename/delete 整理贴纸，clone 把贴纸变成正式文件。