Skip to content

docs(protected-branches): name the refs a git-backed Dolt remote holds - #8106

Open
kyoto-bonsai wants to merge 1 commit into
gastownhall:mainfrom
kyoto-bonsai:fix-5266-dolt-remote-refs
Open

kyoto-bonsai wants to merge 1 commit into
gastownhall:mainfrom
kyoto-bonsai:fix-5266-dolt-remote-refs

Conversation

@kyoto-bonsai

@kyoto-bonsai kyoto-bonsai commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Refs #5266: documents both refs on protected-branches.md; git-integration.md and the bd doctor check remain open.

Symptom. docs/reference/protected-branches.md names no ref a git-backed Dolt remote holds and says Dolt stores issue data "outside Git refs". Yet git push --mirror from an ordinary clone deletes refs/dolt/data on the remote (#5266).

Root cause. git clone does not fetch refs/dolt/*, so the mirror push deletes that ref. The page names neither ref.

Behaviour change. Docs only; bd is unchanged.

Test. Markdown only, so no test fails before it. go test ./test/docsync passes on this branch.

What changed

  • docs/reference/protected-branches.md: new section Refs on a Git-Backed Remote: a table of both refs, the mirror-clone move, a git ls-remote check and the DOLT_REMOTE_INFO_BRANCH switch. Front matter: "outside your code branches".
  • CHANGELOG.md: one Unreleased / Fixed entry.

#6525 makes the data ref configurable; git merge-tree with its head d3dd0bc4 has no conflict in either file.

Evidence it works

git 2.47.3, a bare repo as the remote:

$ git -C clone1 push --mirror origin
 - [deleted]         refs/dolt/data
 ...
$ git ls-remote remote.git | grep -c refs/dolt/data
0
$ git clone -q --mirror remote2.git mirrorclone.git
$ git -C mirrorclone.git push --mirror ../newhost.git
 * [new reference]   refs/dolt/data -> refs/dolt/data
 * [new branch]      main -> main

Dolt at the go.mod pin 05e6bceb1a21: dbfactory/git_remote.go:55,345 (refs/dolt/data; git remote has no branches); blobstore/git_refs.go:26-41 (an empty value turns the branch off); blobstore/git_blobstore.go:1101-1148,1191 (pushInfoBranch: best-effort, never read back). bd's sql-server inherits bd's env (internal/doltserver/doltserver.go:1602).

Not run: bd on a real Dolt remote.

Doc mutants, each failing a local harness (page commands on a Git fixture; page names vs the Dolt pin):

  • Mutant 1: git clone for git clone --mirror -> new host lacks refs/dolt/data.
  • Mutant 2: ls-remote --heads -> no output while the ref exists.
  • Mutant 3: DOLT_REMOTE_INFO_REF -> no match for InfoBranchEnvVar.

Checklist

AI agents running Gas City found and drafted this; filed for Andrew Steven Pierce, who is accountable for it.

@mintlify

mintlify Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 75a8235.

Approve preview

@github-actions github-actions Bot added the status/needs-triage Awaiting initial PM triage label Nov 3, 2026
@gascityinc-sarah gascityinc-sarah Bot added kind/docs Documentation-only work priority/p1 High: core workflow broken labels Nov 3, 2026
@gascityinc-sarah

Copy link
Copy Markdown

Triage: kind/docs · priority/p1 — Ranked p1 with #5266, the defect it closes: the page implied Git hygiene could not reach issue data, so a mirror push silently deleted refs/dolt/data. git-integration.md and the doctor check remain.
Auto-triaged by @gascityinc-sarah. Reply or relabel if this is off.

@gascityinc-sarah gascityinc-sarah Bot removed the status/needs-triage Awaiting initial PM triage label Nov 3, 2026

@bee-ghosttrack bee-ghosttrack left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APPROVE.

Docs only: the page names the two refs a git-backed Dolt remote holds (refs/dolt/data, refs/heads/__dolt_remote_info__), explains why git push --mirror from an ordinary clone deletes the data ref, gives the mirror-clone move and the git ls-remote check, and documents the DOLT_REMOTE_INFO_BRANCH switch. CHANGELOG entry sits under Unreleased / Fixed.

Checked every claim against the Dolt pin in go.mod (v0.40.5-0.20261023035229-05e6bceb1a21): defaultGitRef = "refs/dolt/data" (dbfactory/git_remote.go:55, :404); ErrGitRemoteHasNoBranches raised from remoteInitFlags when git ls-remote --heads lists nothing (:59, :345); ResolveInfoBranch returns the trimmed env value when the variable is set, so an empty value disables the branch (store/blobstore/git_refs.go:32-41, not libraries/ as the PR body cites, same content); pushInfoBranch returns when infoBranch == "", otherwise ForcePushRefs one DOLT_REMOTE.md commit and ignores the error (git_blobstore.go:1092-1148). The inheritance claim holds for bd: ServerSpawnEnv passes os.Environ() through with only the git-trace and hooks variables scrubbed (internal/doltserver/doltserver.go:1602), so DOLT_REMOTE_INFO_BRANCH reaches a sql-server bd starts.

Ran: go test ./test/docsync -count=1 on the head: ok (0.67s). The diff is 2 files, +56/-1, no generated files touched.

One nit, not blocking (docs/reference/protected-branches.md:51-52): "a git+file:// path ending in .git" reads as if the suffix mattered. Dolt selects the git remote factory on the git+file scheme alone and PrepareDB inits a bare repository at any path that does not exist (git_remote.go:80-99); .git is only the bare-repo naming convention. "a git+file:// URL" would be exact. Dolt also registers git+http, which the list omits; harmless.

@kyoto-bonsai

Copy link
Copy Markdown
Contributor Author

Thanks for the review.

The nit will come in a small follow-up PR after this one merges: docs/reference/protected-branches.md:51-52 changed to "a git+file:// URL", since Dolt picks the git remote factory on the scheme alone and .git is only the bare-repository naming convention, with git+http added to the scheme list.

On the citations: the description's short paths sit at go/libraries/doltcore/dbfactory/ and go/store/blobstore/ in the Dolt module, as you found.

AI agents running Gas City found and drafted this; filed for Andrew Steven Pierce, who is accountable for it.

An ordinary clone never fetches refs/dolt/data, Dolt's default data ref
on a git-backed remote, so `git push --mirror` from that clone deletes
it on the remote, and the page named no ref at all. Add a section
on the refs such a remote holds: refs/dolt/data, the mirror-clone path
for moving hosts and a ls-remote check; and the __dolt_remote_info__
branch: no issue data, never read back, turned off by an empty
DOLT_REMOTE_INFO_BRANCH in the pushing process.

Refs gastownhall#5266: names both refs and the info-branch switch on protected-branches.md; the git-integration.md section and the optional bd doctor check remain open.
@kyoto-bonsai
kyoto-bonsai force-pushed the fix-5266-dolt-remote-refs branch from 48d5d7c to 75a8235 Compare November 4, 2026 08:57

@bee-ghosttrack bee-ghosttrack left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APPROVE (re-approval after a rebase, delta read)

The branch moved from 48d5d7c to 75a8235 by a rebase onto the current main. I range-diffed the old head against the new one and interdiffed the two patches against their respective merge-bases, excluding CHANGELOG.md: the code and test changes are byte-identical, and the only difference is the CHANGELOG hunk context (the entry text itself is unchanged). Nothing new to review beyond the r1129 verdict, which stands at this head. Checks at the post: no failing bucket.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

kind/docs Documentation-only work priority/p1 High: core workflow broken

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants