Git clone fails with "remote HEAD refers to nonexistent ref" when default branch is not `master`

[pokho]

Git clone fails with "remote HEAD refers to nonexistent ref" when default branch is not master

Description

When cloning a Keybase git repository where the default branch is main (or any branch other than master), the clone succeeds but no files are checked out. Git reports:

warning: remote HEAD refers to nonexistent ref, unable to checkout

This is a common issue for repositories created on GitHub after October 2020, when GitHub changed the default branch name from master to main.

Steps to Reproduce

1. Create a git repository locally with main as the default branch:

   mkdir test-repo && cd test-repo
   git init -b main
   echo "test" > README.md
   git add . && git commit -m "initial"

2. Add Keybase as a remote and push:

   git remote add origin keybase://private/username/test-repo
   git push -u origin main

3. Clone the repo to a new location:

   cd /tmp
   git clone keybase://private/username/test-repo test-clone

Expected Behavior

The repository should clone successfully with all files checked out on the main branch.

Actual Behavior

Cloning into 'test-clone'...
Initializing Keybase... done.
Syncing with Keybase... done.
Counting: done.
Cryptographic cloning: done.
warning: remote HEAD refers to nonexistent ref, unable to checkout

The .git directory is created but the working directory is empty.

Workaround

Manually specifying the branch works:

git clone --branch main keybase://private/username/test-repo

Root Cause Analysis

After examining the codebase, the issue stems from hardcoded references to master as the default branch:

1. go/kbfs/libgit/browser.go:75:

   const masterBranch = "refs/heads/master"

2. go/kbfs/kbfsgit/runner.go - The list command returns a HEAD symref pointing to refs/heads/master, but when the actual branch is main, this reference doesn't exist.

3. The go-git.v4 library used (gopkg.in/src-d/go-git.v4) initializes repositories with HEAD pointing to refs/heads/master by default, with no option to configure this.

Suggested Fix

1. Detect the actual default branch from the repository instead of hardcoding master:

   // Instead of:
   const masterBranch = "refs/heads/master"
   
   // Query the actual HEAD target:
   func getDefaultBranch(repo *gogit.Repository) plumbing.ReferenceName {
       ref, err := repo.Storer.Reference(plumbing.HEAD)
       if err != nil {
           return plumbing.ReferenceName("refs/heads/main")
       }
       return ref.Target()
   }

2. Update the HEAD symref in the list command to point to the actual branch that exists, not a hardcoded master.

3. Consider upgrading to go-git/v5 which supports InitOptions.DefaultBranch for better default branch configuration.

Environment

• Keybase client version: (latest)
• Git version: 2.x
• OS: Linux

Related Code

• go/kbfs/libgit/browser.go - Default branch constant
• go/kbfs/kbfsgit/runner.go - Git remote helper protocol handling
• go/kbfs/libgit/repo.go - Repository initialization

Impact

This affects any user who:

• Creates repos on GitHub (which defaults to main since Oct 2020)
• Uses modern git with init.defaultBranch set to main
• Pushes existing repos with main as the default branch to Keybase

Given GitHub's dominance and the industry shift to main, this will affect an increasing number of users over time.

[kg4zow]

If you just want to clone the repo, you can use the git clone command's -b option, like so:

git clone -b main keybase://xxx

If you want to set the repo's default branch on the Keybase server:

• cd into the repo's hidden directory.
  • /keybase/private/USER/.kbfs_git/REPO/
  • /keybase/team/TEAM/.kbfs_git/REPO/
• Edit the HEAD file to change the branch.
  • echo 'ref: refs/heads/main' > HEAD

After doing this, using git clone keybase://xxx without the -b option, should check out the correct branch.

Notes:

• You won't be able to see the .kbfs_git directories in a directory listing, but you can cd into them.
• I have no idea how to do this on windows.

---

@chrisnojima-zoom I reported the same exact issue probably 3-4 years ago, and then ended up figuring out how to do this on my own when nobody responded. I think @strib said he was going to look at adding a keybase git settings --primary-branch option so people wouldn't have to manually edit the HEAD file, or even need to be aware that the TLF/.kbfs_git/ directories exist - because people who aren't careful are likely to get curious and start tinkering with things, destroy their git repos, and then get even more mad because git repos don't have anything like the TLF/.kbfs_archived_xxx/ directories.