同期とローカルキャッシュ
ghusage は、API のレスポンスから直接レポートを計算することはありません。まず GitHub のデータをローカルの SQLite データベース(キャッシュ)に保存し、どの形式のレポートもターミナル UI も、すべてこのキャッシュから作ります。
同期で取得するデータ
同期では、指定した期間について 3 種類のデータを取得します。
| データの種類 | 探し方 | 保存するもの |
|---|---|---|
commits | 自分のアカウントが author のコミットを、コミッター日時で探します。GitHub のコミット検索に加えて、期間内に push されたリポジトリのうち自分が持つもの、および自分のコミットやプルリクエストがあるリポジトリのそれぞれについて、デフォルトブランチのコミット一覧を使います | コミット。同期したプルリクエストの中で見つかった自分のコミットも含みます |
pull_requests | Issue 検索で、自分が involves: に当たるか reviewed-by: に当たるプルリクエストのうち、期間内に更新されたもの | 各プルリクエストと、そのコミット(行数を含む)、レビュー、レビュースレッドとそのコメント、会話コメント、タイムラインのイベント、head コミットの CI 結果のすべて。プルリクエストの現在の差分とマージ方法も含む |
issues | Issue 検索で、自分が involves: に当たる Issue のうち、期間内に更新されたもの | 各 Issue と、その open / close / reopen の履歴 |
プルリクエストと Issue は 1 件ずつ別のトランザクションで書き込みます。そのため、同期が途中で止まってもそれまでに書き込んだものは残り、次の実行では足りない分から続けます。
コミットの探し方
GitHub のコミット検索のインデックスは、インデックス済みのリポジトリであっても、何の知らせもなくコミットを取りこぼすことがあります。そこで ghusage は、コミットを直接一覧する方法も併用します。
- 足りない範囲の開始時点以降に push された自分のリポジトリを一覧します(
GET /user/repos。push が新しい順に取得し、範囲より古いリポジトリが出たところで止めます)。--userを指定した場合は、そのユーザー自身のリポジトリしか見えません(GET /users/{login}/repos)。 - コミット検索で自分のコミットが見つかったリポジトリと、同期で見つかったプルリクエストのリポジトリを加えます。
- これらのリポジトリ(フォークは除きます。
--public-onlyではプライベートリポジトリも除きます)のそれぞれについて、範囲内のデフォルトブランチ上の自分のコミットを一覧します(GET /repos/{owner}/{repo}/commits?author=...)。
検索でも一覧でもプルリクエストの中でも見つかったコミットは、1 件として保存します。リポジトリごとに少なくとも 1 回はリクエストするので、活動したリポジトリが多いほど API リクエストの数も増えます。コミットのカバレッジが complete になるのは、コミット検索とすべての一覧の取得が成功したときだけです。コミット検索だけに頼っていた以前のバージョンが記録したコミットのカバレッジは再利用しません。次の同期でその範囲を取得し直します。
行数の取得
変更行数には、自分の各コミットで追加・削除した行数が必要です。
- プルリクエストの中のコミットの行数と、プルリクエストの差分は、毎回の同期でプルリクエストのクエリに含めて取得します。追加のリクエストはかかりません。
- それ以外のコミット(デフォルトブランチだけで見つかったもの)の行数には、
ghusage sync --diff-statsが必要です。通常の同期のあと、期間内(コミッター日時か作成者の日時で判断)の自分のマージでないコミットのうち、行数がまだキャッシュにないものを探し、GraphQL で 1 クエリあたり 100 コミットずつ、複数のクエリを並列に(最大--concurrency件まで)取得します。ほかのコミットとして数えられるコミットは合計に入らないので、取得しません。--public-onlyのときは、公開されていないリポジトリのコミットも取得しません。 - キャッシュにある行数は再利用し、取り直しません。そのため、
--diff-statsをもう一度実行しても、まだ足りない分だけを取得します。目安として、約 1,100 コミットで約 12 リクエストでした。 - GitHub が返さなかったコミット(リポジトリにアクセスできなくなった場合など)は、不明のままです(出力の
unavailable)。次に--diff-statsを実行したときに、もう一度取得を試みます。
$ ghusage sync --since 1y --diff-stats
...
status: complete
line counts: 1084 commits (already known 212, fetched 872, unavailable 0)分からない行数を 0 と表示することはありません。レポートには、合計が何件のコミットを対象にしているかを示します。行数、差分、マージ方法を記録しない古いバージョンで同期したプルリクエストは、取得し直したときにそれらが入ります。変更のないプルリクエストは通常の同期では取得を省くので、その期間について ghusage sync --full を実行してください。
同期の実行
ghusage sync # last 30 days
ghusage sync --since 2026-01-01 # from a date until now
ghusage sync --since 90d --full # refetch everything in the periodSynced octocat for 2026-10-23 00:00 → 2026-11-21 19:30
commits found: 690
pull requests found: 83 (fetched 83, unchanged 0)
issues found: 19 (fetched 19, unchanged 0)
API requests: 279 (retries 0, 40812 ms)
status: completestderr がターミナルのときは、進み具合を stderr に表示します(進み具合の表示を参照)。--format json を指定すると、同期の結果を JSON で出力します(JSON 出力を参照)。
sync の終了コードは次のとおりです。
0: すべてを完全に取得できた。4: 同期は終わったが、一部のデータを完全には取得できなかった(取得に失敗した、または一部しか取得できなかったプルリクエストや Issue がある、コミットを一覧できなかったリポジトリがある、検索の上限に達した)。何が足りないかはincomplete:の行に表示します。6:--require-completeを指定した場合は、4の代わりにこのコードになる。3: 認証に失敗した。5: キャッシュのエラー(別の同期が実行中の場合を含む)。
レポートのコマンドでの自動同期
レポートのコマンド(overview、daily、prs など)は、まず指定した期間のカバレッジを確認します。どれかの種類のデータに抜けがあれば、足りない範囲を同期してからレポートを表示します。その同期が認証以外の理由で失敗した場合は、警告を表示してキャッシュにある内容を表示します。
warning: sync failed, showing cached data: ...同期した直後のデータ
指定した期間を少し前に同期し終えていて、足りないのが直近の数分だけなら、レポートのコマンドは同期し直しません。最後に同期した時点のデータを表示し、そのことを stderr に示します。
note: showing data synced 2 min ago (up to 2026-11-21 23:41); use --max-age 0 to fetch the latestこの場合、期間はその同期の時点で終わります。データがどれだけ古くてもよいかは --max-age(既定は 5m。環境変数 GHUSAGE_MAX_AGE でも指定できます)で決めます。--max-age 0 を指定すると、常に最新のデータを取得します。
進み具合の表示
同期の実行中に stderr がターミナルなら、ghusage はスピナーとともに、並列に動いているリクエストの数(上限は --concurrency)、終わったリクエストの数、プルリクエスト、コミット、Issue の状況を表示します。その下に、実行中のリクエストを経過時間つきで(最大 4 件、残りは件数だけ)、さらに直前の処理(取得し終えたリポジトリやプルリクエスト)を表示します。同期が終わるとすべて消すので、レポートの出力には残りません。
⠹ Syncing with GitHub 0:04 · 6/8 in parallel · 31 requests done · pull requests 1/2 · commits 9/22
▸ search commits p4 0.8s
▸ octo/app#16 2.3s
▸ octo/app commits p2 0.4s
▸ octo/tool commits 0.3s
… 2 more
↳ commits in octo/site: 12 foundGitHub に接続できない場合
--offline を指定しない場合、レポートのコマンドはまず API で自分のアカウントを確認します。この時点で GitHub に接続できない場合(ネットワークのエラー、タイムアウト、再試行しても HTTP 5xx が返る場合)は、警告を表示し、--offline を指定したときと同じように処理を続けます。アカウントには、最後にオンラインで実行したときのアカウント(または --user)を使います。
warning: GitHub is not reachable (network error: could not connect to GitHub); showing cached dataレポートはキャッシュにある内容を表示し、どの範囲が足りないかはカバレッジで分かります。キャッシュだけで続けるには、キャッシュにアカウントが記録されている必要があります。キャッシュが空で --user も指定していない場合、コマンドは終了コード 4 で失敗します。GitHub がトークンを拒否した場合(HTTP 401)は、切り替えずに終了コード 3 で失敗します。
ghusage sync は GitHub が必要なので、このような切り替えはできず、終了コード 4 で終了します。ghusage pr は、GitHub に接続できないときは警告を出して、キャッシュにあるプルリクエストを表示します。そのプルリクエストが一度もキャッシュされていなければ失敗します。
期間全体がすでにカバーされている場合、レポートのコマンドは活動データを何も取得しません。すでにカバーされている期間の変更(たとえば、その後にマージされたプルリクエスト)を取り込むには、その期間について ghusage sync か ghusage sync --full を実行してください。
差分同期
キャッシュは、アカウントとデータの種類ごとに、どの時間範囲をどこまで完全に取得したかを記録しています。これがキャッシュのカバレッジです。
- 通常の同期では、まだ
completeになっていない範囲だけを取得します。GitHub のインデックスへの登録が遅れたものも拾えるように、足りない範囲はそれぞれ 3 日さかのぼって広げます。 - 前回完全に取得してから
updated_atが変わっていないプルリクエストは取得しません(同期の出力ではunchangedとして数えます)。 - open のままで 7 日間更新を取得していないプルリクエストは、検索で更新されたと報告されなくても取得し直します。
--fullを指定すると、既存のカバレッジを無視し、変更のないプルリクエストも含めて期間全体を取得し直します。
検索の期間の扱い
GitHub の検索修飾子 updated: は、プルリクエストや Issue の現在の更新日時に対して一致を判定します。先月活動があり、今日また更新されたプルリクエストは、先月を対象にした検索では見つかりません。これを補うため、ghusage は足りない範囲の開始時点から現在までを対象にプルリクエストと Issue を検索し、そのうえで各イベントを実際に起きた日時で数えます。
GitHub は、1 回の検索クエリにつき最大 1000 件の結果しか返しません。それより多い場合、ghusage は時間範囲を半分ずつに分けて、どの部分も上限に収まるようにします。1 秒の範囲でも 1000 件を超える場合は、最初の 1000 件しか取得できず、その範囲は partial になります。
カバレッジ
どのレポートも、指定した期間のカバレッジをデータの種類ごとに表示します。
| 状態 | 意味 |
|---|---|
complete | 範囲全体について、対象のデータをすべて取得した。 |
partial | 何かが足りない。検索が上限に達した、GitHub が不完全な結果を返した、あるリポジトリのコミットを一覧できなかった、プルリクエストや Issue の取得に失敗したか一部しか取得できなかった、など。理由もあわせて表示します。 |
not_yet_synced | このアカウントについて、その範囲を一度も同期していない。 |
not_available | そのデータは取得できない。 |
unknown | 状態を判定できなかった。 |
レポート全体の状態が complete になるのは、期間内のどの時点についても、すべての種類のデータが complete のときだけです。同じ範囲を何度か同期した場合は、最後の同期の結果でその範囲の状態が決まります。
「complete」は、常に明示された対象範囲についての完全さを表します。たとえばコミットの場合、対象範囲は「自分が push したか貢献したリポジトリ(リポジトリの一覧とコミット検索で探したもの)のデフォルトブランチ上で、自分が author のコミットと、同期したプルリクエストのコミット」です。この対象範囲の説明は JSON 出力に含まれます。対象範囲の外にあるものについては既知の制約を参照してください。
--require-complete
--require-complete を指定すると、全体のカバレッジが complete でないレポートは、レポートを表示したあとで終了コード 6 で終了します。
error: data for the requested period is not_yet_synced (--require-complete)ghusage pr では、そのプルリクエストのカバレッジを使います。
--offline
--offline はキャッシュだけを使い、GitHub には一切接続しません(認証情報も不要です)。sync や --no-cache とは組み合わせられません。
- 一度も同期していない範囲は
not_yet_syncedと表示します。表形式の出力では、stderr に次の注意書きを出します。note: offline mode; some of the period has not been synced - オフラインモードでは、「自分」が誰なのかを知る必要があります。最後にオンラインで実行したときのアカウントか、
--userを使います。キャッシュが空で--userも指定していない場合は、次のエラーで失敗します。error: no cached data for the authenticated user; runghusage synconline first or pass --user ghusage pr --offlineは、すでにキャッシュにあるプルリクエストにしか使えません。
--no-cache
--no-cache を指定すると、指定した期間のデータを一時的なインメモリのデータベースに取得し、コマンドの終了とともに破棄します。ローカルのキャッシュは読みも書きもしません。レポートの計算方法はまったく同じです。何も再利用しないので、実行するたびに期間全体を取得し直します。
データディレクトリ
キャッシュは、データディレクトリにある ghusage.db という 1 つの SQLite ファイルです。データディレクトリは次の順に決まります。
--data-dir <PATH>- 環境変数
GHUSAGE_DATA_DIR(空でない場合) - OS のユーザーデータディレクトリ
| OS | 既定のデータディレクトリ |
|---|---|
| macOS | ~/Library/Application Support/dev.ghusage.ghusage |
| Linux | $XDG_DATA_HOME/ghusage または ~/.local/share/ghusage |
| Windows | %APPDATA%\ghusage\ghusage\data |
ディレクトリがなければ作成します。データベースを開いている間、SQLite はその隣に -wal と -shm のファイルも置きます。
ghusage cache status # location, size, counts, last sync, 30-day coverage
ghusage cache status --format json
ghusage cache clear # delete all cached GitHub datacache clear は、キャッシュしたデータ(プルリクエスト、イベント、カバレッジ、同期の履歴)をすべて削除しますが、データベースのファイルとそのスキーマは残します。認証情報はキャッシュに保存していないので、影響を受けません。
新しいバージョンでデータベースのスキーマが変わった場合、ghusage はキャッシュを自動で移行し、その隣にバックアップ(ghusage.db.bak-v<old version>)を残します。自分より新しいバージョンが作ったキャッシュは、変更せずに使用を拒否します。壊れたデータベースは破損として報告します(終了コード 5)。最初からやり直すには、そのファイルを移動するか削除してください。
同期のロック
1 つのデータディレクトリで同時に実行できる同期は 1 つだけです。同期はデータディレクトリにある sync.lock に排他ロックをかけます。2 つ目の同期は、すぐに終了コード 5 で失敗します。
error: another ghusage sync is already running (lock: /path/to/sync.lock)別の同期の実行中に同期が必要になったレポートのコマンドは、警告を表示し、代わりにキャッシュにあるデータを表示します。キャッシュの読み取りにはロックが要らないので、同期の実行中もレポートとターミナル UI は使えます。
複数のアカウント
カバレッジ、プルリクエスト、Issue、イベントは、どのアカウントのために取得したか(自分のアカウントか、--user で分析したユーザーか)と結びつけて保存します。そのため、ほかのユーザーを同期しても、自分の期間が同期済みになることはありません。両方のアカウントが関わっているプルリクエストは、アカウントの間で共有します。
ghusage pr <URL> で表示したプルリクエストは、もう一度表示できるように(--offline でも)キャッシュします。自分が関わっていないプルリクエスト(author ではない、自分の活動がない、レビュアーに指定されていない、assignee になっていない)は別に保存し、自分のレポートや活動に含めることはありません。
ネットワークの動作
- 並行して実行するリクエストは最大
--concurrency件です(既定は 8、最大は 16)。 - 各リクエストは 30 秒でタイムアウトします。タイムアウト、ネットワークのエラー、HTTP 500/502/503/504 の場合は、指数バックオフで合計 5 回まで試行します。
- プライマリのレート制限を使い切った場合、リセットまで 15 分以内なら
ghusageはリセットを待ちます。それより長ければ、レート制限のエラーで止まります。セカンダリのレート制限とRetry-Afterにも従います。 GHUSAGE_LOG=debug(またはghusage_github=debugのような任意のtracingのフィルター)を設定すると、診断用のログを stderr に出力します。