7b31a09a

Adopt a branch that exists when HEAD points at one that does not

a73x 2026-08-18 14:41

Commit message

Adopt a branch that exists when HEAD points at one that does not

A repository the server creates on first push is born from `init_bare`,
which aims HEAD at whatever `init.defaultBranch` says. On a container
with no gitconfig that is `master`, and nothing in the push path ever
moves it. Push `main` and HEAD dangles for the life of the repository:
no HEAD is advertised, and a clone fetches every object but has nothing
to check out. The client reports it as a warning and exits 0, so the
result is an empty working tree from a repository full of files.

Five of the seven repositories on the live server were in this state.

Adopting after the push is the alternative to guessing a default branch
name at creation time, which is a guess that can be wrong. This one
cannot: it fires only on a HEAD that resolves to nothing, so a branch an
operator chose deliberately is never second-guessed, and because it runs
on every push an already-dangling repository heals on its next one.
`main` and `master` are preferred over the alphabetical pick only to
keep the choice predictable when a first push carries several branches.

Failing to settle HEAD does not fail the push the client has already
completed; it is logged and the push stands.

The test pushes a branch named neither `main` nor `master`. Named
either, it passes on any machine whose `init.defaultBranch` happens to
match — which is how this went unnoticed: libgit2 reads the developer's
gitconfig, so the bug is invisible everywhere except where it lives.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/server/repos.rs

