Add UpdateBranch API (#35368).

This is CreateBranch for branches that already exist making it possible
to reset branch to an arbitrary commit.

Consistent with CreateFile/UpdateFile new branches are created by POST
and existing branches updated by PUT.

Author: hramrach

assets/go-licenses.json

@@ -77,6 +77,7 @@ require (
 	github.com/huandu/xstrings v1.5.0
 	github.com/jaytaylor/html2text v0.0.0-20230321000545-74c2419ad056
 	github.com/jhillyerd/enmime v1.3.0
+	github.com/jinzhu/copier v0.4.0
 	github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51
 	github.com/klauspost/compress v1.18.0
 	github.com/klauspost/cpuid/v2 v2.3.0

go.mod

@@ -510,6 +510,8 @@ github.com/jcmturner/rpc/v2 v2.0.3 h1:7FXXj8Ti1IaVFpSAziCZWNzbNuZmnvw/i6CqLNdWfZ
 github.com/jcmturner/rpc/v2 v2.0.3/go.mod h1:VUJYCIDm3PVOEHw8sgt091/20OJjskO/YJki3ELg/Hc=
 github.com/jhillyerd/enmime v1.3.0 h1:LV5kzfLidiOr8qRGIpYYmUZCnhrPbcFAnAFUnWn99rw=
 github.com/jhillyerd/enmime v1.3.0/go.mod h1:6c6jg5HdRRV2FtvVL69LjiX1M8oE0xDX9VEhV3oy4gs=
+github.com/jinzhu/copier v0.4.0 h1:w3ciUoD19shMCRargcpm0cm91ytaBhDvuRpz1ODO/U8=
+github.com/jinzhu/copier v0.4.0/go.mod h1:DfbEm0FYsaqBcKcFuvmOZb218JkPGtvSHsKg8S8hyyg=
 github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
 github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=

go.sum

@@ -61,6 +61,27 @@ func (err ErrBranchAlreadyExists) Unwrap() error {
 	return util.ErrAlreadyExist
 }
 
+// ErrBranchShaMismatch represents an error that branch points to different SHA.
+type ErrBranchShaMismatch struct {
+	BranchName string
+	Expected   string
+	Actual     string
+}
+
+// IsErrBranchShaMismatch checks if an error is an ErrBranchShaMismatch.
+func IsErrBranchShaMismatch(err error) bool {
+	_, ok := err.(ErrBranchShaMismatch)
+	return ok
+}
+
+func (err ErrBranchShaMismatch) Error() string {
+	return fmt.Sprintf("branch already references %s, expected %s [name: %s]", err.Actual, err.Expected, err.BranchName)
+}
+
+func (err ErrBranchShaMismatch) Unwrap() error {
+	return util.ErrUnprocessableContent
+}
+
 // ErrBranchNameConflict represents an error that branch name conflicts with other branch.
 type ErrBranchNameConflict struct {
 	BranchName string

models/git/branch.go

@@ -282,6 +282,30 @@ type CreateBranchRepoOption struct {
 	OldRefName string `json:"old_ref_name" binding:"GitRefName;MaxSize(100)"`
 }
 
+// UpdateBranchRepoOption options when updating a branch in a repository
+// swagger:model
+type UpdateBranchRepoOption struct {
+	// Name of the branch to create
+	//
+	// required: true
+	// unique: true
+	BranchName string `json:"new_branch_name" binding:"Required;GitRefName;MaxSize(100)"`
+
+	// the commit ID (SHA) for the branch that already exists to update
+	SHA string `json:"sha" binding:"Required"`
+
+	// Deprecated: true
+	// Name of the old branch to create from
+	//
+	// unique: true
+	OldBranchName string `json:"old_branch_name" binding:"GitRefName;MaxSize(100)"`
+
+	// Name of the old branch/tag/commit to create from
+	//
+	// unique: true
+	OldRefName string `json:"old_ref_name" binding:"GitRefName;MaxSize(100)"`
+}
+
 // RenameBranchRepoOption options when renaming a branch in a repository
 // swagger:model
 type RenameBranchRepoOption struct {

modules/structs/repo.go

@@ -1242,6 +1242,7 @@ func Routes() *web.Router {
 					m.Get("/*", repo.GetBranch)
 					m.Delete("/*", reqToken(), reqRepoWriter(unit.TypeCode), mustNotBeArchived, repo.DeleteBranch)
 					m.Post("", reqToken(), reqRepoWriter(unit.TypeCode), mustNotBeArchived, bind(api.CreateBranchRepoOption{}), repo.CreateBranch)
+					m.Put("", reqToken(), reqRepoWriter(unit.TypeCode), mustNotBeArchived, bind(api.UpdateBranchRepoOption{}), repo.UpdateBranch)
 					m.Patch("/*", reqToken(), reqRepoWriter(unit.TypeCode), mustNotBeArchived, bind(api.RenameBranchRepoOption{}), repo.RenameBranch)
 				}, context.ReferencesGitRepo(), reqRepoReader(unit.TypeCode))
 				m.Group("/branch_protections", func() {

routers/api/v1/api.go

@@ -26,6 +26,8 @@ import (
 	pull_service "code.gitea.io/gitea/services/pull"
 	release_service "code.gitea.io/gitea/services/release"
 	repo_service "code.gitea.io/gitea/services/repository"
+
+	"github.com/jinzhu/copier"
 )
 
 // GetBranch get a branch of a repository
@@ -213,8 +215,69 @@ func CreateBranch(ctx *context.APIContext) {
 		return
 	}
 
-	opt := web.GetForm(ctx).(*api.CreateBranchRepoOption)
+	optCreate := web.GetForm(ctx).(*api.CreateBranchRepoOption)
+	opt := api.UpdateBranchRepoOption{}
+	err := copier.Copy(&opt, optCreate)
+	if err != nil {
+		ctx.APIError(http.StatusInternalServerError, "Error processing request.")
+		return
+	}
+
+	CreateUpdateRepoBranch(ctx, &opt)
+}
+
+// UpdateBranch update (reset) a branch in a user's repository
+func UpdateBranch(ctx *context.APIContext) {
+	// swagger:operation PUT /repos/{owner}/{repo}/branches repository repoUpdateBranch
+	// ---
+	// summary: Update a branch
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/UpdateBranchRepoOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Branch"
+	//   "403":
+	//     description: The branch is archived or a mirror.
+	//   "404":
+	//     description: The branch does not exist.
+	//   "409":
+	//     description: The branch SHA does not match.
+	//   "423":
+	//     "$ref": "#/responses/repoArchivedError"
+
+	if ctx.Repo.Repository.IsEmpty {
+		ctx.APIError(http.StatusNotFound, "Git Repository is empty.")
+		return
+	}
+
+	if ctx.Repo.Repository.IsMirror {
+		ctx.APIError(http.StatusForbidden, "Git Repository is a mirror.")
+		return
+	}
+
+	opt := web.GetForm(ctx).(*api.UpdateBranchRepoOption)
+
+	CreateUpdateRepoBranch(ctx, opt)
+}
 
+func CreateUpdateRepoBranch(ctx *context.APIContext, opt *api.UpdateBranchRepoOption) {
 	var oldCommit *git.Commit
 	var err error
 
@@ -243,14 +306,16 @@ func CreateBranch(ctx *context.APIContext) {
 		}
 	}
 
-	err = repo_service.CreateNewBranchFromCommit(ctx, ctx.Doer, ctx.Repo.Repository, oldCommit.ID.String(), opt.BranchName)
+	err = repo_service.CreateUpdateBranchFromCommit(ctx, ctx.Doer, ctx.Repo.Repository, oldCommit.ID.String(), opt.BranchName, opt.SHA)
 	if err != nil {
 		if git_model.IsErrBranchNotExist(err) {
 			ctx.APIError(http.StatusNotFound, "The old branch does not exist")
 		} else if release_service.IsErrTagAlreadyExists(err) {
 			ctx.APIError(http.StatusConflict, "The branch with the same tag already exists.")
-		} else if git_model.IsErrBranchAlreadyExists(err) || git.IsErrPushOutOfDate(err) {
+		} else if git_model.IsErrBranchAlreadyExists(err) {
 			ctx.APIError(http.StatusConflict, "The branch already exists.")
+		} else if git_model.IsErrBranchShaMismatch(err) || git.IsErrPushOutOfDate(err) {
+			ctx.APIError(http.StatusConflict, "The branch SHA does not match.")
 		} else if git_model.IsErrBranchNameConflict(err) {
 			ctx.APIError(http.StatusConflict, "The branch with the same name already exists.")
 		} else {

routers/api/v1/repo/branch.go

@@ -148,6 +148,9 @@ type swaggerParameterBodies struct {
 	// in:body
 	CreateBranchRepoOption api.CreateBranchRepoOption
 
+	// in:body
+	UpdateBranchRepoOption api.UpdateBranchRepoOption
+
 	// in:body
 	CreateBranchProtectionOption api.CreateBranchProtectionOption
 

routers/api/v1/swagger/options.go

@@ -194,9 +194,9 @@ func CreateBranch(ctx *context.Context) {
 		}
 		err = release_service.CreateNewTag(ctx, ctx.Doer, ctx.Repo.Repository, target, form.NewBranchName, "")
 	} else if ctx.Repo.RefFullName.IsBranch() {
-		err = repo_service.CreateNewBranch(ctx, ctx.Doer, ctx.Repo.Repository, ctx.Repo.BranchName, form.NewBranchName)
+		err = repo_service.CreateUpdateBranch(ctx, ctx.Doer, ctx.Repo.Repository, ctx.Repo.BranchName, form.NewBranchName, "")
 	} else {
-		err = repo_service.CreateNewBranchFromCommit(ctx, ctx.Doer, ctx.Repo.Repository, ctx.Repo.CommitID, form.NewBranchName)
+		err = repo_service.CreateUpdateBranchFromCommit(ctx, ctx.Doer, ctx.Repo.Repository, ctx.Repo.CommitID, form.NewBranchName, "")
 	}
 	if err != nil {
 		if release_service.IsErrProtectedTagName(err) {

routers/web/repo/branch.go

@@ -37,14 +37,14 @@ import (
 	"xorm.io/builder"
 )
 
-// CreateNewBranch creates a new repository branch
-func CreateNewBranch(ctx context.Context, doer *user_model.User, repo *repo_model.Repository, oldBranchName, branchName string) (err error) {
+// CreateUpdateBranch creates a new repository branch
+func CreateUpdateBranch(ctx context.Context, doer *user_model.User, repo *repo_model.Repository, oldBranchName, branchName, sha string) (err error) {
 	branch, err := git_model.GetBranch(ctx, repo.ID, oldBranchName)
 	if err != nil {
 		return err
 	}
 
-	return CreateNewBranchFromCommit(ctx, doer, repo, branch.CommitID, branchName)
+	return CreateUpdateBranchFromCommit(ctx, doer, repo, branch.CommitID, branchName, sha)
 }
 
 // Branch contains the branch information
@@ -255,6 +255,22 @@ func loadOneBranch(ctx context.Context, repo *repo_model.Repository, dbBranch *g
 	}, nil
 }
 
+func checkBranchSha(ctx context.Context, repo *repo_model.Repository, name, sha string) error {
+	branch, err := git_model.GetBranch(ctx, repo.ID, name)
+	if err != nil {
+		return err
+	}
+
+	if branch.CommitID != sha {
+		return git_model.ErrBranchShaMismatch{
+			BranchName: name,
+			Expected:   sha,
+			Actual:     branch.CommitID,
+		}
+	}
+	return nil
+}
+
 // checkBranchName validates branch name with existing repository branches
 func checkBranchName(ctx context.Context, repo *repo_model.Repository, name string) error {
 	_, err := gitrepo.WalkReferences(ctx, repo, func(_, refName string) error {
@@ -373,20 +389,27 @@ func SyncBranchesToDB(ctx context.Context, repoID, pusherID int64, branchNames,
 	})
 }
 
-// CreateNewBranchFromCommit creates a new repository branch
-func CreateNewBranchFromCommit(ctx context.Context, doer *user_model.User, repo *repo_model.Repository, commitID, branchName string) (err error) {
+// CreateUpdateBranchFromCommit creates a new repository branch
+func CreateUpdateBranchFromCommit(ctx context.Context, doer *user_model.User, repo *repo_model.Repository, commitID, branchName, sha string) (err error) {
 	err = repo.MustNotBeArchived()
 	if err != nil {
 		return err
 	}
 
-	// Check if branch name can be used
-	if err := checkBranchName(ctx, repo, branchName); err != nil {
-		return err
+	if sha != "" {
+		if err := checkBranchSha(ctx, repo, branchName, sha); err != nil {
+			return err
+		}
+	} else {
+		// Check if branch name can be used
+		if err := checkBranchName(ctx, repo, branchName); err != nil {
+			return err
+		}
 	}
 
 	if err := git.Push(ctx, repo.RepoPath(), git.PushOptions{
 		Remote: repo.RepoPath(),
+		Force:  sha != "",
 		Branch: fmt.Sprintf("%s:%s%s", commitID, git.BranchPrefix, branchName),
 		Env:    repo_module.PushingEnvironment(doer, repo),
 	}); err != nil {