既知の制約
ghusage が出せるのは、GitHub の API で自分のトークンから見える範囲の情報だけです。データが欠けていたり不確かだったりする場合は、推測で埋めず、その欠け(カバレッジ)を示すか、値を不明のままにします。このページでは、数値を頼りにする前に知っておくべき制約をまとめます。
コミット
- コミットはデフォルトブランチから探します。 コミットは 2 つの方法で見つけ、両方で見つかったコミットも 1 回だけ数えます。1 つは GitHub のコミット検索です。もう 1 つはデフォルトブランチのコミット一覧で、対象は、リポジトリ一覧のうち期間内にプッシュがあったリポジトリ、検索で自分のコミットが見つかったリポジトリ、同期したプルリクエストのリポジトリです。コミット検索だけでは足りません。検索のインデックスは、インデックス対象のリポジトリにプッシュしてから何週間たっても、何も知らせずにコミットを取りこぼすことがあるため、
ghusageは検索だけには頼りません。 - ほかのブランチにしかないコミットは数えません。 ただし、
ghusageが同期した(自分が関わっている)プルリクエストに含まれるコミットは数えます。プルリクエストを作っていないフィーチャーブランチでの作業や、マージせずに削除したブランチでの作業は、コミットの集計の対象外です。 - 見つけられるリポジトリは、分析する相手によって変わります。 認証したユーザー本人を分析する場合、リポジトリ一覧には、自分が所有するリポジトリ、コラボレーターとして参加しているリポジトリ、組織のメンバーとしてアクセスできるリポジトリが入ります。
--userを指定した場合は、その相手が所有する公開リポジトリしか一覧にできません。それ以外のリポジトリにあるコミットは、コミット検索とプルリクエストからしか見つかりません。--public-onlyを指定した場合は、プライベートリポジトリと内部(internal)リポジトリを一覧に入れません。 - フォークは一覧に入れません。 フォークのデフォルトブランチは、たいていフォーク元のリポジトリと同じコミットを持っているので、フォークは飛ばします(コミット検索でも飛ばします)。フォークにある自分のコミットは、同期したプルリクエストに含まれる場合だけ数えます。
- 読めないリポジトリ。 リポジトリのコミット一覧の取得を拒否された場合(組織の SSO による HTTP 403 や、アクセスを外された後の 404 など)は、コミットのカバレッジが
partialになり、そのリポジトリの名前を示します。そのリポジトリには、アクセスできなくなったという印を付けます。空のリポジトリは、カバレッジに影響させずに飛ばします。 - コミットは自分のアカウントに結び付いている必要があります。 GitHub がコミットの作成者を自分のアカウントに結び付けている場合に、そのコミットを自分のものとします。通常はコミットのメールアドレスで結び付けます。自分のアカウントに登録していないメールアドレスで作ったコミットは数えません。
- コミットの時刻はコミットの日時で、プッシュした時刻ではありません。 GitHub は、コミットがいつプッシュされたかを記録していません。
ghusageはコミッター日時(--commit-date authorを指定した場合は作成者の日時)を使います。先週作って今日プッシュしたコミットは、先週の分として数えます。リベースや amend をしたコミットには、新しいコミッター日時が付きます。 - 作成者の日時のモードで見えるのは、コミッター日時で同期した範囲だけです。 コミット検索とコミット一覧は、コミッター日時で問い合わせます。そのため
--commit-date authorを指定しても、コミッター日時が同期済みの範囲の外にあるコミットはキャッシュにありません。 - フォースプッシュされた履歴。 フォースプッシュでプルリクエストからコミットが外れた場合、
ghusageがフォースプッシュより前にそのコミットを観測していれば、外れたコミットを残して「no longer in the PR」の印を付けます。最初の同期より前にプッシュされ、フォースプッシュで消えたコミットは復元できません。このようにして外れた自分のコミットは、「Commits」には引き続き入りますが、「PR commits」には入らなくなります。
行数
定義は変更行数を参照してください。
ほかのコミットとして数えられるコミットのルールは暫定です。 同期したプルリクエストだけをもとに判断するので、次のような場合には正しく扱えません。
- デフォルトブランチに直接プッシュしたコミットが、squash や rebase でマージされたプルリクエストにも含まれている場合。そのコミット自体がデフォルトブランチに届いていても、除外されます。
- デフォルトブランチ以外のブランチにマージされたプルリクエスト。その変更がデフォルトブランチに届いたかどうかにかかわらず、ほかのマージ済みプルリクエストと同じように扱います。
ghusageがマージ方法を記録するようになる前に同期したプルリクエスト。マージ方法が分からないので、そのコミットは除外されます。その期間についてghusage sync --fullを実行すると記録し直せます。
このルールは、今後のバージョンで見直すことがあります。
GitHub の値をそのまま使います。 コミットの行数は GitHub が返す値です。マージコミットの値は first parent との差分なので、マージコミットは合計から除いています。生成されたファイルや名前を変えたファイルなども、GitHub の数え方のとおりに数えます。
プルリクエストの外のコミットの行数は、指定したときだけ取得します(
ghusage sync --diff-stats)。それまでは合計がpartialかunavailableになり、0 にはなりません。プルリクエストの変更行数はスナップショットです。 プルリクエストの差分は最後の同期で見たもので、プッシュ、フォースプッシュ、base ブランチの更新で変わります。その履歴は残しません。
検索
updated:は現在の更新時刻で絞り込みます。 GitHub の Issue とプルリクエストの検索は、項目が最後に更新された時刻で絞り込みます。3 月に活動があり、5 月にもう一度更新されたプルリクエストは、3 月を対象にした検索に引っかかりません。ghusageはこれを補うため、取得できていない範囲の始まりから現在までを検索します。こうするとそのプルリクエストが見つかり、3 月のイベントは 3 月に数えられます。その代わり、古い期間ほど検索が大きくなります。- 結果は 1000 件までです。 GitHub は、1 つの検索クエリに対して最大 1000 件しか結果を返しません。
ghusageは、どの部分も 1000 件以下になるまで時間の範囲を分割します。1 秒の範囲でも 1000 件を超える場合は 1000 件しか取得できず、カバレッジは理由付きでpartialになります。 - 不完全な検索結果。 検索がタイムアウトして不完全な結果を返したと GitHub が報告した場合、カバレッジは
partialになります。 - 見つけられるかどうかは、自分が関わっているかで決まります。 プルリクエストは、自分が「関わっている」(作成者、担当者、メンション先、コメントした人)場合か、自分がレビューした場合に見つかります。Issue は、自分が関わっている場合に見つかります。GitHub の検索が自分と結び付けないプルリクエストでの活動は見つかりません。
- 検索インデックスへの反映の遅れ。 ごく最近の活動は、まだ GitHub の検索インデックスに入っていないことがあります。インデックスへの反映が遅れた項目を拾うため、差分同期は毎回、取得できていない範囲の 3 日前から始めます。それでも漏れた分は、次の同期で取得します。
最初の同期より前の履歴
ghusage は取得したものを保存し、そこから履歴を組み立てます。API が保持していないものは、後から取り戻せません。
ghusageが最初に取得する前に削除された項目- 編集されたコメントの元の内容(取得できるのは最新の内容だけ)
- 最初の同期より前にフォースプッシュで消えたコミット
- プッシュの時刻(いつでも取得できない)
編集と削除
- 編集は活動として数えず、編集の履歴も取得できません。分かるのは、最新の内容と、コメントが編集されたかどうかだけです。
- 削除されたコメント、レビュー、コミットに気づけるのは、
ghusageがプルリクエストを完全に取得し直したときだけです。気づいた時点で削除済みの印を付け、件数から除きます。削除された時刻は分からず、記録するのは削除を観測した時刻だけです。 - すでに完全にカバーしている期間は自動では取得し直さないので、その期間の削除や状態の変化に気づくのは、プルリクエストを取得し直したときだけです(たとえば、前回の同期以降に更新されたプルリクエストを取得し直す
ghusage syncや、ghusage sync --fullを実行したとき)。
プルリクエスト
- レビュースレッドの解決の履歴は取得できません。 分かるのは各レビュースレッドの現在の状態(解決済みか、outdated か、誰が解決したか)だけで、いつ解決されたかは分かりません。そのため、スレッドの件数は現在の状態を表します。
- CI の結果はヘッドコミットの分だけです。 チェック実行とコミットステータスは、各プルリクエストの現在のヘッドコミットについて取得します。プルリクエストのそれより前のコミットの結果は取得しません。ただし、そのコミットがヘッドだったときに以前の同期で保存した結果は残します。
- レビューの下にあるコメント。 インラインコメントは、レビュースレッドから(全ページ分)読みます。各レビューの下に並ぶコメントは、欠けを埋めるための補助の取得元としてだけ使います(レビューごとに先頭の 20 件)。
- マージとクローズ。 プルリクエストを誰がマージしたかを GitHub が報告しないことがあります。その場合は不明と表示し、誰の活動にもしません。マージから 60 秒以内のクローズは、マージに伴うものとして扱います。
- 下書きのレビュー(保留中で未提出のもの)は
ghusageから見えず、数えることもありません。 - レビューとして記録されるスレッドへの返信。 GitHub は、レビュースレッドへの返信を 1 件ずつ、本文のない「commented」のレビューとして記録します。これらはレビューの提出として数えません(指標の定義を参照)。
- Issue のコメントは収集しません。 コメントの指標の対象はプルリクエストです。Issue の指標の対象は、作成、クローズ、再オープンです。
- 非常に大きなプルリクエスト(タイムラインの項目、コミット、コメントが数千件あるもの)については、体系的な計測をしていません。完全に取得できない集まりがあると、そのプルリクエストは
partialになります。
アカウントとアクセス
- すべての情報は、トークンから見える範囲に限られます。アクセス権のないプライベートリポジトリ、SAML での認可が必要な組織、Fine-grained トークンで許可していないリポジトリは見えません。
- 同期中に GitHub から拒否されたリポジトリ(アクセスを外された後などの HTTP 403 や 404)は、キャッシュ済みのデータを残したまま
(no access)と表示します。影響を受けた範囲のカバレッジはpartialになります。 --userを指定した場合、ほかのユーザーの活動は、自分のトークンから見えるリポジトリの分に限られます。ほかのユーザーについての所有区分は、リポジトリの所有者だけで判断します。
レート制限とネットワーク
- GitHub の REST、検索、GraphQL のレート制限がかかります。認証済みユーザーの検索は 1 分あたり 30 リクエストまでなので、長い期間を対象にした最初の同期は、規模が大きいと時間がかかります。
- プライマリレート制限を使い切った場合、リセットまで 15 分以内なら
ghusageはリセットを待ちます。15 分より先なら、同期は API エラー(終了コード 4)で止まります。それまでに取得したものはすべて残り、次の実行で続きから取得します。 - セカンダリレート制限には、最大 60 秒待って対応します。
Retry-Afterが秒数で示されている場合は、それに従います。 - プライマリレート制限を使い切ったときに待つ動作は、検索の制限を実際に使い切って、本物の API で確かめています。セカンダリレート制限と、リセットが 15 分より先の場合は、GitHub の応答を模した自動テストでだけ確かめています。
- GitHub に接続できない場合、レポートのコマンドは警告を出したうえでキャッシュ済みのデータを使いますが、新しいデータは取得しません。
ghusage syncには、つながるネットワークが必要です。
プラットフォーム
ghusageは macOS(Apple Silicon)で開発しており、そこで実際の GitHub のデータに対して使っています。- 継続的インテグレーションでは、Linux(x86_64 と ARM64)、macOS(ARM64 と Intel)、Windows(x86_64)でビルドし、テストスイートを実行しています。npm のバイナリは、Windows ARM64 を含め、これらの各プラットフォームでビルドし、スモークテスト(npm でインストールして実行)をしています。Windows ARM64 では、テストスイート全体は実行していません。
- Windows(x86_64)は、実機の上で手作業で確認しています。対象は、サインイン、同期の進捗表示、表、ターミナル UI(タブ、詳細画面、リサイズ、全角文字、終了時の端末の復元)、リンクを開く動作です。同期を 2 つ同時に動かしたとき(同期のロック)の動作は、Windows では手作業で確認していません。
- Linux は、実機の上での手作業による確認をしていません。継続的インテグレーションでの確認だけで、そこには疑似端末でターミナル UI を動かすスモークテストも含みます。
--token-fileのファイル権限の確認は、Unix 系のシステムでだけ行います。- GitHub Enterprise Server(
GHUSAGE_API_URL)は試していません。ghusage prとターミナル UI でリンクを開く機能は、github.comの URL だけを受け付けます。
ターミナル UI
tで時間の範囲を変えても、新しい範囲はそれだけでは同期されません。rを押してください。- キャッシュが非常に大きい場合、期間やフィルターを変えた直後の最初の表示はバックグラウンドで計算するので、目に見えて時間がかかることがあります。
- 幅の狭いターミナルでは、Repositories タブはリポジトリ名を読めるように、重要度の低い列(PR events、Active PRs、Issues、-Lines、+Lines、Merged、Reviews、Visibility の順)を隠します。それでも非常に長い名前は短くなることがあります。完全な名前を見るには、ターミナルの幅を広げるか、Enter でリポジトリの詳細を開いてください。
- macOS と Linux では、
SIGTERMとSIGHUPを受けると、qと同じようにターミナル UI を終了し、ターミナルを元に戻します。SIGKILL(kill -9)で強制終了した場合は元に戻せないので、resetを実行してください。
キャッシュのファイル
- 新しく作るデータディレクトリは、自分だけが読める権限(
0700)で作り、データベースは0600で作ります。既存のディレクトリは権限をそのまま保ちます。共有のマシンでは、ls -ldで権限を確かめ、必要ならchmod 700で絞ってください。