+    resolve(repos_dir, requested).or_else(|| resolve(repos_dir, requested.strip_suffix(".git")?))
+/// Point HEAD at a branch that exists, when it currently points at one that
+/// does not.
+///
+/// A repository born from `init_bare` has HEAD aimed at whatever
+/// `init.defaultBranch` said — a branch nobody has pushed yet. Nothing in the
+/// push path moves it, so unless something adopts the branch that actually
+/// arrives, HEAD dangles for the life of the repository: no HEAD is
+/// advertised, and a clone fetches every object but has nothing to check out.
+///
+/// Adoption is the alternative to guessing a default branch name at creation
+/// time, which is a guess that can be wrong. This one cannot: it only ever
+/// fires on a HEAD that resolves to nothing, so a default branch an operator
+/// chose deliberately is never second-guessed. Running it after every push
+/// also means an already-dangling repository heals on its next one.
+///
+/// `main` and `master` are preferred over an alphabetical pick only to keep
+/// the choice predictable when a first push carries several branches at once.
+pub fn adopt_head_if_unborn(repo_path: &Path) -> Result<(), git2::Error> {
+    let repo = git2::Repository::open(repo_path)?;
+    // A HEAD that resolves is already an answer. Leave it alone.
+    if repo.head().is_ok() {
+        return Ok(());
+    }
+    let mut names: Vec<String> = repo
+        .branches(Some(git2::BranchType::Local))?
+        .filter_map(Result::ok)
+        .filter_map(|(branch, _)| branch.name().ok().flatten().map(str::to_string))
+        .collect();
+    names.sort();
+    let chosen = ["main", "master"]
+        .iter()
+        .find(|preferred| names.iter().any(|n| n == *preferred))
+        .map(|preferred| (*preferred).to_string())
+        .or_else(|| names.first().cloned());
+    // No branches at all — a push of nothing but collab refs, say. There is
+    // nothing to adopt, and an unborn HEAD is the honest description of that.
+    let Some(chosen) = chosen else {
+        return Ok(());
+    };
+    repo.set_head(&format!("refs/heads/{chosen}"))
+}
+/// Open a git2::Repository from a RepoEntry.
+pub fn open(entry: &RepoEntry) -> Result<git2::Repository, git2::Error> {
+    if entry.bare {

src/server/ssh/session.rs

Old		New
@@ -974,6 +974,16 @@ async fn run_git_command(
974	let status = child.wait().await?;	974	let status = child.wait().await?;
975	let exit_code = status.code().unwrap_or(1) as u32;	975	let exit_code = status.code().unwrap_or(1) as u32;
976		976
		977	// A push is the only thing that can create the branch HEAD should name, so
		978	// this is the point at which a repository whose HEAD never resolved can
		979	// start resolving. Failing to settle it is not a reason to fail the push
		980	// the client already completed.
		981	if git_cmd == GitCmd::ReceivePack && exit_code == 0 {
		982	if let Err(e) = crate::repos::adopt_head_if_unborn(repo_path) {
		983	warn!("Could not settle HEAD in {:?}: {}", repo_path, e);
		984	}
		985	}
		986
977	let _ = handle.exit_status_request(channel, exit_code).await;	987	let _ = handle.exit_status_request(channel, exit_code).await;
978	let _ = handle.eof(channel).await;	988	let _ = handle.eof(channel).await;
979	let _ = handle.close(channel).await;	989	let _ = handle.close(channel).await;

tests/common/mod.rs

Old		New
@@ -1380,7 +1380,7 @@ impl ServerHarness {
1380	/// Run `git push` over SSH from an arbitrary working tree, as `key`,	1380	/// Run `git push` over SSH from an arbitrary working tree, as `key`,
1381	/// returning the raw output rather than asserting success.	1381	/// returning the raw output rather than asserting success.
1382	pub fn ssh_push_from(&self, dir: &Path, key: &Path, repo: &str, refspec: &str) -> Output {	1382	pub fn ssh_push_from(&self, dir: &Path, key: &Path, repo: &str, refspec: &str) -> Output {
1383	let url = format!("ssh://git@127.0.0.1:{}/{}.git", self.ssh_addr.port(), repo);	1383	let url = self.ssh_url_for(repo);
1384	Command::new("git")	1384	Command::new("git")
1385	.args(["push", &url, refspec])	1385	.args(["push", &url, refspec])
1386	.env("GIT_SSH_COMMAND", ssh_command_for(key))	1386	.env("GIT_SSH_COMMAND", ssh_command_for(key))
@@ -1399,7 +1399,7 @@ impl ServerHarness {
1399	/// Fetch over SSH as `key`, returning raw output. Used to assert that an	1399	/// Fetch over SSH as `key`, returning raw output. Used to assert that an
1400	/// unreadable repository is refused rather than merely empty.	1400	/// unreadable repository is refused rather than merely empty.
1401	pub fn ssh_fetch(&self, dir: &Path, key: &Path, repo: &str) -> Output {	1401	pub fn ssh_fetch(&self, dir: &Path, key: &Path, repo: &str) -> Output {
1402	let url = format!("ssh://git@127.0.0.1:{}/{}.git", self.ssh_addr.port(), repo);	1402	let url = self.ssh_url_for(repo);
1403	Command::new("git")	1403	Command::new("git")
1404	.args(["ls-remote", &url])	1404	.args(["ls-remote", &url])
1405	.env("GIT_SSH_COMMAND", ssh_command_for(key))	1405	.env("GIT_SSH_COMMAND", ssh_command_for(key))
@@ -1495,11 +1495,27 @@ impl ServerHarness {
1495		1495
1496	/// ssh:// URL for the harness repo, for use as a git-collab remote.	1496	/// ssh:// URL for the harness repo, for use as a git-collab remote.
1497	pub fn repo_ssh_url(&self) -> String {	1497	pub fn repo_ssh_url(&self) -> String {
1498	format!(	1498	self.ssh_url_for(&self.repo_name)
1499	"ssh://git@127.0.0.1:{}/{}.git",	1499	}
1500	self.ssh_addr.port(),	1500
1501	self.repo_name	1501	/// ssh:// URL for any repository name on this server, including one the
1502	)	1502	/// server has never seen — which is how a test reaches the create-on-push
		1503	/// path.
		1504	pub fn ssh_url_for(&self, repo: &str) -> String {
		1505	format!("ssh://git@127.0.0.1:{}/{}.git", self.ssh_addr.port(), repo)
		1506	}
		1507
		1508	/// Clone over SSH into `dest`, returning raw output rather than asserting
		1509	/// success. A clone is the only thing that exercises HEAD end to end: it
		1510	/// is the client's checkout, not the ref advertisement, that a dangling
		1511	/// HEAD actually breaks.
		1512	pub fn ssh_clone(&self, repo: &str, dest: &Path) -> Output {
		1513	Command::new("git")
		1514	.args(["clone", &self.ssh_url_for(repo), dest.to_str().unwrap()])
		1515	.env("GIT_SSH_COMMAND", ssh_command_for(&self.ssh_client_key()))
		1516	.env("GIT_TERMINAL_PROMPT", "0")
		1517	.output()
		1518	.expect("failed to run git clone")
1503	}	1519	}
1504		1520
1505	pub fn work_repo(&self) -> &TestRepo {	1521	pub fn work_repo(&self) -> &TestRepo {

tests/server_behavior_test.rs

@@ @@ -1,5 +1,7 @@ @@
+mod common;
+use std::process::Command;
+use common::ServerHarness;
+#[test]
+        tree.body
+    );
+/// A repository the server creates on first push must end up with a HEAD that
+/// resolves to a branch that actually arrived.
+///
+/// `git init --bare` stamps HEAD at a branch name nobody has pushed yet —
+/// whatever `init.defaultBranch` happens to say, which on a server with no
+/// gitconfig is `master`. If nothing adopts the branch that does arrive, HEAD
+/// dangles forever: the server advertises no HEAD, and the client clones every
+/// object but has nothing to check out — an empty working tree from a
+/// repository full of files, reported only as a warning.
+///
+/// The pushed branch is deliberately named neither `main` nor `master`, so no
+/// `init.defaultBranch` on the machine running the tests can make HEAD line up
+/// by luck and hide the bug.
+#[test]
+fn cloning_a_server_created_repository_checks_out_the_pushed_branch() {
+    let harness = ServerHarness::new("behavior-head-adoption");
+    let key = harness.ssh_client_key();
+    harness
+        .work_repo()
+        .commit_file("README.md", "hello\n", "add readme");
+    // A name the server has never seen, so the push is what creates it.
+    let push = harness.ssh_push_from(
+        harness.work_repo().dir.path(),
+        &key,
+        "created-on-push",
+        "main:trunk",
+    );
+    assert!(
+        push.status.success(),
+        "push failed: {}",
+        String::from_utf8_lossy(&push.stderr)
+    );
+    let dest = harness.scratch("clone-of-created").join("created-on-push");
+    let clone = harness.ssh_clone("created-on-push", &dest);
+    assert!(
+        clone.status.success(),
+        "clone failed: {}",
+        String::from_utf8_lossy(&clone.stderr)
+    );
+    assert!(
+        dest.join("README.md").is_file(),
+        "clone left no working tree; HEAD did not resolve.\n{}",
+        String::from_utf8_lossy(&clone.stderr)
+    );
+}
+/// Adoption settles HEAD once. A later push that brings a branch the
+/// preference order rates more highly must not move it.
+///
+/// Without this, HEAD would drift under the operator: a repository serving
+/// `trunk` would silently switch to `main` the moment a `main` appeared, and
+/// every subsequent clone would check out a different branch than the last.
+#[test]
+fn a_settled_head_is_not_moved_by_later_pushes() {
+    let harness = ServerHarness::new("behavior-head-stable");
+    let key = harness.ssh_client_key();
+    let work = harness.work_repo();
+    work.commit_file("README.md", "hello\n", "add readme");
+    let push = harness.ssh_push_from(work.dir.path(), &key, "settled", "main:trunk");
+    assert!(
+        push.status.success(),
+        "first push failed: {}",
+        String::from_utf8_lossy(&push.stderr)
+    );
+    // `main` outranks `trunk` in the adoption preference order, so a HEAD that
+    // is still up for grabs would land on it.
+    let push = harness.ssh_push_from(work.dir.path(), &key, "settled", "main:main");
+    assert!(
+        push.status.success(),
+        "second push failed: {}",
+        String::from_utf8_lossy(&push.stderr)
+    );
+    let dest = harness.scratch("clone-of-settled").join("settled");
+    let clone = harness.ssh_clone("settled", &dest);
+    assert!(
+        clone.status.success(),
+        "clone failed: {}",
+        String::from_utf8_lossy(&clone.stderr)
+    );
+    let checked_out = Command::new("git")
+        .args(["rev-parse", "--abbrev-ref", "HEAD"])
+        .current_dir(&dest)
+        .output()
+        .expect("failed to run git rev-parse");
+    assert_eq!(
+        String::from_utf8_lossy(&checked_out.stdout).trim(),
+        "trunk",
+        "HEAD drifted off the branch it had already settled on"
+    );
+}