GitoxideLabs/gitoxide gix-worktree-state-v0.37.0

gix-worktree-state v0.37.0

on GitHub

Bug Fixes

• resolve Windows directory symlink chains

  Delaying symlinks until regular files are written is insufficient on
  Windows: an early link can target another link that has not been created
  yet. A single target probe then leaves a file link where a directory link
  is required, making paths such as a-child -> z-dir/nested unusable.
  Git for Windows retries unresolved links when directory links appear.

  Add gix_fs::symlink::create_or_delay() and retry unresolved checkout
  entries while other links make progress. When a pass makes no progress,
  create the remaining dangling or cyclic links with the existing file
  fallback.

  Completed links need no removal or recreation. For forced overwrites,
  try creation before unlinking so a deferred replacement leaves the
  existing link intact if a later object error aborts checkout.

• cap automatic macOS checkout at four workers

  Using all logical cores for checkout causes APFS creation contention on
  macOS. Benchmark fresh checkouts of the Linux tree to choose a default
  that preserves throughput without starting unnecessary workers.

  Resolve None and Some(0) to at most four available logical cores in
  shared checkout plumbing, so clone, linked-worktree creation, and index
  checkout inherit the cap. Positive explicit limits remain overrides;
  other platforms retain their existing defaults, and builds without
  gix-parallel/parallel continue to run on the calling thread. Update the
  checkout.workers and clone documentation accordingly.

  Why four workers

  On an Apple M4 Max with 16 logical CPUs and native case-insensitive APFS,
  the initial worker sweep measured median checkout times of 2.564 s at
  four workers, 3.774 s at eight, and 6.874 s at automatic sixteen. An initial
  probe using newer offline-resolved dependencies favored five workers,
  but that advantage did not reproduce with the workspace's locked versions.

  The final comparison using those locked versions covers every execution
  order of four, five, and six workers, with six samples per setting:

  Workers	Median seconds	Range
  4	2.664813	2.533386–3.106756
  5	2.665293	2.513454–2.938505
  6	2.903967	2.843629–4.047406

  Four and five split the paired wins three to three and have effectively
  identical medians. Choose four to obtain the same measured throughput
  with one fewer worker, matching the existing macOS removal cap.

  Git and single-threaded reference

  A separate three-round comparison with the workspace's locked dependencies
  checks the same collision-safe Linux tree against Apple Git 2.54.0. Rotate
  execution order so each method runs first, second, and third once:

  Checkout	Median seconds	Range
  Git, one worker	7.293862	7.279254–7.394098
  gix, one thread	6.875375	6.822443–6.958276
  gix, four workers	2.376388	2.349792–2.493034

  Git runs checkout-index --all --prefix=<fresh-destination>/ with
  checkout.workers=1 against the prebuilt retained index. Its timer includes
  process startup and index loading; gix times the checkout call with an
  already loaded index. Index preparation, volume synchronization, complete
  Git content/mode/symlink validation, and cleanup are outside both timers.
  These are initial-checkout references, not timings of full clone or branch
  switch workflows. No builds or tests overlap the timed samples.

  Raw wall seconds in execution order:

  • Round 1: Git 7.394098, gix/1 6.822443, gix/4 2.376388.
  • Round 2: gix/4 2.493034, Git 7.279254, gix/1 6.958276.
  • Round 3: gix/1 6.875375, gix/4 2.349792, Git 7.293862.

  All nine checkouts pass Git content verification. This is a separate run
  from the four/five/six comparison above; compare methods within each run.

  Parallel Git reference

  A separate four-pair run compares Apple Git 2.54.0 with
  checkout.workers=3 and checkout.workers=4 on the same retained tree,
  using checkout-index --all --prefix=<fresh-destination>/ as above.
  Alternate execution order between rounds:

  Git workers	Median seconds	Range
  3	4.261867	4.058227–4.361033
  4	3.745698	3.611599–3.768478

  Four workers win all four pairs; three offers no advantage here. A
  separate warmup with GIT_TRACE2_EVENT confirms four checkout--worker
  processes; exclude that traced 3.367775 s sample from the timing table.
  All eight untraced checkouts pass Git content, mode, and symlink checks.
  Volume synchronization, validation, and removal remain outside timers;
  no probe compilation overlaps these measurements.

  Raw wall seconds in execution order:

  • Round 1: Git/3 4.058227, Git/4 3.768478.
  • Round 2: Git/4 3.733868, Git/3 4.227494.
  • Round 3: Git/3 4.361033, Git/4 3.611599.
  • Round 4: Git/4 3.757527, Git/3 4.296240.

  This later run measures Git's worker scaling. The earlier one-worker Git
  and gix figures are reference timings from their own run, rather than
  additional matched samples in this comparison.

  Fixture and limits

  Borrow objects read-only from the bare Linux repository at
  /Users/byron/dev/git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux,
  commit 707df3375124b51048233625a7e1c801e8c8a7fd. Use independent metadata
  and fresh destinations under /private/tmp, omitting thirteen later
  case-fold collisions that native APFS cannot represent. The retained tree
  contains 88,821 entries, including 79 symlinks, and 1,509,611,994 blob bytes.

  Time only checkout; synchronize the volume, verify content, executable
  modes, and symlinks against isolated Git, and remove destinations outside
  the timer. No builds or tests overlap timed samples. Keep the benchmark
  method and decisive measurements in this commit message.

  These warm-cache initial-checkout results cover one Mac and one volume.
  They do not establish an optimum for every filesystem, repository, filter
  pipeline, or incremental checkout. Explicit worker limits remain available
  for those workloads; no cold-cache or durable-write benchmark was made.

Commit Statistics

• 6 commits contributed to the release over the course of 14 calendar days.
• 14 days passed between releases.
• 2 commits were understood as conventional.
• 0 issues like '(#ID)' were seen in commit messages

Commit Details