Support getting last commit message using contents-ext API (#34904)

Fix #34870 Fix #34929 --------- Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>

Author: rickyma

modules/structs/repo_file.go

@@ -116,14 +116,17 @@ type ContentsExtResponse struct {
 
 // ContentsResponse contains information about a repo's entry's (dir, file, symlink, submodule) metadata and content
 type ContentsResponse struct {
-Name string `json:"name"`
-Path string `json:"path"`
-SHA string `json:"sha"`
-LastCommitSHA string `json:"last_commit_sha"`
+Name string `json:"name"`
+Path string `json:"path"`
+SHA string `json:"sha"`
+
+LastCommitSHA *string `json:"last_commit_sha,omitempty"`
 // swagger:strfmt date-time
-LastCommitterDate time.Time `json:"last_committer_date"`
+LastCommitterDate *time.Time `json:"last_committer_date,omitempty"`
 // swagger:strfmt date-time
-LastAuthorDate time.Time `json:"last_author_date"`
+LastAuthorDate *time.Time `json:"last_author_date,omitempty"`
+LastCommitMessage *string `json:"last_commit_message,omitempty"`
+
 // `type` will be `file`, `dir`, `symlink`, or `submodule`
 Type string `json:"type"`
 Size int64 `json:"size"`
@@ -141,8 +144,8 @@ type ContentsResponse struct {
 SubmoduleGitURL *string `json:"submodule_git_url"`
 Links *FileLinksResponse `json:"_links"`
 
-LfsOid *string `json:"lfs_oid"`
-LfsSize *int64 `json:"lfs_size"`
+LfsOid *string `json:"lfs_oid,omitempty"`
+LfsSize *int64 `json:"lfs_size,omitempty"`
 }
 
 // FileCommitResponse contains information generated from a Git commit for a repo's file.

routers/api/v1/repo/file.go

@@ -812,7 +812,8 @@ func GetContentsExt(ctx *context.APIContext) {
 // required: true
 // - name: filepath
 // in: path
-// description: path of the dir, file, symlink or submodule in the repo
+// description: path of the dir, file, symlink or submodule in the repo. Swagger requires path parameter to be "required",
+// you can leave it empty or pass a single dot (".") to get the root directory.
 // type: string
 // required: true
 // - name: ref
@@ -823,7 +824,8 @@ func GetContentsExt(ctx *context.APIContext) {
 // - name: includes
 // in: query
 // description: By default this API's response only contains file's metadata. Use comma-separated "includes" options to retrieve more fields.
-// Option "file_content" will try to retrieve the file content, option "lfs_metadata" will try to retrieve LFS metadata.
+// Option "file_content" will try to retrieve the file content, "lfs_metadata" will try to retrieve LFS metadata,
+// "commit_metadata" will try to retrieve commit metadata, and "commit_message" will try to retrieve commit message.
 // type: string
 // required: false
 // responses:
@@ -832,6 +834,9 @@ func GetContentsExt(ctx *context.APIContext) {
 // "404":
 // "$ref": "#/responses/notFound"
 
+if treePath := ctx.PathParam("*"); treePath == "." || treePath == "/" {
+ctx.SetPathParam("*", "") // workaround for swagger, it requires path parameter to be "required", but we need to list root directory
+}
 opts := files_service.GetContentsOrListOptions{TreePath: ctx.PathParam("*")}
 for includeOpt := range strings.SplitSeq(ctx.FormString("includes"), ",") {
 if includeOpt == "" {
@@ -842,6 +847,10 @@ func GetContentsExt(ctx *context.APIContext) {
 opts.IncludeSingleFileContent = true
 case "lfs_metadata":
 opts.IncludeLfsMetadata = true
+case "commit_metadata":
+opts.IncludeCommitMetadata = true
+case "commit_message":
+opts.IncludeCommitMessage = true
 default:
 ctx.APIError(http.StatusBadRequest, fmt.Sprintf("unknown include option %q", includeOpt))
 return
@@ -883,7 +892,11 @@ func GetContents(ctx *context.APIContext) {
 // "$ref": "#/responses/ContentsResponse"
 // "404":
 // "$ref": "#/responses/notFound"
-ret := getRepoContents(ctx, files_service.GetContentsOrListOptions{TreePath: ctx.PathParam("*"), IncludeSingleFileContent: true})
+ret := getRepoContents(ctx, files_service.GetContentsOrListOptions{
+TreePath: ctx.PathParam("*"),
+IncludeSingleFileContent: true,
+IncludeCommitMetadata: true,
+})
 if ctx.Written() {
 return
 }

services/repository/files/content.go

@@ -39,6 +39,8 @@ type GetContentsOrListOptions struct {
 TreePath string
 IncludeSingleFileContent bool // include the file's content when the tree path is a file
 IncludeLfsMetadata bool
+IncludeCommitMetadata bool
+IncludeCommitMessage bool
 }
 
 // GetContentsOrList gets the metadata of a file's contents (*ContentsResponse) if treePath not a tree
@@ -132,39 +134,46 @@ func getFileContentsByEntryInternal(_ context.Context, repo *repo_model.Reposito
 }
 selfURLString := selfURL.String()
 
-err = gitRepo.AddLastCommitCache(repo.GetCommitsCountCacheKey(refCommit.InputRef, refType != git.RefTypeCommit), repo.FullName(), refCommit.CommitID)
-if err != nil {
-return nil, err
-}
-
-lastCommit, err := refCommit.Commit.GetCommitByPath(opts.TreePath)
-if err != nil {
-return nil, err
-}
-
 // All content types have these fields in populated
 contentsResponse := &api.ContentsResponse{
-Name: entry.Name(),
-Path: opts.TreePath,
-SHA: entry.ID.String(),
-LastCommitSHA: lastCommit.ID.String(),
-Size: entry.Size(),
-URL: &selfURLString,
+Name: entry.Name(),
+Path: opts.TreePath,
+SHA: entry.ID.String(),
+Size: entry.Size(),
+URL: &selfURLString,
 Links: &api.FileLinksResponse{
 Self: &selfURLString,
 },
 }
 
-// GitHub doesn't have these fields in the response, but we could follow other similar APIs to name them
-// https://docs.github.com/en/rest/commits/commits?apiVersion=2022-11-28#list-commits
-if lastCommit.Committer != nil {
-contentsResponse.LastCommitterDate = lastCommit.Committer.When
-}
-if lastCommit.Author != nil {
-contentsResponse.LastAuthorDate = lastCommit.Author.When
+if opts.IncludeCommitMetadata || opts.IncludeCommitMessage {
+err = gitRepo.AddLastCommitCache(repo.GetCommitsCountCacheKey(refCommit.InputRef, refType != git.RefTypeCommit), repo.FullName(), refCommit.CommitID)
+if err != nil {
+return nil, err
+}
+
+lastCommit, err := refCommit.Commit.GetCommitByPath(opts.TreePath)
+if err != nil {
+return nil, err
+}
+
+if opts.IncludeCommitMetadata {
+contentsResponse.LastCommitSHA = util.ToPointer(lastCommit.ID.String())
+// GitHub doesn't have these fields in the response, but we could follow other similar APIs to name them
+// https://docs.github.com/en/rest/commits/commits?apiVersion=2022-11-28#list-commits
+if lastCommit.Committer != nil {
+contentsResponse.LastCommitterDate = util.ToPointer(lastCommit.Committer.When)
+}
+if lastCommit.Author != nil {
+contentsResponse.LastAuthorDate = util.ToPointer(lastCommit.Author.When)
+}
+}
+if opts.IncludeCommitMessage {
+contentsResponse.LastCommitMessage = util.ToPointer(lastCommit.Message())
+}
 }
 
-// Now populate the rest of the ContentsResponse based on entry type
+// Now populate the rest of the ContentsResponse based on the entry type
 if entry.IsRegular() || entry.IsExecutable() {
 contentsResponse.Type = string(ContentTypeRegular)
 // if it is listing the repo root dir, don't waste system resources on reading content

services/repository/files/content_test.go

@@ -5,56 +5,21 @@ package files
 
 import (
 "testing"
-"time"
 
 "code.gitea.io/gitea/models/unittest"
 api "code.gitea.io/gitea/modules/structs"
 "code.gitea.io/gitea/modules/util"
-"code.gitea.io/gitea/routers/api/v1/utils"
 "code.gitea.io/gitea/services/contexttest"
 
 _ "code.gitea.io/gitea/models/actions"
 
 "github.com/stretchr/testify/assert"
-"github.com/stretchr/testify/require"
 )
 
 func TestMain(m *testing.M) {
 unittest.MainTest(m)
 }
 
-func getExpectedReadmeContentsResponse() *api.ContentsResponse {
-treePath := "README.md"
-sha := "4b4851ad51df6a7d9f25c979345979eaeb5b349f"
-encoding := "base64"
-content := "IyByZXBvMQoKRGVzY3JpcHRpb24gZm9yIHJlcG8x"
-selfURL := "https://try.gitea.io/api/v1/repos/user2/repo1/contents/" + treePath + "?ref=master"
-htmlURL := "https://try.gitea.io/user2/repo1/src/branch/master/" + treePath
-gitURL := "https://try.gitea.io/api/v1/repos/user2/repo1/git/blobs/" + sha
-downloadURL := "https://try.gitea.io/user2/repo1/raw/branch/master/" + treePath
-return &api.ContentsResponse{
-Name: treePath,
-Path: treePath,
-SHA: "4b4851ad51df6a7d9f25c979345979eaeb5b349f",
-LastCommitSHA: "65f1bf27bc3bf70f64657658635e66094edbcb4d",
-LastCommitterDate: time.Date(2017, time.March, 19, 16, 47, 59, 0, time.FixedZone("", -14400)),
-LastAuthorDate: time.Date(2017, time.March, 19, 16, 47, 59, 0, time.FixedZone("", -14400)),
-Type: "file",
-Size: 30,
-Encoding: &encoding,
-Content: &content,
-URL: &selfURL,
-HTMLURL: &htmlURL,
-GitURL: &gitURL,
-DownloadURL: &downloadURL,
-Links: &api.FileLinksResponse{
-Self: &selfURL,
-GitURL: &gitURL,
-HTMLURL: &htmlURL,
-},
-}
-}
-
 func TestGetContents(t *testing.T) {
 unittest.PrepareTestEnv(t)
 ctx, _ := contexttest.MockContext(t, "user2/repo1")
@@ -63,45 +28,8 @@ func TestGetContents(t *testing.T) {
 contexttest.LoadRepoCommit(t, ctx)
 contexttest.LoadUser(t, ctx, 2)
 contexttest.LoadGitRepo(t, ctx)
-defer ctx.Repo.GitRepo.Close()
-repo, gitRepo := ctx.Repo.Repository, ctx.Repo.GitRepo
-refCommit, err := utils.ResolveRefCommit(ctx, ctx.Repo.Repository, ctx.Repo.Repository.DefaultBranch)
-require.NoError(t, err)
-
-t.Run("GetContentsOrList(README.md)-MetaOnly", func(t *testing.T) {
-expectedContentsResponse := getExpectedReadmeContentsResponse()
-expectedContentsResponse.Encoding = nil // because will be in a list, doesn't have encoding and content
-expectedContentsResponse.Content = nil
-extResp, err := GetContentsOrList(ctx, repo, gitRepo, refCommit, GetContentsOrListOptions{TreePath: "README.md", IncludeSingleFileContent: false})
-assert.Equal(t, expectedContentsResponse, extResp.FileContents)
-assert.NoError(t, err)
-})
-
-t.Run("GetContentsOrList(README.md)", func(t *testing.T) {
-expectedContentsResponse := getExpectedReadmeContentsResponse()
-extResp, err := GetContentsOrList(ctx, repo, gitRepo, refCommit, GetContentsOrListOptions{TreePath: "README.md", IncludeSingleFileContent: true})
-assert.Equal(t, expectedContentsResponse, extResp.FileContents)
-assert.NoError(t, err)
-})
-
-t.Run("GetContentsOrList(RootDir)", func(t *testing.T) {
-readmeContentsResponse := getExpectedReadmeContentsResponse()
-readmeContentsResponse.Encoding = nil // because will be in a list, doesn't have encoding and content
-readmeContentsResponse.Content = nil
-expectedContentsListResponse := []*api.ContentsResponse{readmeContentsResponse}
-// even if IncludeFileContent is true, it has no effect for directory listing
-extResp, err := GetContentsOrList(ctx, repo, gitRepo, refCommit, GetContentsOrListOptions{TreePath: "", IncludeSingleFileContent: true})
-assert.Equal(t, expectedContentsListResponse, extResp.DirContents)
-assert.NoError(t, err)
-})
 
-t.Run("GetContentsOrList(NoSuchTreePath)", func(t *testing.T) {
-extResp, err := GetContentsOrList(ctx, repo, gitRepo, refCommit, GetContentsOrListOptions{TreePath: "no-such/file.md"})
-assert.Error(t, err)
-assert.EqualError(t, err, "object does not exist [id: , rel_path: no-such]")
-assert.Nil(t, extResp.DirContents)
-assert.Nil(t, extResp.FileContents)
-})
+// GetContentsOrList's behavior is fully tested in integration tests, so we don't need to test it here.
 
 t.Run("GetBlobBySHA", func(t *testing.T) {
 sha := "65f1bf27bc3bf70f64657658635e66094edbcb4d"

services/repository/files/file.go

@@ -22,7 +22,12 @@ import (
 func GetContentsListFromTreePaths(ctx context.Context, repo *repo_model.Repository, gitRepo *git.Repository, refCommit *utils.RefCommit, treePaths []string) (files []*api.ContentsResponse) {
 var size int64
 for _, treePath := range treePaths {
-fileContents, _ := GetFileContents(ctx, repo, gitRepo, refCommit, GetContentsOrListOptions{TreePath: treePath, IncludeSingleFileContent: true}) // ok if fails, then will be nil
+// ok if fails, then will be nil
+fileContents, _ := GetFileContents(ctx, repo, gitRepo, refCommit, GetContentsOrListOptions{
+TreePath: treePath,
+IncludeSingleFileContent: true,
+IncludeCommitMetadata: true,
+})
 if fileContents != nil && fileContents.Content != nil && *fileContents.Content != "" {
 // if content isn't empty (e.g., due to the single blob being too large), add file size to response size
 size += int64(len(*fileContents.Content))

templates/swagger/v1_json.tmpl

@@ -19,6 +19,7 @@ import (
 "code.gitea.io/gitea/modules/gitrepo"
 "code.gitea.io/gitea/modules/setting"
 api "code.gitea.io/gitea/modules/structs"
+"code.gitea.io/gitea/modules/util"
 "code.gitea.io/gitea/services/context"
 
 "github.com/stretchr/testify/assert"
@@ -52,8 +53,8 @@ func getCreateFileOptions() api.CreateFileOptions {
 func normalizeFileContentResponseCommitTime(c *api.ContentsResponse) {
 // decoded JSON response may contain different timezone from the one parsed by git commit
 // so we need to normalize the time to UTC to make "assert.Equal" pass
-c.LastCommitterDate = c.LastCommitterDate.UTC()
-c.LastAuthorDate = c.LastAuthorDate.UTC()
+c.LastCommitterDate = util.ToPointer(c.LastCommitterDate.UTC())
+c.LastAuthorDate = util.ToPointer(c.LastAuthorDate.UTC())
 }
 
 type apiFileResponseInfo struct {
@@ -74,9 +75,9 @@ func getExpectedFileResponseForCreate(info apiFileResponseInfo) *api.FileRespons
 Name: path.Base(info.treePath),
 Path: info.treePath,
 SHA: sha,
-LastCommitSHA: info.lastCommitSHA,
-LastCommitterDate: info.lastCommitterWhen,
-LastAuthorDate: info.lastAuthorWhen,
+LastCommitSHA: util.ToPointer(info.lastCommitSHA),
+LastCommitterDate: util.ToPointer(info.lastCommitterWhen),
+LastAuthorDate: util.ToPointer(info.lastAuthorWhen),
 Size: 16,
 Type: "file",
 Encoding: &encoding,

tests/integration/api_repo_file_create_test.go

@@ -18,6 +18,7 @@ import (
 "code.gitea.io/gitea/modules/gitrepo"
 "code.gitea.io/gitea/modules/setting"
 api "code.gitea.io/gitea/modules/structs"
+"code.gitea.io/gitea/modules/util"
 "code.gitea.io/gitea/services/context"
 
 "github.com/stretchr/testify/assert"
@@ -60,9 +61,9 @@ func getExpectedFileResponseForUpdate(info apiFileResponseInfo) *api.FileRespons
 Name: path.Base(info.treePath),
 Path: info.treePath,
 SHA: sha,
-LastCommitSHA: info.lastCommitSHA,
-LastCommitterDate: info.lastCommitterWhen,
-LastAuthorDate: info.lastAuthorWhen,
+LastCommitSHA: util.ToPointer(info.lastCommitSHA),
+LastCommitterDate: util.ToPointer(info.lastCommitterWhen),
+LastAuthorDate: util.ToPointer(info.lastAuthorWhen),
 Type: "file",
 Size: 20,
 Encoding: &encoding,