Manual project import: Fails to detect Github "main" branch

[benjaoming]

Details

Leaving the "Default branch" field empty does not work, but will start to build master branches.

• Read the Docs project URL: https://readthedocs.org/projects/example-sphinx-basic/
• Build URL (if applicable): https://readthedocs.org/projects/example-sphinx-basic/builds/17248339/
• Read the Docs username (if applicable): https://readthedocs.org/profiles/benjaoming/

Expected Result

• Importing a Github project, should immediately start building the default branch -- and if no default branch can be detected, then main should be the default
• Help text should mention main not master

Actual Result

git clone --no-single-branch --depth 50 https://github.com/readthedocs-examples/example-sphinx-basic .
git checkout --force master
error: pathspec 'master' did not match any file(s) known to git

[stsewd]

Importing a Github project, should immediately start building the default branch -- and if no default branch can be detected, then main should be the default

Currently the default is master, and if we change the default to main the same error will be faced when someone imports a project that doesn't have a branch named main.

We could reword the help text and say the default is master, leaving out the "default value of your VCS".

[benjaoming]

Is it not possible to detect which branch is default?

[stsewd]

Is it not possible to detect which branch is default?

Currently only if the project wasn't manually imported.

[benjaoming]

In addition to changing the help-text so it isn't directly misleading, another possible work-around would be to hard-code the initial value of the "Default branch" to main for manual imports? So it will always appear like this, forcing the user to take action?

[stsewd]

We could also try setting the default branch if the checkout step fails and the default version isn't set, something around these lines

readthedocs.org/readthedocs/vcs_support/backends/git.py

Lines 326 to 329 in 86befd2

	if not identifier:
	identifier = self.default_branch or self.fallback_branch
	identifier = self.find_ref(identifier)

[humitos]

I think we shouldn't guess the default branch or try anything customized on Read the Docs. Why not just default to the branch that git defaults by default? I mean, we should remove the step git checkout --force master when we don't have a default branch manually defined. Removing that step, everything should work. Git will use the branch cloned by default when doing git clone. That's it.

[humitos]

I got another customer hitting this problem. This bug blocks them when importing projects manually (e.g. because they are using Azure DevOps) and generates a bad UX at onboarding.

[agjohnson]

Why not just default to the branch that git defaults by default?

This seems like a good approach. Do we need that text input value to establish the latest Version object though?

[benjaoming]

I tried the method in this StackOverflow solution and I like it.

git remote show [your_remote] | sed -n '/HEAD branch/s/.*: //p'

I would propose to parse the git remote show output in Python instead of sed.

Tested with:

• github.com ✔️
• gitlab.com ✔️
• my own private SSH bare git repo ✔️
• bitbutcket.org ✔️

This seems to work with:

• Any currently checked out local branch
• Doesn't matter if remote is ssh or https
• Running the command needs to connect to the upstream repo - if ssh credentials do not work, the command fails

NOTICE

git help remote
# ...
       show
           Gives some information about the remote <name>.

           With -n option, the remote heads are not queried first with git ls-remote <name>; cached information is used instead.

We can add the option -n to cache. This makes the command extremely fast, and since it's a freshly cloned repo, perhaps that's what we want?

The reason I did these tests was a remark on StackOverflow saying The default branch is a github thing, not a git thing but I don't think anymore that the above method has anything specific to do with GitHub.

[FrostyX]

The "default branch" field is not a text field anymore, it is a select now. Which is a bit problem, when the main branch is missing. I ended up right-clicking to inspect and changed the

<option value="master" selected="">master</option>

to

<option value="main" selected="">main</option>

In case anyone needs to workaround the issue as well.

[benjaoming]

That workaround seems good @FrostyX - but a fix has also been committed in #9424 and is scheduled to be rolled out at the next release, probably early next week 🎉 If you happen to encounter any further issues, please let us know 👍