docs(install): the path bug is symlinks, not /var

The comments and Agent Note blamed macOS resolving /var through
private/var. That is only how the mismatch surfaced in temp fixtures, since
mktemp hands back a /var path there.

The real condition is broader: Git always reports resolved paths, so
comparing one against an unresolved path disagrees whenever a symlink sits
anywhere above the checkout. A symlinked home directory alone triggers it —
reproduced with no /var involved — which is common wherever homes live
behind a symlink or on a network mount.

Naming the cause correctly keeps a reader from dismissing resolve_dir as
macOS-only defensiveness.
This commit is contained in:
Turtle
2026-07-31 23:47:58 +08:00
parent db432c1e74
commit c435350561
5 changed files with 11 additions and 9 deletions

View File

@@ -71,10 +71,12 @@ DSH_STAGING_BRANCH=dsh-staging/$DSH_STAMP
DSH_STAGING=$DSH_SOURCE/staging-$DSH_STAMP
# --- path helpers ---------------------------------------------------------------
# Every path comparison below runs on physical paths. macOS resolves /var through
# a symlink to /private/var, so comparing a git-reported (already resolved) path
# against an unresolved one silently misclassifies an existing managed install as
# a foreign clone and builds a second container beside the real one.
# Every path comparison below runs on physical paths. Git always reports resolved
# paths, so comparing one against an unresolved path disagrees whenever a symlink
# sits anywhere above the checkout — a symlinked home directory is enough, and
# macOS reaches every mktemp path that way through /var -> private/var. The
# mismatch silently misclassifies an existing managed install as a foreign clone
# and builds a second container beside the real one.
# `git rev-parse --path-format=absolute` would do this, but it needs git 2.31+.
#
# A not-yet-created directory (the container on a fresh install) has no physical