Skip to content

Metric definitions ​

This page defines every number ghusage reports. Table output, JSON, CSV and the terminal UI are all computed by the same code, so the definitions apply to all of them. JSON field names are given in code.

Basic rules ​

Events ​

Everything ghusage counts is an event: a commit, a pull request being opened, a review being submitted, a comment, a label being added, a check run finishing, and so on. Each event has a stable identity, so the same event fetched twice or from two different GitHub APIs is counted once, and the order in which data was fetched never changes a result.

You ​

"You" is the account being analyzed: the authenticated user, or the account given with --user. An event is yours when its actor is that account. When both account IDs are known, only the IDs are compared, so a renamed or reused login cannot be mistaken for you.

  • Bots are accounts whose GitHub type is Bot or whose login ends in [bot]. Their activity is never yours; it is included in counts of what you received and of everyone's activity.
  • Unknown actors (for example deleted accounts) are never counted as you.

Which events count ​

An event counts toward a period when:

  1. its time is inside the period, which is half-open: start ≤ time < end (see Periods and time zones);
  2. its repository matches the filters (--repo, --owner, --visibility, --ownership, --public-only);
  3. it has not been observed to be removed (see edits and deletions);
  4. it is not a pending (draft, unsubmitted) review, and not a thread-reply-only review.

An event's time is when it happened on GitHub (created_at, submitted_at, the time of a timeline event). For commits it is the committer date by default; with --commit-date author it is the author date. Commit times are when the commit was made, not when it was pushed; GitHub does not provide push times.

Activity, not CI ​

Check runs and commit statuses (CI) are automation. They are never counted as anyone's activity: they are excluded from active days, active pull requests, pull request internal events, per-PR event counts, participants and timings. CI results are reported separately.

Period counts versus current state ​

Most numbers count events in the period. A few are snapshot values that describe the current state as of the last sync, regardless of the period: open pull requests, open issues you authored, and review thread resolution. They are labeled "(current)" or "(now)" in table output and live under snapshot in JSON.

Totals and breakdowns ​

daily, weekly, monthly and yearly split the period into calendar buckets that cover it exactly, without gaps or overlaps. Event counts in the buckets add up to the total of the period. Unique counts do not add up: a pull request reviewed on two days counts once on each of those days but once in the total. The unique counts are reviewed_prs, active_prs and active_prs_all_participants.

Summary metrics ​

These appear in overview (and in every JSON report under metrics, per bucket under activity_breakdown[].summary, and per repository under repositories[].summary).

Commits ​

Commits (commits): the number of distinct commits you authored in the period, identified by repository and SHA.

  • Sources: commits whose author is your account on the default branches of repositories you pushed to or contributed to (found by listing each repository's commits and by GitHub commit search), plus your commits found inside pull requests ghusage has synced. A commit found in several ways counts once. See how commits are found.
  • A commit is yours when GitHub links its author to your account (usually by the commit email). Commits with an author email that is not linked to your account are not attributed to you.
  • The same SHA in two repositories (for example a fork and its upstream) counts as two commits.
  • Commits that were later removed from a pull request by a force push still count: you made them.
  • Placed in time by committer date (default) or author date (--commit-date author).

Merge commits (merge_commits): how many of those commits have more than one parent. Shown as (N merge).

Lines added and deleted by these commits are described in Lines changed.

Pull requests ​

PRs created (prs_created): pull requests you opened in the period (counted at their creation time).

PRs merged (yours) (prs_merged): your pull requests that were merged in the period, by anyone, counted at the merge time. A pull request created before the period and merged in it counts; one created in the period and merged later does not.

Merges you performed (merges_performed): merges in the period where you were the one who merged, whoever authored the pull request. Merging your own pull request counts here and in "PRs merged (yours)".

Merged by unknown (merges_unknown_actor): how many of your merged pull requests have no known merger (GitHub did not report one). Shown in table output only when non-zero.

PRs closed without merge (prs_closed_without_merge): close events in the period on your pull requests that are known not to be part of a merge, by anyone. A close counts as part of a merge when the pull request is merged and the close happened within 60 seconds of the merge. A pull request that was closed, reopened and closed again counts twice.

PRs reopened (prs_reopened, JSON/TUI only): reopen events on your pull requests in the period, by anyone.

Open PRs (current) (snapshot.open_prs): your pull requests in the cache that are open as of their last sync. This is current state, not a count for the period. Repository filters apply.

Reviews ​

GitHub reviews have a state: approved, changes requested, or commented.

Reviews submitted (reviews_submitted): review submissions you made in the period, on anyone's pull request.

  • total: all counted submissions. Submitting three reviews on one pull request counts three.
  • approved, changes_requested, commented: by state.
  • dismissed_unknown_state: dismissed reviews whose original state could not be determined. When GitHub reports the state a review had before it was dismissed, the review counts under that state.
  • Pending (unsubmitted) reviews are never counted.

Reviewed PRs (reviewed_prs): the number of distinct pull requests on which you submitted at least one counted review in the period. This is a unique count. Shown as on N PRs.

Reviews received (reviews_received): review submissions by anyone other than you (people, bots and unknown actors) on your pull requests in the period, with the same breakdown by state.

From bots (reviews_received_from_bots): how many of the reviews received were submitted by bots.

Review dismissals performed (review_dismissals_performed, JSON only): reviews you dismissed in the period.

Thread-reply-only reviews ​

When you reply to an existing review thread, GitHub records the reply as a review with state "commented" and no body. Counting those would inflate review numbers, so a commented review is not counted as a review submission when it has no summary text and every inline comment in it is a reply to an existing thread. The replies themselves still count as inline comments. In ghusage pr --timeline such reviews are shown with the detail "thread reply only, not counted as a review".

Review summaries ​

The text body of a submitted review is a review summary. It counts as a comment (type review_summary), never as an additional review. A review with an empty or whitespace-only body has no summary.

Comments ​

There are three comment types:

TypeJSON keyWhat it is
ConversationconversationA comment in the pull request's conversation (not attached to code)
InlineinlineA review comment attached to code, in a review thread, including replies
Review summaryreview_summaryThe text body of a submitted review

Comments written (comments_written): comments you wrote in the period on any pull request, by type. The total (total in JSON) is the sum of the three types.

Comments received (comments_received): comments written by anyone other than you (including bots) on your pull requests in the period, by type.

Comments on issues are not collected; comment metrics cover pull requests only. Editing a comment is not counted as activity.

Review thread replies (review_responses): your inline replies in review threads on your own pull requests where the thread was started by someone else (a known account). These are your answers to review feedback. Additional commits pushed after a review are not counted here.

Pull request development ​

PR commits (pr_commits): distinct commits you authored that are currently part of a pull request, by commit time in the period. A commit that is part of two pull requests counts once for each. Commits removed from the pull request by a force push are excluded.

Force pushes (force_pushes): force pushes you made to a pull request's branch in the period, as recorded in the pull request timeline.

Coordination actions (coordination_actions, JSON only): review requests, removed review requests, assignments and unassignments you made.

Metadata actions (metadata_actions, JSON only): labels added or removed, milestones set or removed, and title changes you made.

Issues ​

Issues (issues_opened, issues_closed, issues_reopened): issues you opened, close events you performed, and reopen events you performed in the period. Closing the same issue twice counts twice.

Open issues you authored (current) (snapshot.open_issues_authored, shown by issues): issues you opened that are currently open.

Activity ​

Active PRs (active_prs): the number of distinct pull requests in which you had at least one event in the period (any type except CI: a commit, a review, a comment, a label, ...). Unique count.

With anyone's activity (active_prs_all_participants): the number of distinct synced pull requests in which anyone (you, others or bots) had at least one non-CI event in the period. Unique count. Only pull requests that were synced because they involve you are known to ghusage.

PR internal events (pr_internal_events): the number of your events inside pull requests in the period: pull request commits, lifecycle events (open, close, reopen, merge, draft changes), force pushes, counted reviews, dismissals, comments of all three types, coordination and metadata actions. CI is excluded. Commits found on default branches and issue events are not pull request events.

Active days (active_days): the number of distinct local calendar dates (in the report's time zone) on which you had at least one counted non-CI event: a commit, a pull request event or an issue event.

Last activity (last_activity, JSON/CSV): the time of your latest counted non-CI event in the period. For commits, the selected commit date (--commit-date) is used.

CI results ​

CI results (not counted as activity) (ci): check runs and commit statuses of the synced pull requests with a time in the period, by outcome, regardless of who triggered them:

FieldOutcomes
passedsuccess
failedfailure, timed out, startup failure, action required, error
pendingqueued, in progress, waiting, requested, pending
otherneutral, skipped, stale, cancelled, unknown

Every attempt is counted: a check that failed and was then re-run successfully counts once in failed and once in passed.

A sync reads the CI results of each pull request's head commit at that time. Results already stored for earlier head commits are kept when new commits are pushed, so a failure on an earlier head still counts; CI of a head commit that was never synced while it was the head is not available.

Review threads (current) ​

snapshot.threads counts the review threads of the pull requests that had anyone's non-CI activity in the period, by their current state: total, open (not resolved), resolved, and outdated (the code they refer to has changed; overlaps with open and resolved). When a thread was resolved is not known.

Lines changed ​

ghusage reports how many lines your commits added and deleted (diff_stats in JSON), and, separately, each pull request's current diff. Both come from the line counts GitHub reports. See how line counts are fetched for when they are known.

Read line counts with care

Line counts are easily dominated by generated files, formatting changes, dependency updates (lock files, vendored code) and moved or renamed files. A small careful fix and a large mechanical change can differ by orders of magnitude. Line counts are not a measure of how much or how well someone worked: do not turn them into scores or rankings, and do not use them to compare people. Look at lines added and lines deleted separately rather than adding them up.

Lines changed by your commits ​

Lines changed (your commits) (diff_stats): lines added and deleted by the commits counted in Commits, minus merge commits and the commits left out below.

  • The commits are the same as for commits: the same sources, the same period boundaries (by committer date, or author date with --commit-date author), the same filters and the same deduplication. A commit found both on a default branch and inside a pull request counts once.
  • Merge commits are left out. GitHub reports a merge commit's lines against its first parent, which repeats the changes of the branch that was merged. Those changes are already counted in the merged commits.
  • Unknown line counts are never treated as zero. The sums cover only the commits whose line counts are known, and coverage says how many that is.
  • Daily, weekly, monthly, yearly and per-repository values use the same definition, so they add up to the total of the period.
FieldMeaning
commitsNon-merge commits counted in commits
excludedOf those, commits left out because their changes are counted through other commits (see below)
commits_with_statsOf the remaining commits - excluded, commits with known line counts
additions, deletionsLines added and deleted, summed over the commits_with_stats commits only
coverageno_commits: nothing to count (no commits, or all left out); complete: every remaining commit has known line counts; partial: only some do, so the sums are lower bounds; unavailable: none does, so the sums are unknown (not zero)

The number of commits (commits) is not affected by any of this.

Commits counted through other commits ​

A commit's changes can reach the default branch as a different commit:

  • a pull request merged by squash creates one new commit containing the changes of all its commits;
  • a pull request merged by rebase creates new copies of its commits;
  • a commit removed from a pull request by a force push is usually replaced by a rewritten one.

Counting both the original commit and the commit that reached the default branch would count the same change twice. So a commit that appears in a synced pull request is left out of the line totals (excluded) unless at least one of its appearances is still part of the pull request and that pull request is

  • open, or closed without being merged, or
  • merged with a merge commit (a merge commit with two parents).

In other words, commits that exist only in pull requests merged by squash or rebase, or whose merge method is not known, and commits that a force push removed from the pull request, are left out. Commits that never appear in a synced pull request always count.

The merge method is taken from the number of parents of the pull request's merge commit, which a sync records together with the pull request. Pull requests that were synced before ghusage recorded the merge method have an unknown merge method, so their commits are left out. Run ghusage sync --full for the period to record it.

This rule is provisional and may be refined in a future version. See Known limitations for the cases it gets wrong.

Pull request changes ​

Changes (diff in prs and pr): a pull request's diff between its base and head as of the last sync: lines added (additions), lines deleted (deletions), changed files (changed_files) and when it was observed (observed_at).

  • It is a snapshot of the pull request, not changes made in the period. It changes with every push, force push and update of the base branch.
  • It is not added to the line totals of your commits: the two describe different things and would count the same changes twice.
  • It is null (shown as ? or "unknown") when it is not known, for example for a pull request synced by an older version.

Table labels ​

overview labelJSON field
Commitscommits (merge_commits)
PRs createdprs_created
PRs merged (yours)prs_merged
Merges you performedmerges_performed (merges_unknown_actor)
PRs closed without mergeprs_closed_without_merge
Open PRs (current)snapshot.open_prs
Reviews submittedreviews_submitted, reviewed_prs
Reviews receivedreviews_received, reviews_received_from_bots
Comments writtencomments_written
Comments receivedcomments_received
Review thread repliesreview_responses
PR commitspr_commits
Force pushesforce_pushes
Issuesissues_opened, issues_closed, issues_reopened
Active PRsactive_prs, active_prs_all_participants
PR internal eventspr_internal_events
CI results (not counted as activity)ci
Active daysactive_days
Lines changed (your commits)diff_stats

"Lines changed (your commits)" reads, depending on diff_stats.coverage: +A -D in N commits (complete); +A -D in K of N commits; the rest are unknown (run `ghusage sync --diff-stats`) (partial); or unknown for N commits (run `ghusage sync --diff-stats`) (unavailable). N is commits - excluded. When commits were left out, ; E commits left out as counted through other commits (squash or rebase merges, force pushes) is appended.

In daily / weekly / monthly / yearly, the columns are: Commits (commits), PRs (prs_created), Merged (prs_merged), Reviews (reviews_submitted.total), Received (reviews_received.total), Comments (comments written, all types), PR commits (pr_commits), Issues (issues_opened), Active PRs (active_prs), +Lines (diff_stats.additions) and -Lines (diff_stats.deletions).

In repos, the columns are: Commits, PRs (created), Merged (yours), Reviews (submitted), Comments (written), Issues (opened), Active PRs, PR events (pr_internal_events), +Lines, -Lines and Last activity, all for that repository.

In the +Lines and -Lines columns (table and Markdown output), ~N is a sum over only some of the commits (partial) and ? means that no commit has known line counts (unavailable). A note below the table explains the marks when they appear. Repositories are ordered by your activity there (commits + PR internal events + issue events), then by name.

Pull request list ​

ghusage prs lists pull requests with at least one non-CI event in the period: by default those where at least one event is yours; with --all-participants also those where only others were active. All columns count events in the period only.

ColumnJSON fieldDefinition
Statestate, is_draftCurrent state: open, draft, merged, closed (closed without merge)
AuthorauthorLogin of the pull request author
EventseventsCounted non-CI events by anyone (including bots)
Yoursevents_by_subjectThose of the events that are yours
CommitscommitsDistinct commits in the pull request (by anyone) with a commit time in the period
ReviewsreviewsCounted review submissions by anyone
CommentscommentsComments of all three types by anyone
PeopleparticipantsDistinct known accounts with at least one event
Discussiondiscussion_participantsDistinct known accounts that wrote a conversation, inline or review summary comment (labels, commits or review requests alone do not count)
ThreadsthreadsReview threads with an inline comment in the period
Last activitylast_activityTime of the latest of those events
CIlatest_ciCurrent combined CI state of the head commit (snapshot)
Changesdiff+A -D: the pull request's base-to-head diff as of the last sync (snapshot, not changes in the period; ? when not known). See Pull request changes

--details: activity per pull request ​

Descriptive statistics over the listed pull requests (same participation rule): events, reviews, comments, commits, participants, discussion participants, review threads and active days per pull request, where active days are the distinct local dates with a non-CI event in the period. For each, ghusage reports the median, mean, 90th percentile (nearest rank), maximum and the number of pull requests (n); JSON also includes the minimum.

--details: lifecycle timing (your pull requests) ​

Computed for your pull requests that had anyone's activity in the period, using everything known about each pull request (not only events in the period). Reported in hours in the table and in seconds in JSON.

TimingDefinition
Time to first reviewFrom creation to the first counted review submitted by someone other than the author (bots included)
Creation to mergeFrom creation to merge, for merged pull requests
Review to your next activityFrom that first review to the author's next observed event of any kind. This is not necessarily a response to the review; it is just the next thing the author did in that pull request
First to last activityFrom the first to the last observed non-CI event in the pull request

Not quality scores

Intensity and timing values are descriptive statistics about how activity is distributed. They are not measures of quality, skill or productivity, and should not be used to compare people.

Pull request detail ​

ghusage pr <URL> covers the whole life of one pull request, not a period.

FieldDefinition
State (current)open, open (draft), merged, closed
MergedMerge time and merger; "merger unknown" when GitHub did not report one
CommitsDistinct commits currently in the pull request. "N no longer in the PR" counts commits seen earlier that a force push removed
ReviewsCounted review submissions by anyone, by state
CommentsComments by anyone, by type
Review threadsCurrent state: total, open, resolved, outdated
Latest CICurrent combined CI state of the head commit
Changes (current snapshot)+A -D in F files (base to head as of <time>): the pull request's diff as of the last sync. See Pull request changes
ParticipantsKnown accounts with at least one counted non-CI event
Time to first review, Creation to mergeAs defined above

The timeline (--timeline, JSON, CSV) lists every stored event, including events that are not counted (pending reviews are never stored; removed items are marked "no longer present"; thread-reply-only reviews are marked). PR commits are labeled "Commit (committed)" because their time is the commit time, not the time they were added to the pull request.

Edits and deletions ​

  • Editing a comment or review is not counted as activity. Only the latest content is known; comments that were edited are marked edited.
  • When a sync completely refetches a pull request and finds that a comment, review, commit or timeline event that was seen before is gone, it is marked as removed with the time the removal was observed, and it is excluded from counts. When it was actually deleted is not known. Review threads that no longer exist are dropped from the thread counts.
  • Items deleted before ghusage first saw them are not known at all.