學習日 14：一次性儲存庫中的 Git 協作

預測 --input 說明改進會改變 projects/text_tools/cli.py 的哪一行，以及複製的三個檔案中哪些必須保持位元組一致（用 sha256sum 驗證）。解釋為什麼 git diff 加零結束碼是證據而不是行為的證明，以及當 GIT_DIR 可能指向別的儲存庫時為何必須經 d14env（env -i + 私有 HOME/XDG/config/template + 關閉簽章）執行，以及為何 ( set -e 的 fail-stop 與 WORKDIR 驗證能防止失敗的 cd 在呼叫者儲存庫中執行 Git。執行以下完整的私有環境與檢查：

(
set -e
WORKDIR=$(mktemp -d)
[ -n "$WORKDIR" ] && [ -d "$WORKDIR" ] && [ -w "$WORKDIR" ] && [ -x "$WORKDIR" ] || {
  echo "abort: WORKDIR '$WORKDIR' is missing or unusable - refusing to run anything outside it" >&2
  exit 1
}
LEARN=/absolute/path/to/your/clone
[ -f "$LEARN/projects/text_tools/cli.py" ] || {
  echo "abort: LEARN must point at a checkout containing projects/text_tools/cli.py" >&2
  exit 1
}
export WORKDIR LEARN
mkdir -p "$WORKDIR/home" "$WORKDIR/xdg" "$WORKDIR/tpl" "$WORKDIR/tmp"
d14env() {
  env -i PATH="$PATH" HOME="$WORKDIR/home" XDG_CONFIG_HOME="$WORKDIR/xdg" \
      TMPDIR="$WORKDIR/tmp" WORKDIR="$WORKDIR" LEARN="$LEARN" \
      GIT_CONFIG_NOSYSTEM=1 GIT_CONFIG_GLOBAL=/dev/null \
      GIT_TEMPLATE_DIR="$WORKDIR/tpl" \
      GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=commit.gpgsign GIT_CONFIG_VALUE_0=false \
      LC_ALL=C PYTHONDONTWRITEBYTECODE=1 "$@"
}
command -v git sed python3
PYTHON_BIN="$(command -v python3)"
mkdir -p "$WORKDIR/base/projects/text_tools"
cp "$LEARN"/projects/text_tools/__init__.py "$LEARN"/projects/text_tools/core.py "$LEARN"/projects/text_tools/cli.py "$WORKDIR/base/projects/text_tools/"
cd "$WORKDIR/base"
d14env git init
d14env git config user.name "Learner"
d14env git config user.email "[email protected]"
d14env sha256sum projects/text_tools/*.py
d14env git add projects/
d14env git commit -m "text_tools snapshot"
d14env git clone "$WORKDIR/base" "$WORKDIR/clone"
cd "$WORKDIR/clone"
d14env git config user.name "Learner"
d14env git config user.email "[email protected]"
d14env git switch -c parser-help
d14env sed -i 's|corpus file\.|corpus file (UTF-8 by default; override with --encoding/--errors).|' projects/text_tools/cli.py
d14env git status --short
d14env git diff
d14env git diff --cached
d14env git diff --check
d14env git add projects/text_tools/cli.py
d14env git commit -m "cli: document --input decoding defaults"
d14env git log --oneline -3
d14env "$PYTHON_BIN" projects/text_tools/cli.py --help | grep -F "UTF-8 by default"
printf 'export WORKDIR=%s  # run this before the later activity blocks\n' "$WORKDIR"
)

在合併前預測你的變體會出現的衝突標記和最終行內容。解釋為什麼盲目選擇 ours 或 theirs 會遺失需求，以及解決如何同時滿足兩條驗收條件。參考序列（同一私有複製）：

(
set -e
: "${WORKDIR:?set WORKDIR to the private Day 14 fixture path first}"
[ -d "$WORKDIR/clone/.git" ] || { echo "private clone not found - run the setup block first"; exit 1; }
d14env() {
  env -i PATH="$PATH" HOME="$WORKDIR/home" XDG_CONFIG_HOME="$WORKDIR/xdg" \
      TMPDIR="$WORKDIR/tmp" WORKDIR="$WORKDIR" LEARN="$LEARN" \
      GIT_CONFIG_NOSYSTEM=1 GIT_CONFIG_GLOBAL=/dev/null \
      GIT_TEMPLATE_DIR="$WORKDIR/tpl" \
      GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=commit.gpgsign GIT_CONFIG_VALUE_0=false \
      LC_ALL=C PYTHONDONTWRITEBYTECODE=1 "$@"
}
command -v git sed python3
PYTHON_BIN="$(command -v python3)"
cd "$WORKDIR/clone"
d14env git switch -c desc-unicode
d14env sed -i 's|compute statistics, deterministic splits, and provenance artifacts\.|compute Unicode-aware statistics, deterministic splits, and provenance artifacts.|' projects/text_tools/cli.py
d14env git commit -am "describe Unicode-aware statistics"
d14env git switch -
d14env git switch -c desc-provenance
d14env sed -i 's|and provenance artifacts\.|and original-byte provenance artifacts.|' projects/text_tools/cli.py
d14env git commit -am "describe original-byte provenance"
if d14env git merge desc-unicode; then
  echo "unexpected: merge resolved cleanly" >&2
  exit 1
else
  echo "expected non-zero exit (content conflict): $?"
fi
d14env sed -n '/<<<<<<</,/>>>>>>>/p' projects/text_tools/cli.py
d14env "$PYTHON_BIN" - <<'PY'
from pathlib import Path
p = Path('projects/text_tools/cli.py')
s = p.read_text()
i = s.index('<<<<<<<')
j = s.index('\n', s.index('>>>>>>>', i))
resolved = '        description="Text and Data Tools: compute Unicode-aware statistics, deterministic splits, and original-byte provenance artifacts."\n'
p.write_text(s[:i] + resolved + s[j+1:])
PY
d14env git add projects/text_tools/cli.py
d14env git commit -m "merge: keep both requirements"
d14env git rev-list --parents -n 1 HEAD
d14env "$PYTHON_BIN" projects/text_tools/cli.py --help | grep -F "Unicode-aware"
d14env "$PYTHON_BIN" projects/text_tools/cli.py --help | grep -F "original-byte"
d14env git status --short
)

對與有效編輯同處一檔案的未暫存拼字錯誤，以及跟在單親壞提交之後的獨立良好提交：分別選擇 git restore、git revert 或保存的副本，並在執行前預測最終的差異與歷史。為什麼 KEEP 編輯必須在演示暫存錯誤之前提交，而不僅僅在工作樹中倖存？

(
set -e
: "${WORKDIR:?set WORKDIR to the private Day 14 fixture path first}"
[ -d "$WORKDIR/clone/.git" ] || { echo "private clone not found - run the setup block first"; exit 1; }
d14env() {
  env -i PATH="$PATH" HOME="$WORKDIR/home" XDG_CONFIG_HOME="$WORKDIR/xdg" \
      TMPDIR="$WORKDIR/tmp" WORKDIR="$WORKDIR" LEARN="$LEARN" \
      GIT_CONFIG_NOSYSTEM=1 GIT_CONFIG_GLOBAL=/dev/null \
      GIT_TEMPLATE_DIR="$WORKDIR/tpl" \
      GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=commit.gpgsign GIT_CONFIG_VALUE_0=false \
      LC_ALL=C PYTHONDONTWRITEBYTECODE=1 "$@"
}
command -v git sed python3
PYTHON_BIN="$(command -v python3)"
cd "$WORKDIR/clone"
d14env git switch -c d14-ref parser-help
d14env sed -i 's|compute statistics, deterministic splits, and provenance artifacts\.|compute Unicode-aware statistics, deterministic splits, and original-byte provenance artifacts.|' projects/text_tools/cli.py
d14env git commit -am "reference baseline: description keeps both requirement terms"
d14env sed -i 's|Unicode-aware statistics|statistisc|' projects/text_tools/cli.py
d14env sed -i 's|(default: 42)\.|(default: 42; any integer).|' projects/text_tools/cli.py
d14env cp projects/text_tools/cli.py "$WORKDIR/cli-backup.py"
d14env git diff
d14env sed -i 's|statistisc|Unicode-aware statistics|' projects/text_tools/cli.py
d14env git diff
d14env git diff --check
d14env "$PYTHON_BIN" projects/text_tools/cli.py --help | grep -F "any integer"
d14env git commit -am "document that --seed accepts any integer"
d14env sed -i 's|default=42,|default=7,|' projects/text_tools/cli.py
d14env git add projects/text_tools/cli.py
d14env git status --short
d14env git restore projects/text_tools/cli.py
d14env bash -c 'git diff --cached | grep -F "default=7"'
d14env git restore --staged projects/text_tools/cli.py
d14env git restore projects/text_tools/cli.py
d14env git status --short
d14env bash -c 'test -z "$(git status --porcelain)"'
d14env "$PYTHON_BIN" projects/text_tools/cli.py --help | grep -F "any integer"
d14env sed -i 's|default=42,|default=7,|' projects/text_tools/cli.py
d14env git commit -am "BAD: change default seed to 7"
BAD=$(d14env git rev-parse HEAD)
d14env sed -i 's|(default: 0.1)\.|(default: 0.1; must be in [0, 1]).|' projects/text_tools/cli.py
d14env git commit -am "GOOD: clarify split-ratio range"
d14env git revert --no-edit "$BAD"
d14env grep -F "default=42," projects/text_tools/cli.py
d14env grep -F "must be in [0, 1]" projects/text_tools/cli.py
d14env grep -F "any integer" projects/text_tools/cli.py
d14env git log --oneline -3
d14env git rev-list --count HEAD
MERGE_SHA=$(d14env git rev-list --all --merges -n 1)
[ -n "$MERGE_SHA" ] || { echo "no merge commit found - run the act-02 reference merge first" >&2; exit 1; }
if d14env git revert "$MERGE_SHA" 2>"$WORKDIR/merge_revert.err"; then
  echo "unexpected: merge revert succeeded without -m" >&2
  exit 1
else
  rc=$?
  grep -F "no -m option" "$WORKDIR/merge_revert.err" && echo "expected non-zero exit (merge needs -m): $rc"
fi
)

在執行強檢查前，預測 --help 列出 --quiet 是否證明該旗標生效。指出弱冒煙檢查看不到的缺陷，以及能暴露它的更強 CLI 檢查。修補程式（評審者編寫，非觀察到的代理輸出）：

(
set -e
: "${WORKDIR:?set WORKDIR to your private Day 14 fixture path first}"
[ -d "$WORKDIR/clone/.git" ] || { echo "private clone not found - run the setup block first"; exit 1; }
d14env() {
  env -i PATH="$PATH" HOME="$WORKDIR/home" XDG_CONFIG_HOME="$WORKDIR/xdg" \
      TMPDIR="$WORKDIR/tmp" WORKDIR="$WORKDIR" LEARN="$LEARN" \
      GIT_CONFIG_NOSYSTEM=1 GIT_CONFIG_GLOBAL=/dev/null \
      GIT_TEMPLATE_DIR="$WORKDIR/tpl" \
      GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=commit.gpgsign GIT_CONFIG_VALUE_0=false \
      LC_ALL=C PYTHONDONTWRITEBYTECODE=1 "$@"
}
command -v git sed python3
PYTHON_BIN="$(command -v python3)"
cd "$WORKDIR/clone"
d14env git switch -c add-quiet
d14env "$PYTHON_BIN" - <<'PY'
from pathlib import Path
p = Path('projects/text_tools/cli.py')
s = p.read_text()
old = '    parser.add_argument(\n        "--errors",'
assert s.count(old) == 1
s = s.replace(old, '''    parser.add_argument(
        "--quiet",
        action="store_true",
        help="Suppress the artifact-generation success summary.",
    )
    parser.add_argument(
        "--errors",''')
p.write_text(s)
PY
d14env git commit -am "add --quiet flag"
d14env "$PYTHON_BIN" projects/text_tools/cli.py --help | grep -F -- "--quiet"
mkdir -p "$WORKDIR/acts"
d14env printf 'a\nb\nc\n' > "$WORKDIR/acts/in.txt"
d14env "$PYTHON_BIN" projects/text_tools/cli.py --input "$WORKDIR/acts/in.txt" --split --output-dir "$WORKDIR/acts/out" --quiet
)