Gist 项目技术文档

1. 安装指南

1.1 使用 Ruby 安装

如果你已经安装了 Ruby，可以通过以下命令安装 gist：

gem install gist

1.2 使用 Bundler 安装

如果你使用 Bundler，可以在 Gemfile 中添加以下内容：

source :rubygems
gem 'gist'

1.3 使用 Homebrew 安装（适用于 OS X）

在 OS X 上，可以通过 Homebrew 安装 gist：

brew install gist

1.4 使用 FreeBSD 安装

在 FreeBSD 上，可以通过 ports 安装 gist：

pkg install gist

1.5 使用 Ubuntu/Debian 安装

在 Ubuntu/Debian 上，可以通过以下命令安装 gist：

apt install gist

注意：Debian 将二进制文件重命名为 gist-paste 以避免名称冲突。

2. 项目的使用说明

2.1 上传文件

要上传 a.rb 文件的内容，只需运行：

gist a.rb

2.2 上传多个文件

可以上传多个文件，例如：

gist a b c
gist *.rb

2.3 从标准输入读取内容

默认情况下，gist 从标准输入读取内容，并可以使用 -f 选项设置文件名：

gist -f test.rb <a.rb

2.4 从剪贴板粘贴内容

可以使用 -P 选项从剪贴板粘贴内容：

gist -P

2.5 创建私有 Gist

使用 -p 选项创建私有 Gist：

gist -p a.rb

2.6 添加描述

使用 -d 选项为 Gist 添加描述：

gist -d "Random rbx bug" a.rb

2.7 更新现有 Gist

可以使用 -u 选项更新现有 Gist：

gist -u GIST_ID FILE_NAME
gist -u 42f2c239d2eb57299408 test.txt

2.8 复制 URL 到剪贴板

使用 -c 选项将生成的 URL 复制到剪贴板：

gist -c <a.rb

2.9 打开浏览器

使用 -o 选项直接在浏览器中打开 Gist：

gist -o <a.rb

2.10 列出 Gist

可以列出用户的 Gist：

gist -l : 列出已认证用户的所有 Gist
gist -l defunkt : 列出 defunkt 的公开 Gist

2.11 读取 Gist

可以读取 Gist 并将其内容打印到标准输出：

gist -r GIST_ID
gist -r 374130

3. 项目API使用文档

3.1 使用 Gist 作为库

你可以在 Ruby 代码中使用 Gist 作为库：

Gist.gist("Look.at(:my => 'awesome').code")

3.2 高级功能

你可以传递以下参数以实现更高级的功能：

• :access_token：使用 OAuth2 进行身份验证（默认读取 ~/.gist 文件）。
• :filename：更改语法高亮（默认是 a.rb）。
• :public：如果你想让 Gist 的 URL 可猜测。
• :description：为 Gist 添加描述。
• :update：更新现有 Gist（可以是 URL 或 ID）。
• :copy：将生成的 URL 复制到剪贴板（默认是 false）。
• :open：在浏览器中打开生成的 URL（默认是 false）。

3.3 上传多个文件

你可以上传多个文件到同一个 Gist：

Gist.multi_gist("a.rb" => "Foo.bar", "a.py" => "Foo.bar")

3.4 强制用户获取 OAuth2 令牌

你可以强制用户获取 OAuth2 令牌并存储在 ~/.gist 文件中：

Gist.login!

4. 项目安装方式

4.1 登录

在使用 gist 之前，你需要登录。支持两种登录流程：

1. Github 设备代码 OAuth 流程：这是默认的身份验证方式，适用于 github.com。
2. 用户名和密码令牌交换流程：这是 GitHub Enterprise 的默认方式，但已被 GitHub 弃用。

4.2 设备代码流程

此流程允许你在浏览器中登录 GitHub 并输入验证码以获取令牌：

gist --login

4.3 用户名-密码流程

此流程要求你输入 GitHub 用户名和密码（以及 2FA 代码），并将其交换为具有 "gist" 权限的令牌：

gist --login

4.4 GitHub Enterprise

如果你想让 gist 使用本地安装的 GitHub Enterprise，需要导出 GITHUB_URL 环境变量：

export GITHUB_URL=http://github.internal.example.com/

4.5 令牌文件格式

如果你无法使用密码，可以通过 Web 界面生成令牌并将其保存到正确的文件中。避免换行符，否则可能会看到 Bad credentials 错误。