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

@@ -292,6 +292,30 @@ type RenameBranchRepoOption struct {
 	Name string `json:"name" binding:"Required;GitRefName;MaxSize(100)"`
 }
 
+// UpdateBranchRepoOption options when updating a branch reference in a repository
+// swagger:model
+type UpdateBranchRepoOption struct {
+	// Name of the branch to update
+	//
+	// 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 reset to
+	//
+	// unique: true
+	OldBranchName string `json:"old_branch_name" binding:"GitRefName;MaxSize(100)"`
+
+	// Name of the old branch/tag/commit to reset to
+	//
+	// unique: true
+	OldRefName string `json:"old_ref_name" binding:"GitRefName;MaxSize(100)"`
+}
+
 // TransferRepoOption options when transfer a repository's ownership
 // swagger:model
 type TransferRepoOption 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

@@ -6,6 +6,7 @@ package repo
 
 import (
 	"errors"
+	"fmt"
 	"net/http"
 
 	"code.gitea.io/gitea/models/db"
@@ -26,6 +27,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 +216,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, fmt.Sprintf("Error processing request %s.", err))
+		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 +307,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.IsErrPushOutOfDate(err) || git.IsErrPushRejected(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 or updates a 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
@@ -373,23 +373,36 @@ 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 or updates a 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 != "" {
+		_, err := git_model.GetBranch(ctx, repo.ID, branchName)
+		if 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{
+	pushOpts := git.PushOptions{
 		Remote: repo.RepoPath(),
 		Branch: fmt.Sprintf("%s:%s%s", commitID, git.BranchPrefix, branchName),
 		Env:    repo_module.PushingEnvironment(doer, repo),
-	}); err != nil {
+	}
+
+	if sha != "" {
+		pushOpts.ForceWithLease = fmt.Sprintf("%s:%s", git.BranchPrefix+branchName, sha)
+	}
+
+	if err := git.Push(ctx, repo.RepoPath(), pushOpts); err != nil {
 		if git.IsErrPushOutOfDate(err) || git.IsErrPushRejected(err) {
 			return err
 		}