`CommitStats` in the `Commit` struct is always nil

[acouvreur]

The CommitStats in the Commit struct is always nil.

Comparing the current Commit struct:

go-github/github/git_commits.go

Lines 44 to 62 in c4a49db

	// Commit represents a GitHub commit.
	type Commit struct {
	SHA *string `json:"sha,omitempty"`
	Author *CommitAuthor `json:"author,omitempty"`
	Committer *CommitAuthor `json:"committer,omitempty"`
	Message *string `json:"message,omitempty"`
	Tree *Tree `json:"tree,omitempty"`
	Parents []*Commit `json:"parents,omitempty"`
	Stats *CommitStats `json:"stats,omitempty"`
	HTMLURL *string `json:"html_url,omitempty"`
	URL *string `json:"url,omitempty"`
	Verification *SignatureVerification `json:"verification,omitempty"`
	NodeID *string `json:"node_id,omitempty"`
	// CommentCount is the number of GitHub comments on the commit. This
	// is only populated for requests that fetch GitHub data like
	// Pulls.ListCommits, Repositories.ListCommits, etc.
	CommentCount *int `json:"comment_count,omitempty"`
	}

With the GitHub OpenAPI Spec:

The Stats field is not on the OpenAPI Contract.

---

I know that structs can be used to represents objects that look alike a lot (hence the CommentCount field).

So I'm not sure if the Stats field is also one of these exceptions. If that's the case, it should be explained just like CommentCount.

[gmlewis]

I'm not sure I would call this issue a "bug".

According to GitHub, that line was added in 2013 in this commit:
1eaf383#diff-58a05e976d34ffef86ba94037754253cc9c33d354c78296018a375577ead4b19R21
entitled "implement repos_commits API".

So apparently it was once used by GitHub. As to its current usage, that would definitely require some investigation.
I'm happy to leave this issue open in case anyone would like to perform some investigation into this field's usage
and add a comment as to how and when it is used.

[acouvreur]

I'm not sure I would call this issue a "bug".

According to GitHub, that line was added in 2013 in this commit: 1eaf383#diff-58a05e976d34ffef86ba94037754253cc9c33d354c78296018a375577ead4b19R21 entitled "implement repos_commits API".

So apparently it was once used by GitHub. As to its current usage, that would definitely require some investigation. I'm happy to leave this issue open in case anyone would like to perform some investigation into this field's usage and add a comment as to how and when it is used.

Thanks for the quick answer @gmlewis. I will investigate as it wrongly put me into assuming I could check a created commit stats from the response.

I do think that it is not populated at all in any case. If that's the case I can submit a PR removing that field, otherwise a PR explaining where it is used.

[gmlewis]

I do think that it is not populated at all in any case. If that's the case I can submit a PR removing that field, otherwise a PR explaining where it is used.

Excellent. Thanks, @acouvreur . Sounds good. It's yours.

[acouvreur]

Commit struct analysis to look for the Stats field usage through the codebase:

Usage in struct `CheckSuite`: ✅ No usage

The Commit struct is used in CheckSuite.HeadCommit:

go-github/github/checks.go

Lines 71 to 92 in c4a49db

	type CheckSuite struct {
	ID *int64 `json:"id,omitempty"`
	NodeID *string `json:"node_id,omitempty"`
	HeadBranch *string `json:"head_branch,omitempty"`
	HeadSHA *string `json:"head_sha,omitempty"`
	URL *string `json:"url,omitempty"`
	BeforeSHA *string `json:"before,omitempty"`
	AfterSHA *string `json:"after,omitempty"`
	Status *string `json:"status,omitempty"`
	Conclusion *string `json:"conclusion,omitempty"`
	CreatedAt *Timestamp `json:"created_at,omitempty"`
	UpdatedAt *Timestamp `json:"updated_at,omitempty"`
	App *App `json:"app,omitempty"`
	Repository *Repository `json:"repository,omitempty"`
	PullRequests []*PullRequest `json:"pull_requests,omitempty"`
	// The following fields are only populated by Webhook events.
	HeadCommit *Commit `json:"head_commit,omitempty"`
	LatestCheckRunsCount *int64 `json:"latest_check_runs_count,omitempty"`
	Rerequstable *bool `json:"rerequestable,omitempty"`
	RunsRerequstable *bool `json:"runs_rerequestable,omitempty"`
	}

As mentionned, the HeadCommit field is only populated by Webhook events, so let's check CheckSuite Webhooks events:

