本文へ移動

CLI リファレンス ​

text
ghusage [OPTIONS] [COMMAND]

コマンドを指定しないと、ghusage は overview を実行します。グローバルオプションは、コマンドの前にも後ろにも置けます(ghusage --since 30d daily と ghusage daily --since 30d は同じです)。

コマンド ​

コマンド説明既定の期間
overview期間の概要(既定のコマンド)直近 7 日
daily日ごとの活動直近 7 日
weekly週ごとの活動(週は月曜日から始まります)直近 8 週
monthly暦月ごとの活動直近 6 か月
yearly暦年ごとの活動直近 3 年
reposリポジトリごとの活動直近 7 日
prs期間内に活動のあったプルリクエスト直近 7 日
reviews自分が提出したレビューと、自分が受けたレビュー直近 7 日
comments自分が書いたコメントと、自分のプルリクエストに付いたコメント直近 7 日
issues自分が作成・クローズ・再オープンした Issue直近 7 日
pr <URL>1つのプルリクエストの詳細とタイムライン(期間に依存しません)
commit <COMMIT>1 つのコミット。メッセージ、作者とコミッター、親コミット、変更ファイル。--patch を付けると diff も出す(期間に依存しません)
tui対話型のターミナル UI直近 30 日
syncGitHub からデータを取得してローカルのキャッシュに入れる直近 30 日
doctor認証、キャッシュ、接続を確認する
auth statusどの認証情報を使っているか、それが有効かを表示する
cache statusキャッシュの場所、サイズ、最後の同期、カバレッジを表示する
cache clearキャッシュした GitHub のデータをすべて削除する(認証情報は消えません)

「直近 7 日」は、今日とその前の 6 日間です。ローカル時刻の午前0時から始まり、現在時刻で終わります。「直近 8 週」は今週の 7 週前の月曜日から、「直近 6 か月」は今月の 5 か月前の月の1日から始まります。詳しくは期間とタイムゾーンを参照してください。

レポートのコマンド ​

overview、daily、weekly、monthly、yearly、repos、prs、reviews、comments、issues は、期間のうちまだ取得していない範囲を同期してから(--offline のときを除く)、レポートとそのカバレッジを表示します。それぞれの数値の意味は指標の定義を参照してください。

  • overview: 期間の概要と、上位 5 つのリポジトリ。
  • daily / weekly / monthly / yearly: 暦の区切りごとに1行と、合計の行。週は ISO 週番号(2026-W47)、月は 2026-11 の形で表示します。
  • repos: 期間内に活動のあったリポジトリごとに1行。自分の活動が多い順に並びます。公開範囲の後ろの * は自分が所有するリポジトリ、(no access) は同期中に GitHub がアクセスを拒否した(HTTP 403 または 404)リポジトリを示します。拒否されたリポジトリでも、キャッシュ済みのデータは残します。
  • reviews: 状態ごとの件数に続けて、自分が提出したレビューと、自分のプルリクエストにほかの人が提出したレビュー。
  • comments: 種類ごとの件数に続けて、自分が書いたコメントと、自分のプルリクエストで受けたコメントの一つひとつ。
  • issues: 件数、自分が作成した Issue のうちオープンなものの数(現在の状態)、期間内に自分が作成・クローズ・再オープンした Issue の一つひとつ。

prs ​

text
ghusage prs [--details] [--sort <SORT>] [--state <STATE>] [--all-participants]

期間内に活動のあったプルリクエストを一覧にします。

オプション説明
--detailsプルリクエストごとの活動の統計と、自分のプルリクエストのライフサイクルの所要時間も表示します
--sort <SORT>activity(既定。期間内のイベント数)、comments、reviews、created(作成日時)、updated(期間内の最後の活動)。常に大きい順・新しい順です
--state <STATE>現在の状態が open、closed(マージせずにクローズ)、merged のプルリクエストだけを表示します
--all-participants期間内にほかの人だけが活動を残したプルリクエストも含めます

既定では、期間内に自分のイベントが1つ以上あるプルリクエストだけを表示します。列の意味は指標の定義にあります。

Changes 列には、各プルリクエストの base と head の差分を +A -D の形で表示します(分からないときは ?)。これは最後に同期した時点のスナップショットで、期間中に行った変更ではありません。表の下にもその旨の注記を出します。プルリクエストの変更行数を参照してください。

pr ​

text
ghusage pr <URL> [--timeline] [--event-type <TYPES>]...

