本文へ移動

期間とタイムゾーン ​

期間は半開区間 ​

期間はすべて半開区間で、開始時刻を含み、終了時刻を含みません(start ≤ t < end)。そのため、隣り合う期間が重なることも、あいだに隙間ができることもありません。ちょうど午前0時に起きたイベントは、その午前0時から始まる日に入ります。

内部では、時刻はすべて UTC で扱います。日・週・月といった暦の境界は、選んだタイムゾーンで計算します。

--since と --until ​

sh
ghusage overview --since 2026-11-01 --until 2026-11-30
ghusage daily --since 14d
ghusage overview --since 2026-11-20T09:00:00+09:00 --until 2026-11-20T18:00:00+09:00

指定できる形式は次のとおりです。

形式--since(開始)に指定したとき--until(終了)に指定したとき
YYYY-MM-DDその日の始まりのローカル時刻の午前0時その日の終わりのローカル時刻の午前0時。その日がまるごと含まれます
today今日のローカル時刻の午前0時今日の終わり
yesterday昨日のローカル時刻の午前0時昨日の終わり(今日の午前0時)
RFC 3339 のタイムスタンプ(例: 2026-11-20T09:00:00Z、2026-11-20T09:00:00+09:00)その時刻その時刻(この時刻は含まない)
NdN−1 日前の日の始まり。今日を含む直近 N 日になります指定できません
NwN−1 週前の週が始まる月曜日。今週を含む直近 N 週になります指定できません
NmN−1 か月前の月の1日。今月を含む直近 N か月になります指定できません
NyN−1 年前の年の1月1日。今年を含む直近 N 暦年になります指定できません
  • N は正の整数でなければなりません(0d はエラーになります)。
  • --until を省略すると、期間は現在時刻で終わります。
  • --since を省略すると、コマンドごとの既定値を使います。ほとんどのレポートは 7d、weekly は 8w、monthly は 6m、yearly は 3y、sync と tui は 30d です。
  • 開始は終了より前でなければなりません。そうでないときは、終了コード 2 で失敗します(error: empty period: ...)。

選んだタイムゾーンで今日が 2026-11-21(土)だとすると、次のようになります。

オプション期間
--since 7d2026-11-15 00:00 → 現在
--since 2w2026-11-09(月)00:00 → 現在
--since 3m2026-09-01 00:00 → 現在
--since today2026-11-21 00:00 → 現在
--since yesterday --until yesterday2026-11-20 00:00 → 2026-11-21 00:00
--since 2026-11-01 --until 2026-11-302026-11-01 00:00 → 2026-12-01 00:00

各レポートのヘッダーには、解決した期間が表示されます。JSON では period.start / period.end に入ります。

タイムゾーン ​

タイムゾーンによって、日・週・月がどこから始まるか、イベントがどの日付に入るかが決まります。タイムゾーンは次の順に選ばれます。

  1. --timezone <IANA name>(例: --timezone Asia/Tokyo、--timezone UTC)
  2. 環境変数 TZ。有効な IANA 名が入っている場合に限ります(先頭の : は無視します)
  3. オペレーティングシステムのタイムゾーン設定
  4. UTC

--timezone に無効な値を指定すると、終了コード 2 で失敗します。TZ の値が無効なときは無視して、次の候補を使います。

同じイベントでも、タイムゾーンによって日付が変わることがあります。たとえば 2026-11-20 16:00 UTC のコミットは、UTC では 2026-11-20 ですが、Asia/Tokyo では 2026-11-21 になります。

週と月 ​

  • 週はローカル時刻の午前0時、月曜日から始まります。weekly では、週を ISO 週番号で 2026-W47 のように表示します(年によっては第53週があります)。
  • 月は1日のローカル時刻の午前0時から始まる暦月で、2026-11 のように表示します。
  • 最初と最後の区切りは、期間に合わせて切り詰めます。--since 2026-11-04 を指定すると、最初の週の区切りは月曜日ではなく 2026-11-04(水)から始まります。各区切りの正確な start と end は JSON に入っています。

夏時間 ​

1日は暦の上の日で、24時間ごとの区切りではありません。夏時間の切り替えがある日は、ローカルの1日が23時間か25時間になり(30分ずれるタイムゾーンでは30分の差になります)、その日の区切りもその長さになります。夏時間の切り替えでその日のローカル時刻の午前0時が存在しないときは、その日で最初に有効なローカル時刻から1日が始まります。切り替えの前後でも、イベントが抜け落ちたり二重に数えられたりすることはありません。

コミットの日付 ​

Git のコミットには、author date(変更を最初に書いた日時)と committer date(rebase や amend などで、コミットを最後に作り直した日時)の2つの日付があります。ghusage は既定では committer date を使います。--commit-date author を指定すると、コミットがどの期間・どの日に入るかを author date で決めます。どちらの日付も、push した日時ではありません。

GitHub のコミット検索は、committer date でコミットを探します。そのため --commit-date author を指定したとき、author date は期間内でも committer date がどの同期済みの範囲にも入らないコミットは、キャッシュになく、数えられません。

出力のタイムスタンプ ​

  • 表形式の出力では、時刻を選んだタイムゾーンで表示します(YYYY-MM-DD HH:MM)。
  • JSON の period.start / period.end は、選んだタイムゾーンの RFC 3339 形式です(例: 2026-11-02T00:00:00+09:00)。それ以外の JSON のタイムスタンプは、すべて UTC の RFC 3339 形式です(例: 2026-11-01T15:00:00Z)。
  • CSV のタイムスタンプは、オフセット +00:00 付きの UTC の RFC 3339 形式です。