feat: adds option to force update new branch in contents routes

[robgonnella]

Allows users to specify a "force" option in API /contents routes when modifying files in a new branch. When "force" is true, and the branch already exists, a force push will occur provided the branch does not have a branch protection rule that disables force pushing.

This is useful as a way to manage a branch remotely through only the API. For example in an automated release tool you can pull commits, analyze, and update a release PR branch all remotely without needing to clone or perform any local git operations.

Resolve #35538

[wxiaoguang]

To be honest, I don't think the design is clear. It doesn't seem related to "git force push" when the "force" option is in a "file operation API".

Does the "force" mean "ignore creating branch if it exists and continue update the files on it", or "discarding the existing branch and create a new one from the old branch then update the files"?

For example in an automated release tool you can pull commits, analyze, and update a release PR branch all remotely without needing to clone or perform any local git operations.

I still have the question why "force" is necessary. You can also "try to create a new branch and ignore the errors if it exists, then update the files", or "delete the existing branch and ignore the errors, then create a new branch".

[wxiaoguang]

If I understand correctly, you'd like to make the file operation API work this way: "discarding the existing branch and create a new one from the old branch (like git force push) then update the files"?

[robgonnella]

If I understand correctly, you'd like to make the file operation API work this way: "discarding the existing branch and create a new one from the old branch (like git force push) then update the files"?

Yes I believe that would be the flow.

If you are starting from a "base branch", building your file changes from that point and then targeting a "new branch" as the final destination (exactly what the file updates API exposes), you have no option other than "force" if the "new branch" already exists.

In my case deleting the branch first and recreating would not be an option as the branch will have an open PR to the "base" branch and deleting the branch will auto close the existing PR. You would then have to recreate the PR as well. I've tried this as a workaround and I suppose it's doable but there are timing issues with waiting for the PR is be fully registered as closed before opening a new PR from the same branch. Overall the experience in that flow is sub-optimal.

[wxiaoguang]

Made some changes and simplified the code:

1. We don't need to check "branch protection" in the API logic, each "git push" will trigger git hook, and the protection is fully done there.
   • Also added some more test asserts to make sure we get the error messages we want.
2. All file operation APIs share the same logic, so we only need to test the "ForcePush" logic in one of them.

[robgonnella]

Ahh yes much nicer! Thank you for your thoughtful and detailed review and guidance!