1つのプルリクエストについて、状態、作成者、マージ、コミット(プルリクエストにもう含まれていないコミットも含む)、状態ごとのレビュー、種類ごとのコメント、レビュースレッド(現在の状態)、最新の CI の結果、参加者、所要時間、カバレッジを表示します。Changes (current snapshot) の行には、プルリクエストの差分を +A -D in F files (base to head as of <時刻>) の形で表示します。まだ分からないときは、その旨を表示します。

オプション説明
<URL>https://github.com/OWNER/REPO/pull/NUMBER。後ろに /files などのパス、クエリ文字列、フラグメントが付いていても受け付けます
--timelineすべてのイベントを順に表示します(表形式の出力)。JSON と CSV には常にタイムラインが入ります
--event-type <TYPES>タイムラインに出すイベントの種類を絞ります。カンマ区切りでも、オプションの繰り返しでも指定できます。件数には影響しません

オンラインのときは、表示する前に必ずプルリクエストを取得し直します。取得に失敗し、そのプルリクエストがキャッシュにあれば、警告を出してキャッシュのデータを使います。--offline のときは、プルリクエストがすでにキャッシュにある必要があります。自分が関わっていないプルリクエストを表示しても、自分のレポートには加わりません。

イベントの種類: commit_authored、pr_opened、pr_converted_to_draft、pr_ready_for_review、pr_closed、pr_reopened、pr_merged、pr_commit、pr_head_force_pushed、review_submitted、review_dismissed、conversation_comment、inline_comment、review_summary、review_requested、review_request_removed、assigned、unassigned、labeled、unlabeled、milestoned、demilestoned、renamed、issue_opened、issue_closed、issue_reopened、check_run、commit_status。(commit_authored には、以前の名前の commit も引き続き使えます。)

sh
ghusage pr https://github.com/OWNER/REPO/pull/123 --timeline \
  --event-type review_submitted,inline_comment

commit ​

text
ghusage commit <COMMIT> [--patch]

1 つのコミットを表示します。表示するのは、リポジトリ、SHA、作者とコミッター(git の名前、ひも付いた GitHub のログイン名、日時)、親コミット(2 つ以上あればマージコミット)、メッセージの全文、変更ファイルの一覧です。変更ファイルには、状態(added、modified、removed、renamed など)、追加・削除した行数、合計を付けます。

オプション説明
<COMMIT>OWNER/REPO@SHA か https://github.com/OWNER/REPO/commit/SHA(.../pull/NUMBER/commits/SHA も可)。SHA は 7 桁以上の 16 進数に省略できる
--patch各ファイルの diff も出す。表形式では、色が有効なら追加した行を緑、削除した行を赤、hunk ヘッダーをシアンで表示する。JSON では各ファイルに patch フィールドが付く

コミットは、前に見たことがあれば(このコマンドでもターミナル UI でも)キャッシュから読みます。なければ GitHub から GET /repos/{owner}/{repo}/commits/{sha} で取得し、ファイルが複数ページにわたるときは全ページをたどって、キャッシュに保存します。コミットの中身がレポートの数値を変えることはありません。--offline のときは、コミットがすでにキャッシュにある必要があります。

GitHub は、バイナリファイルや大きすぎる diff を返しません。そのようなファイルは「no diff available from GitHub」と表示します。また、GitHub が 1 つのコミットについて返すファイルは 3000 件までです。それを超えて欠けたファイルがあるときはその旨を表示します(JSON では files_truncated)。--public-only のときは、公開されていないリポジトリのコミットを拒否します。

sh
ghusage commit OWNER/REPO@1a2b3c4 --patch
ghusage commit https://github.com/OWNER/REPO/commit/1a2b3c4d5e6f --format json

sync ​

text
ghusage sync [--full] [--diff-stats]

期間のデータを取得してキャッシュに入れます。--full を付けないと、まだ取得し終えていない範囲だけを取得します。--full を付けると、期間全体を取得し直します。--offline とは併用できません。同期とキャッシュも参照してください。

オプション説明
--fullまだ取得していない範囲だけでなく、期間全体を取得し直します
--diff-stats期間内の自分のコミットのうち、まだ行数が分からないものについて、追加・削除した行数も取得します(100 コミットごとに GraphQL のリクエスト 1 回)。行数の取得を参照してください

--diff-stats を付けると、出力に line counts: N commits (already known K, fetched F, unavailable U) の行が加わり、JSON の出力には diff_stats オブジェクトが入ります(JSON の出力を参照)。

