【gh】GitHub CLI で gist のコマンドライン操作【公式 gist コマンドの使い方】【日本語ヘルプ】

<h1>GitHub gist をコマンドラインから操作する</h1>

> GitHub 公式の [GitHub 操作用コマンド・ライン・ツール](https://github.com/cli/cli) **`gh` の `gist` コマンドで操作できる内容**を知りたい。

例えば「gist 内の特定ファイルを削除する仕方」など。つまり、`git` で `pull` して削除してから `push` するような手間を省きたいのです。

## TL; DR <sub><sup>（今北産業）</sup></sub>

1. GitHub リポジトリの wiki 同様に、**gist も git リポジトリ**である。<br>しかし、新規作成などは `git` ではできないため、GitHub API を叩かなくてはいけない。
1. `gh`（[github.com/cli/cli](https://github.com/cli/cli)） は GitHub の API を叩ける GitHub 公式の CLI ツールである。<br>サブコマンドに `gh gist` があるため、`gist` 操作が可能である。
1. `gist` コマンドの一覧。（ヘルプの日本語訳は TS; DR 参照）

    | コマンド | 概要 |
    | :---------------: | :-- |
    | `gh gist clone` | `gist` をローカルに `clone` する。|
    | `gh gist create` | 指定したファイルやディレクトリを `gist` として GitHub に登録する。|
    | `gh gist delete` | 指定した `gist` ID もしくは URL の `gist` を削除する。|
    | `gh gist edit` | 指定した `gist` 内のファイルを編集・更新（置き換え）・追加・削除する。|
    | `gh gist list` | ユーザの `gist` 一覧を表示する。|
    | `gh gist view` | 指定した `gist` ID もしくは URL の `gist` を閲覧する。|
<!--
    | `gh api /gists/<GIST_ID>/forks` | 指定した他者の gist ID を自分のアカウントに fork する。|
    | `gh api /gists/<GIST_ID>/star` | 指定した gist ID のスター数を取得する。|
-->

- [GitHub CLI & hub](https://github.com/cli/cli/blob/trunk/docs/gh-vs-hub.md)（gh と hub の違い） | GitHub CLI @ GitHub - [[Google 翻訳](https://github-com.translate.goog/cli/cli/blob/trunk/docs/gh-vs-hub.md?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja&_x_tr_pto=wapp)]

## TS; DR <sub><sup>（gist をコマンドで操作するためのコマケーこと）</sup></sub>

:::note info
以下のいずれのコマンドも、あらかじめ GitHub にログインしておく必要があります。事前に以下のコマンドでログインしておいてから利用します。

```bash
gh auth login
```

GitHub の 2 要素認証が有効な場合など、環境変数 `GITHUB_TOKEN` にパーソナル・アクセス・トークンを指定している場合は、`gist` [スコープ](https://qiita.com/KEINOS/items/216d138b0fdf994b9582)も含まれている必要があります。
:::

### gist のヘルプ日本語訳＋追加情報

#### `gist --help`

```shell-session
$ gh gist --help
GitHub の gist を扱うことができます。

使用方法
  gh gist <command> [ flags ]

主なコマンド
  clone:   gist をローカルにクローンする
  create:  新しい gist を作成する
  delete:  gist を削除する
  edit:    gist のファイルを編集する（追加・編集・置き換え・削除）
  list:    gist 一覧をリストアップする
  view:    gist 内のファイルを表示する

継承フラグ
  -h, --help コマンドのヘルプを表示します。（すべてのコマンドで有効です）

引数について
  各コマンドで gist を指定する場合、以下のいずれかの形式で引数として渡せます。
    - ID で指定する（例：5b0e0062eb8e9654adad7bb1d81cc75f）
    - URL で指定する（例："https://gist.github.com/OWNER/5b0e0062eb8e9654adad7bb1d81cc75f"）

詳細はこちら
  各コマンドの詳細情報を得るには、"gh <command> <subcommand> --help" を使用します。
  マニュアルは https://cli.github.com/manual で読んでください．
```

#### `gist clone`

```shell-session
$ gh gist clone --help
GitHub の gist をローカルにクローンします。

使用方法
  gh gist clone <gist> [ <directory> ] [ -- <gitflags>... ]

引数
  gist
    クローン対象の gist を指定します。gist は、以下のいずれかの形式で
    引数として与えることができます。
      - ID で指定する（例：5b0e0062eb8e9654adad7bb1d81cc75f）
      - URL で指定する（例："https://gist.github.com/OWNER/5b0e0062eb8e9654adad7bb1d81cc75f"）

引数（オプション）
  directory
    クローン先のディレクトリ名を指定します。未指定の場合は gist ID が使われます。
  -- <gitflags>
    ローカルにクローンする際の `git clone` にフラグを渡すこともできます。
    '--' の後に `git clone` のフラグを追加して指定します。
```

- `gh gist clone` は `git clone` のラッパー・コマンドで、gist ID を URL に変換してから `git clone` します。

#### `gist create`

```shell-session
$ gh gist create --help
指定された内容の GitHub gist を新規に作成します。正常に作成されると gist の
URL が返されます。

Gist は 1 つ、または複数のファイルから作成することができます。ファイル名を
'-' と指定すると、標準入力から内容を読み込みます。

デフォルトでは、gist は非公開（Private）で作成されます。一般に公開する場合
は '--public' フラグを使用します。

使用方法
  gh gist create [ <filename>... | - ] [ flags ]

引数（オプション）
  <filename>... | -
    gist に含めるファイル名を指定します。1 つまたは複数のファイルから作成するこ
    とができます。未指定の場合は、"-" と同等になり、標準入力から内容を読み取ろう
    とします。ファイル名が "-" の場合は、gist の内容を標準入力から読み取ります。
    "-" は、ファイル名の指定と併用はできません。

  flags
    -d, --desc string     この gist の説明文を指定します。
    -f, --filename string 標準入力から読み込むときに使用するファイル名を指定し
                          ます。
    -p, --public          gist を一般公開で `push` します。(デフォルト: 非公開)
    -w, --web             作成した GitHub 上の gist をウェブブラウザで開きます。
```
```shell-session:使用例
  $ # ローカルファイル 'hello.py' を一般公開 gist として公開する。
  $ gh gist create --public hello.py
  
  $ # 説明文付きの gist を作成する
  $ gh gist create hello.py -d "my Hello-World program in Python"
  
  $ # 複数のファイルを含む gist を作成する
  $ gh gist create hello.py world.py cool.txt
    
  $ # 他のコマンドからパイプ渡しされた内容から gist を作成します。
  $ # この場合のファイル名は "gist:<ID>" という書式で作成されます。
  $ cat cool.txt | gh gist create

  $ # 他のコマンドからパイプ渡しされた内容を、ファイル名付きで gist を作成します。
  $ cat foo.txt | gh gist create - -f bar.txt
```

- GitHub API のメソッドとエンドポイント:
  - `POST https://api.github.com/gists`
- 公式ドキュメント:
  - [Create a gist](https://docs.github.com/en/rest/reference/gists#create-a-gist) @ docs.github.com
- このコマンドには "gist" の[スコープ](https://qiita.com/KEINOS/items/216d138b0fdf994b9582)が必要です。スコープが足りない場合は、以下のコマンドで追加できます。環境変数 `GITHUB_TOKEN` にパーソナル・アクセス・トークンを指定している場合は、`gist` スコープ付きのアクセス・トークンに置き換える必要があります。

  ```bash:現在のスコープにgistを追加して再読み込みする
  gh auth refresh -h github.com -s gist
  ```

#### `gist delete`

```shell-session
$ gh gist delete --help
指定された gist を削除します。

使用方法
  gh gist delete <gist> [ flags ]

引数
  gist
    クローン対象の gist を指定します。gist は、以下のいずれかの形式で
    引数として与えることができます。
      - ID で指定する（例：5b0e0062eb8e9654adad7bb1d81cc75f）
      - URL で指定する（例："https://gist.github.com/OWNER/5b0e0062eb8e9654adad7bb1d81cc75f"）

引数（オプション）
  flags
    -h, --help このコマンドのヘルプを表示します。
```

- GitHub API のメソッドとエンドポイント:
  - `DELETE https://api.github.com/gists/<GIST_ID>`
- 公式ドキュメント:
  - [Delete a gist](https://docs.github.com/en/rest/reference/gists#delete-a-gistt) @ docs.github.com

#### `gist edit`

```shell-session
$ gh gist edit --help
指定された gist を編集します。

gist の説明文更新、ファイルの追加・編集・置き換え・削除などができます。
対話モードで gist 内の特定ファイルを編集する場合は、`git` に紐付けさ
れているエディタが起動します。ファイルの削除は内容を空にすることで行え
ます。

使用方法
  gh gist edit <gist> [ <filename> | - ] [ flags ]

引数
  gist
    編集対象の gist を指定します。gist は、以下のいずれかの形式で指
    定できます。
      - ID で指定する（例：5b0e0062eb8e9654adad7bb1d81cc75f）
      - URL で指定する（例："https://gist.github.com/OWNER/5b0e0062eb8e9654adad7bb1d81cc75f"）

引数（オプション）
  <filename> | -
    ローカルにあるデータで置き換えたい場合に指定します。指定がない場
    合は対話モードになり、gist 内の対象ファイルを選択後、エディタが
    起動します。
    `-` が指定された場合は、標準入力からの内容で置き換えます。置き換
    え先（gist 内の対象ファイル）を指定する場合は `-f` `--filename`
    フラグを利用します。

  flags
    -a, --add string       gist に新しいファイルを追加します。
    -d, --desc string      gist の説明文を変更します。
    -f, --filename string  編集対象の gist のファイルを指定します。
```
```shell-session:使用例
  $ # ファイルの編集（対話式）
  $ # ID ea5ef...71518 の gist 内のファイルを対話式で選択し編集します。
  $ gh gist edit ea5ef308ac22d0b8de925489fd971518

  $ # ファイルの編集
  $ # ID ea5ef...71518 の gist 内にある foo.txt をエディタで編集します。
  $ gh gist edit ea5ef308ac22d0b8de925489fd971518 -f foo.txt

  $ # ファイルの追加（ローカル・ファイル）
  $ # ローカルの foo.txt を ID ea5ef...71518 の gist に bar.txt として追加し
  $ # ます。
  $ gh gist edit ea5ef308ac22d0b8de925489fd971518 foo.txt --add bar.txt

  $ # ファイルの追加（標準入力）
  $ # 標準入力の内容を ID ea5ef...71518 の gist に cool.txt として追加します。
  $ cat cool.txt | gh gist edit ea5ef308ac22d0b8de925489fd971518 - --add cool.txt

  $ # 置き換え
  $ # ローカルの foo.txt の内容と ID ea5ef...71518 の gist にある bar.txt を
  $ # 置き換えます。
  $ gh gist edit ea5ef308ac22d0b8de925489fd971518 foo.txt -f bar.txt

  $ # ファイルの削除
  $ # ID ea5ef...71518 の gist にある cool.txt を空のデータに置き換えることで
  $ # cool.txt を削除します。
  $ echo '' | gh gist edit ea5ef308ac22d0b8de925489fd971518 - -f cool.txt
```

- GitHub API のメソッドとエンドポイント:
  - `DELETE https://api.github.com/gists/<GIST_ID>`
- 公式ドキュメント:
  - [Delete a gist](https://docs.github.com/en/rest/reference/gists#delete-a-gistt) @ docs.github.com

#### `gist list`

```shell-session
$ gh gist list --help
ログイン中の、ユーザの gist 一覧をリストアップします。

gist 内のファイルではなく、gist のリポジトリ一覧です。

使用方法
  gh gist list [ flags ]

引数（オプション）
  flags
    -L, --limit int   1 回で取得する gist の最大数 (デフォルト:10、最大:100)
        --public      一般公開されている gist のみを表示
        --secret      非公開の gist のみを表示
```

- GitHub API のメソッドとエンドポイント:
  - `GET https://api.github.com/gists`（非公開および公開 gist）
  - `GET https://api.github.com/gists/public`（公開 gist のみ）
- 公式ドキュメント:
  - [List gists for the authenticated user](https://docs.github.com/en/rest/reference/gists#list-gists-for-the-authenticated-user) @ docs.github.com
  - [List public gists](https://docs.github.com/en/rest/reference/gists#list-public-gists) @ docs.github.com
- 現在の `gh gist` コマンドは、ページ指定を実装していないため、gist のリポジトリ数が 100 件を超える場合は GitHub API を利用する必要があります。

#### `gist view`

```shell-session
$ gh gist view --help
指定された gist、もしくは最近の gist から選択して、gist の内容を表示します。

gist 内のファイルの拡張子が ".md" の場合は、レンダリング（色付け）されて表示されます。

使用方法
  gh gist view [ <gist> ] [ flags ]

引数（オプション）
  gist
    表示対象の gist を指定します。gist は、以下のいずれかの形式で指
    定できます。他者の公開 gist も指定可能です。指定がない場合は、対
    話モードで gist を選択します。
      - ID で指定する（例：5b0e0062eb8e9654adad7bb1d81cc75f）
      - URL で指定する（例："https://gist.github.com/OWNER/5b0e0062eb8e9654adad7bb1d81cc75f"）    

  flags
    -f, --filename string   gist から指定したファイルだけを表示する。
        --files             gist のファイル名を列挙する。
    -r, --raw               レンダリングされた gist の内容ではなく、生の内容を
                            表示する。
    -w, --web               gist をブラウザで開く。

```
```shell-session:使用例
  $ # gist を選択して表示（対話式）
  $ gh gist view

  $ # gist を指定して表示
  $ gh gist view ac42062c9d30dbd18b21eef4cc1e4615

  $ # 指定した gist 内の foo.txt の内容を表示
  $ gh gist view ea5ef308ac22d0b8de925489fd971518 -f foo.txt

  $ # GitHub 上の指定した gist をブラウザで表示
  $ gh gist view ea5ef308ac22d0b8de925489fd971518 --web
```