Force-checkout remote branch to fix unrelated histories

[ofalvai]

Checklist

• I've read and followed the Contribution Guidelines
• step.yml and README.md is updated with the changes (if needed)

Version

Requires a MAJOR/MINOR/PATCH version update

Context

Git clones can fail in persistent environments (bare-metal runners) when the build is triggered by a push event. Imagine this sequence:

1. Build 1 runs with the default step settings. It fetches origin/main (because it's not a PR build) with --depth=1 (default step setting).
2. New commits are pushed to origin/main
3. Build 2 runs: it fetches origin/main again with --depth=1, but when it tries to checkout and merge the local branch, it fails with the refusing to merge unrelated histories error.

An actual step log:

$ git "init"
Reinitialized existing Git repository in /home/bitrise-admin/ca71a338453a42a3/git/.git/
$ git "config" "gc.auto" "0"
$ git "fetch" "--jobs=10" "--depth=1" "--no-tags" "origin" "refs/heads/master"
From github.com:bitrise-io/ubuntu-android
 * branch            master     -> FETCH_HEAD
 + d0413b1...db22ecf master     -> origin/master  (forced update)
$ git "checkout" "master"
Switched to branch 'master'
Your branch and 'origin/master' have diverged,
and have 1 and 1 different commits each, respectively.
  (use "git pull" to merge the remote branch into yours)
$ git "merge" "origin/master"
fatal: refusing to merge unrelated histories
Checkout strategy used: gitclone.checkoutBranch
Failed to execute Step:
  updating branch (master) failed:
    fatal: refusing to merge unrelated histories

Changes

Branch checkout was implemented using a fetch + checkout + merge remote local sequence. This doesn't work in persistent envs because there is a leftover local branch from the previous run with a single commit (because of shallow fetching). The new remote-tracking branch also has a single commit, and there is no common ancestor of these two commits, so the merge command fails.

This PR changes the implementation of our branch checkout so that any previous local branch state is overwritten, sort of like a git pull --force.

The end result remains the same:

• The branch is checked out
• It is not behind origin
• If the local branch already exists, it's overwritten
• [new] If the local and remote branches diverged, the remote state wins

Investigation details

Decisions

[ofalvai]

Naming is hard 😵‍💫

[ofalvai]

The custom retry here adds nicer error message (a list of existing branch names), but if a branch doesn't exist, I think it fails in the fetch step above.
I don't have a strong opinion on this, but I don't like this abstraction and I can easily say goodbye to this.
I was also thinking about adding -B to this checkout wrapper, but it only works in the context of checking out branches, while the wrapper is used for tags and commits as well.