フィルター(--repo、--owner、--visibility、--ownership)を指定しても、sync が取得する範囲は絞られません。

tui ​

対話型のターミナル UI を開きます。ターミナル UI を参照してください。

doctor ​

キャッシュを開けるか、整合性チェックに通るかを確かめ、最後の同期を表示します。--offline でなければ、認証情報が見つかるか、GitHub が受け付けるか、レート制限が残っているかも確かめます。いずれかのチェックに失敗すると、終了コード 1 で終わります。

text
$ ghusage doctor --offline
ok   cache opened: /Users/me/Library/Application Support/dev.ghusage.ghusage/ghusage.db
ok   cache integrity: ok
ok   offline: GitHub checks skipped

auth status ​

ログイン名、認証情報の取得元、トークンのスコープ(GitHub が返した場合)、レート制限を表示します。認証情報が見つからないとき、または GitHub が拒否したときは、終了コード 3 で失敗します。

cache status / cache clear ​

cache status は、データベースのパスとサイズ、スキーマのバージョン、リポジトリ・プルリクエスト・Issue・イベントの件数、最後の同期、直近 30 日のカバレッジを表示します。cache clear は、キャッシュしたデータをすべて削除します。

text
$ ghusage cache status
Cache: /Users/me/Library/Application Support/dev.ghusage.ghusage/ghusage.db
  size: 0.2 MiB, schema version 1
  repositories 0, pull requests 0, issues 0, events 0
  last sync: never

グローバルオプション ​

オプション説明
--since <SINCE>期間の開始。YYYY-MM-DD、RFC 3339、today、yesterday、または Nd / Nw / Nm / Ny(直近 N 日・週・月・年)
--until <UNTIL>期間の終了(この時刻は含みません)。日付を指定すると、その日がまるごと含まれます。既定は現在時刻です。ここには Nd/Nw/Nm/Ny を指定できません
--timezone <TZ>日・週・月の境界に使う IANA タイムゾーン(既定: TZ、次にシステムの設定、最後に UTC)
--repo <OWNER/NAME>このリポジトリだけ(大文字と小文字を区別しません)。繰り返し指定できます
--owner <LOGIN>このユーザーまたは organization が所有するリポジトリだけ。繰り返し指定できます
--visibility <public|private>公開リポジトリだけ、または公開でない(private と internal の)リポジトリだけ
--ownership <owned|external>自分が所有するリポジトリだけ、またはそれ以外のリポジトリだけ
--user <USER>ほかのユーザーの活動を分析します(自分のトークンで見える範囲に限られます)
--format <table|json|csv|markdown>出力形式(既定は table)。csv を使えるのはレポートと pr だけです。sync、doctor、auth、cache、tui に指定すると、終了コード 2 でエラーになります。markdown を使えるのは overview、daily、weekly、monthly、yearly、repos だけです(プロフィール READMEを参照)。JSON や CSV と同じく、--include-private を付けない限りプライベートリポジトリの名前を隠します
--offlineキャッシュのデータだけを使い、GitHub には接続しません
--no-cacheローカルのキャッシュではなく、一時的なキャッシュに最新のデータを取得します
--require-complete期間内に不完全なデータが1つでもあれば、終了コード 6 で終わります
--no-color色を付けません(NO_COLOR も参照します)
--include-privateJSON / CSV の出力に、private リポジトリの名前とタイトルを含めます
--public-only公開リポジトリだけを取得・表示します
--commit-date <committer|author>コミットがどの日に入るか、期間内かどうかを、どちらのコミット日付で決めるか(既定は committer)。ターミナル UI でも使います
--token-file <PATH>GitHub のトークンをこのファイルから読みます(ほかのユーザーが読めない権限にしておく必要があります)
--data-dir <PATH>キャッシュのデータベースを置くディレクトリ(既定: OS のユーザーデータディレクトリ、または GHUSAGE_DATA_DIR)
--concurrency <N>GitHub への同時リクエスト数の上限。1〜16(既定は 8)
--max-age <AGE>キャッシュの同期からこの時間が経っていなければ、レポートは同期をせず、その同期の時点のデータを表示します。30s、5m、1h、または常に最新を取得する 0(既定は 5m、または GHUSAGE_MAX_AGE)
-h, --helpヘルプを表示します
-V, --versionバージョンを表示します

