Document non-fast-forward requirement for topo bootstrap

88b109f→main·

Successive topo checkpoints aren't guaranteed to be in an ancestor-descendant relationship — topological order can interleave parallel branches — so the internal refs/gitsync/bootstrap/heads/temp ref may receive non-fast-forward updates between batches. The temp ref is purely internal scaffolding (user-visible refs/heads and refs/tags only get a single fast-forward update at cutover), but targets that enforce receive.denyNonFastforwards across all refs will reject the temp-ref updates and fail the bootstrap.

Major hosts (GitHub, GitLab, Bitbucket, Cloudflare) don't enable this by default; the constraint only matters on hardened deployments. Document on the Strategy field, the BootstrapStrategy* SDK constants, and both CLI flag descriptions.

Sessions

Changes

4

• cmd/git-sync

  • Mbootstrap.go+1/-1
  • Msyncplan.go+1/-1

• internal/strategy/bootstrap

  • Mbootstrap.go+13

• unstable

  • Mclient.go+7

79 unmodified lines

cmd.Flags().BoolVar(&jsonOutput, "json", false, "print JSON output")
cmd.Flags().Int64Var(&req.Options.MaxPackBytes, "max-pack-bytes", 0, "abort bootstrap if the streamed source pack exceeds this many bytes")
cmd.Flags().Int64Var(&req.Options.TargetMaxPackBytes, "target-max-pack-bytes", 0, "target receive-pack body size limit; batches are planned and auto-subdivided to fit")
cmd.Flags().StringVar(&req.Options.BootstrapStrategy, "bootstrap-strategy", "", "checkpoint chain ordering: \"first-parent\" (default) or \"topo\". Use \"topo\" for merge-heavy repos where individual first-parent steps drag in unboundedly large side branches")
cmd.Flags().StringVar(&req.Options.BootstrapStrategy, "bootstrap-strategy", "", "checkpoint chain ordering: \"first-parent\" (default) or \"topo\". Use \"topo\" for merge-heavy repos where individual first-parent steps drag in unboundedly large side branches; requires the target to allow non-fast-forward updates on the refs/gitsync/ namespace")
addProtocolFlag(cmd, &protocolVal)
cmd.Flags().BoolVarP(&req.Options.Verbose, "verbose", "v", false, "verbose logging")

Mcmd/git-sync/bootstrap.go+1/-1

117 unmodified lines

cmd.Flags().IntVar(&req.Options.MaterializedMaxObjects, "materialized-max-objects", unstable.DefaultMaterializedMaxObjects, "abort non-relay materialized syncs above this many objects")
cmd.Flags().Int64Var(&req.Options.MaxPackBytes, "max-pack-bytes", 0, "abort bootstrap-relay push if the streamed source pack exceeds this many bytes")
cmd.Flags().Int64Var(&req.Options.TargetMaxPackBytes, "target-max-pack-bytes", 0, "target receive-pack body size limit; batches are planned and auto-subdivided to fit")
cmd.Flags().StringVar(&req.Options.BootstrapStrategy, "bootstrap-strategy", "", "checkpoint chain ordering for bootstrap: \"first-parent\" (default) or \"topo\". Use \"topo\" for merge-heavy repos where individual first-parent steps drag in unboundedly large side branches")
cmd.Flags().StringVar(&req.Options.BootstrapStrategy, "bootstrap-strategy", "", "checkpoint chain ordering for bootstrap: \"first-parent\" (default) or \"topo\". Use \"topo\" for merge-heavy repos where individual first-parent steps drag in unboundedly large side branches; requires the target to allow non-fast-forward updates on the refs/gitsync/ namespace")
addProtocolFlag(cmd, &protocolVal)
cmd.Flags().BoolVarP(&req.Options.Verbose, "verbose", "v", false, "verbose logging")

Mcmd/git-sync/syncplan.go+1/-1

67 unmodified lines

// "checkpoint" branches where each first-parent step drags in a
// large second-parent ancestry that would otherwise have to be
// pushed in one indivisible pack.
//
// Server requirement under "topo": successive checkpoints aren't
// always in an ancestor-descendant relationship (topological
// order can interleave parallel branches), so the internal
// refs/gitsync/bootstrap/heads/<branch> temp ref may receive
// non-fast-forward updates between checkpoints. The temp ref is
// purely internal scaffolding — user-visible refs (refs/heads,
// refs/tags) only receive a single fast-forward update at
// cutover — but targets that enforce receive.denyNonFastforwards
// across all refs (not just refs/heads) will reject these
// updates and fail the bootstrap. Major hosts (GitHub, GitLab,
// Bitbucket, Cloudflare) do not enable this by default; the
// constraint only matters on hardened/locked-down deployments.
Strategy string

Minternal/strategy/bootstrap/bootstrap.go+13

46 unmodified lines

// BootstrapStrategy values accepted by AdvancedOptions.BootstrapStrategy.
// Empty is treated as the default (first-parent).
//
// BootstrapStrategyTopo additionally requires the target to allow
// non-fast-forward updates under the refs/gitsync/ namespace, since
// successive checkpoints under topological ordering aren't guaranteed
// to be in an ancestor-descendant relationship and the internal temp
// ref may receive non-ff updates between batches. Major hosts allow
// this by default; only locked-down deployments need to be checked.
const (
    BootstrapStrategyFirstParent = "first-parent"
    BootstrapStrategyTopo        = "topo"
)

Munstable/client.go+7