This is the same for completed, requested and rerequested.
Conclusion: no usage of Stats in CheckSuite.HeadCommit

Usage in struct `MergeGroup`: ✅ No usage

The Commit struct is used in MergeGroup.HeadCommit:

go-github/github/event_types.go

Lines 842 to 854 in c4a49db

	// MergeGroup represents the merge group in a merge queue.
	type MergeGroup struct {
	// The SHA of the merge group.
	HeadSHA *string `json:"head_sha,omitempty"`
	// The full ref of the merge group.
	HeadRef *string `json:"head_ref,omitempty"`
	// The SHA of the merge group's parent commit.
	BaseSHA *string `json:"base_sha,omitempty"`
	// The full ref of the branch the merge group will be merged into.
	BaseRef *string `json:"base_ref,omitempty"`
	// An expanded representation of the head_sha commit.
	HeadCommit *Commit `json:"head_commit,omitempty"`
	}

The MergeGroup structure is only used through the MergeGroupEvent struct, so let's check MergeGroup Webhooks events:

This is the same for checks_requested and destroyed.
Conclusion: no usage of Stats in MergeGroup.HeadCommit

Usage in struct `Commit`: ✅ No usage

The Commit struct is used in Commit.Parents:

go-github/github/git_commits.go

Lines 44 to 62 in c4a49db

	// Commit represents a GitHub commit.
	type Commit struct {
	SHA *string `json:"sha,omitempty"`
	Author *CommitAuthor `json:"author,omitempty"`
	Committer *CommitAuthor `json:"committer,omitempty"`
	Message *string `json:"message,omitempty"`
	Tree *Tree `json:"tree,omitempty"`
	Parents []*Commit `json:"parents,omitempty"`
	Stats *CommitStats `json:"stats,omitempty"`
	HTMLURL *string `json:"html_url,omitempty"`
	URL *string `json:"url,omitempty"`
	Verification *SignatureVerification `json:"verification,omitempty"`
	NodeID *string `json:"node_id,omitempty"`
	// CommentCount is the number of GitHub comments on the commit. This
	// is only populated for requests that fetch GitHub data like
	// Pulls.ListCommits, Repositories.ListCommits, etc.
	CommentCount *int `json:"comment_count,omitempty"`
	}

Parents in Commit look like this (from the OpenAPI Contract):

This could be refined to be a CommitRef instead of Commit though.

Conclusion: no usage of Stats in Commit.Parents

Usage in struct `Timeline`: ✅ No usage

The Timeline struct is used in Timeline.Parents:

go-github/github/issues_timeline.go