フィルターは AND で組み合わさり、リポジトリは指定したフィルターすべてに一致する必要があります。--repo や --owner を繰り返したときは、その値どうしは OR で組み合わさります。「所有する」とは、リポジトリのオーナーが自分であるか、(自分を分析しているときに)自分がそのリポジトリの admin 権限を持っていることです。リポジトリを所有する organization のメンバーであるだけでは、所有するリポジトリにはなりません。

グローバルオプションはどのコマンドでも受け付けますが、すべてのコマンドが使うわけではありません。期間(--since、--until)を使うのは、レポート、sync、tui です。フィルター(--repo、--owner、--visibility、--ownership)と --commit-date を使うのは、レポートと tui だけです。コマンドが使わないオプションを指定すると、ghusage は warning: --repo has no effect on `sync` のような警告を stderr に出し、そのまま処理を続けます。

出力とターミナル ​

  • レポートは stdout に出力します。エラー、警告、補足のメッセージ、同期の進み具合は stderr に出力します。
  • 色を付けるのは、stdout がターミナルで、--no-color が指定されておらず、NO_COLOR が空でない値に設定されていないときだけです。パイプに渡した出力には、エスケープシーケンスは入りません。
  • 同期の進み具合は、stderr がターミナルのときだけ表示します。
  • GitHub から取得したテキスト(タイトル、ログイン名、名前)は、制御文字を取り除いてから表示します。
  • パイプが閉じられても(たとえば ghusage daily | head -3)、エラーとしては扱いません。
  • 表形式の出力は人が読むためのもので、バージョンによって変わることがあります。スクリプトでは --format json か --format csv を使ってください。JSON と CSV の出力を参照してください。

終了コード ​

コード意味
0成功
1一般的なエラー(例: オフラインモードでキャッシュにアカウントがない、プルリクエストがキャッシュにない、doctor のチェックに失敗した、ターミナルのエラー)
2引数が無効(不明なオプションや値、無効な日付やタイムゾーン、空の期間、無効なプルリクエストの URL、不明なイベントの種類、sync --offline、CSV 出力のないコマンドへの --format csv、Markdown 出力のないコマンドへの --format markdown)
3認証エラー(認証情報がない、トークンファイルが使えない、GitHub がトークンを拒否した)
4GitHub API のエラー(ネットワーク、レート制限、サーバーエラー)。sync で一部のデータを最後まで取得できなかったときも、このコードになります。レポートのコマンドは、GitHub に接続できなくてもアカウントがキャッシュにあれば失敗せず、警告を出してキャッシュのデータを表示します
5キャッシュのエラー(データベースを作成できない・開けない、データベースが壊れている・新しすぎる、別の同期が実行中)
6--require-complete を指定していて、データが不完全(レポートは出力されます)

--help と --version は終了コード 0 で終わります。

現在のバージョンでは、次のように表示されます。

text
$ ghusage --since 0d
error: invalid date or time: 0d (use YYYY-MM-DD, RFC 3339, today, yesterday, or Nd/Nw/Nm/Ny)
$ echo $?
2

$ ghusage --timezone Mars/Phobos
error: unknown time zone: Mars/Phobos

$ ghusage sync --offline
error: sync cannot run with --offline

$ ghusage --offline --no-cache
error: the argument '--offline' cannot be used with '--no-cache'

環境変数 ​

変数説明
GH_TOKENGitHub のトークン(優先順位は --token-file の次)
GITHUB_TOKENGitHub のトークン(GH_TOKEN が設定されていないときに使います)
GHUSAGE_DATA_DIRキャッシュを置くデータディレクトリ(--data-dir が優先します)
GHUSAGE_MAX_AGE--max-age の既定値
GHUSAGE_API_URLGitHub Enterprise Server 向けの REST API のベース URL(既定は https://api.github.com)。GraphQL のエンドポイントもこれに合わせて変わり、URL が /api/v3 で終わるときは https://HOST/api/graphql、それ以外は <GHUSAGE_API_URL>/graphql になります
GHUSAGE_GRAPHQL_URLGraphQL のエンドポイントの URL(GHUSAGE_API_URL から決まる URL より優先します)
GHUSAGE_LOGstderr に出す診断用ログのフィルター。tracing のフィルター構文で、debug や ghusage_github=debug のように書きます(既定は warn)
TZ--timezone を指定しないときの既定のタイムゾーン(Europe/Berlin のような IANA 名)
NO_COLOR空でない値を設定すると、色を付けません

GitHub Enterprise Server については、認証を参照してください。