<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Collaborate/take over this issue](https://contributors.gitlab.com/manage-issue?action=work&projectId=278964&issueIid=422793) </details> <!--IssueSummary end--> ### Proposal Server-side git repositories use the pseudo ref HEAD to determine which branch is the default branch. This reference is set even for newly created empty repositories. The HEAD file is required for a repository to be valid. This branch is called "unborn". Gitlab for historic reasons does not strictly rely on HEAD and instead [uses a heuristic](https://gitlab.com/gitlab-org/gitaly/-/blob/e4c8756b70e743147d001ef2d0744ecc4dc326e7/internal/git/localrepo/refs.go#L323) to determine the default branch: 1. If a branch exists that matches HEAD, use it. 2. If a branch exists that has the name `heads/refs/main`, use it. 3. If a branch exists that has the name `heads/refs/master`, use it. 4. If there are no branches, use nothing. 5. Otherwise, use the first branch as determined by git ordering. This leads to confusing default branch selection: * Empty repositories end up having no default branch even though git has set one. * If there are no branches that match HEAD/main/master a default is picked arbitrarily. We already know that this causes confusion - https://gitlab.com/gitlab-org/gitaly/-/issues/1446 In https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5880 a parameter was added to the RPC `FindDefaultBranch` called `head_only` which makes sure that the RPC will only use HEAD for the default branch. This parameter [has already been added to gitlab-rails](https://gitlab.com/gitlab-org/gitlab/-/blob/9398e5f65d2729bbfddf7db2daa4194630f85f8f/lib/gitlab/git/repository.rb#L96). I propose that all usages of `Repository#head_ref` in gitlab-rails be converted to have `head_only: true`. This conversion was already attempted wholesale from the gitaly side, but there were too many failures. So instead we likely need to proceed with this conversion on a case-by-case basis.