Lines 18 to 38 in c4a49db

	type Timeline struct {
	ID *int64 `json:"id,omitempty"`
	URL *string `json:"url,omitempty"`
	CommitURL *string `json:"commit_url,omitempty"`
	// The User object that generated the event.
	Actor *User `json:"actor,omitempty"`
	// The person who commented on the issue.
	User *User `json:"user,omitempty"`
	// The person who authored the commit.
	Author *CommitAuthor `json:"author,omitempty"`
	// The person who committed the commit on behalf of the author.
	Committer *CommitAuthor `json:"committer,omitempty"`
	// The SHA of the commit in the pull request.
	SHA *string `json:"sha,omitempty"`
	// The commit message.
	Message *string `json:"message,omitempty"`
	// A list of parent commits.
	Parents []*Commit `json:"parents,omitempty"`

This is only used in a single Timeline event, which is committed: https://docs.github.com/en/rest/using-the-rest-api/issue-event-types?apiVersion=2022-11-28#properties-for-committed

Parents in the Timeline Committed event look like this (from the OpenAPI Contract):

This could be refined to be a CommitRef instead of Commit though, just like the one in Parents.

Conclusion: no usage of Stats in Timeline.Parents

Usage in struct `RepositoryTag`: ✅ No usage

The RepositoryTag struct is used in RepositoryTag.Commit:
https://github.com/google/go-github/blob/master/github/repos.go#L967-L973

This is only used in listing the tags in a repository: https://docs.github.com/en/rest/repos/repos#list-repository-tags

Commit look like this (from the OpenAPI Contract):

This could be refined to be a CommitRef instead of Commit again to avoid confusion.

Conclusion: no usage of Stats in RepositoryTag.Commit

Usage in struct `BranchCommit`: ✅ No usage

The BranchCommit struct is used in BranchCommit.Commit:
https://github.com/google/go-github/blob/master/github/repos_commits.go#L118-L123

This is only used in listing branches for HEAD commit: https://docs.github.com/en/rest/commits/commits#list-branches-for-head-commit

Commit look like this (from the OpenAPI Contract):

This could be refined to be a CommitRef instead of Commit again to avoid confusion.

Conclusion: no usage of Stats in BranchCommit.Commit

Usage in struct `RepositoryCommit`: ✅ No usage

The RepositoryCommit struct is used in RepositoryCommit.Commit and RepositoryCommit.Parents:

go-github/github/repos_commits.go

Lines 16 to 34 in c4a49db

	// RepositoryCommit represents a commit in a repo.
	// Note that it's wrapping a Commit, so author/committer information is in two places,
	// but contain different details about them: in RepositoryCommit "github details", in Commit - "git details".
	type RepositoryCommit struct {
	NodeID *string `json:"node_id,omitempty"`
	SHA *string `json:"sha,omitempty"`
	Commit *Commit `json:"commit,omitempty"`
	Author *User `json:"author,omitempty"`
	Committer *User `json:"committer,omitempty"`
	Parents []*Commit `json:"parents,omitempty"`
	HTMLURL *string `json:"html_url,omitempty"`
	URL *string `json:"url,omitempty"`
	CommentsURL *string `json:"comments_url,omitempty"`
	// Details about how many changes were made in this commit. Only filled in during GetCommit!
	Stats *CommitStats `json:"stats,omitempty"`
	// Details about which files, and how this commit touched. Only filled in during GetCommit!
	Files []*CommitFile `json:"files,omitempty"`
	}

RepositoryCommit is used in a lot of different places:

Usage in struct `StatusEvent`: ✅ No usage

The `StatusEvent` struct is not used directly by any function or struct.

And the event schema is defined as:



Conclusion: no usage of Stats in StatusEvent.Commit, StatusEvent.Parents and StatusEvent.Branches.Commit

Usage in function `RepositoriesService.ListBranches`: ✅ No usage

The `RepositoriesService.ListBranches` function returns a `Branch` which contains a `RepositoryCommit`.

The OpenAPI Schema defines the following:

This could be refined to be a CommitRef instead of Commit again to avoid confusion.

Conclusion: no usage of Stats in Branch.Commit.Commit when called through RepositoriesService.ListBranches

Usage in function `RepositoriesService.GetBranch`: ✅ No usage

The `RepositoriesService.GetBranch` function returns a `Branch` which contains a `RepositoryCommit`.

The OpenAPI Schema defines the following:

Conclusion: no usage of Stats in Branch.Commit.Commit when called through RepositoriesService.GetBranch

Usage in function `RepositoriesService.RenameBranch`: ✅ No usage

The `RepositoriesService.RenameBranch` function returns a `Branch` which contains a `RepositoryCommit`.

The OpenAPI Schema defines the following:

Conclusion: no usage of Stats in Branch.Commit.Commit when called through RepositoriesService.RenameBranch

Usage in function `RepositoriesService.CompareCommits`: ✅ No usage

The RepositoriesService.CompareCommits function returns a CommitsComparison which contains two RepositoryCommit (BaseCommit and MergeBaseCommit fields).

The OpenAPI Schema defines the following:

Conclusion: no usage of Stats in CommitComparaison.BaseCommit.Commit and CommitComparaison.MergeBaseCommit.Commit when called through RepositoriesService.CompareCommits

Usage in function `PullRequestsService.ListCommits`: ✅ No usage

The PullRequestsService.ListCommits function returns a CommitsComparison which contains two RepositoryCommit (BaseCommit and MergeBaseCommit fields).

The OpenAPI Schema defines the following:

Conclusion: no usage of Stats in CommitComparaison.BaseCommit.Commit and CommitComparaison.MergeBaseCommit.Commit when called through RepositoriesService.CompareCommits

I have a few more structs to go through, but overall it looks like Stats inside Commit is never actually used in any circumstances.

EDIT: I have checked all the structs. and usage and basically Stats is never used or I have missed something.

It is never available through operations done by the GitService. Then Stats is avaible through wrapper for operations such as Repository Commit etc.

Does that make sense to deprecate or even remove the field at all ?

[gmlewis]

Does that make sense to deprecate or even remove the field at all ?

With this detailed analysis, I'm totally fine with you creating a PR to remove the field.

Thank you for doing this deep dive, @acouvreur !