Document why each fixture archive is .gitignored

gix-archive/tests/fixtures/generated-archives/.gitignore

@@ -1 +1,5 @@
+# The fixture script uses `ln -s`, an executable-bit toggle, and a
+# filter driver — features that cannot be round-tripped through an archive
+# extracted on every supported platform (notably Windows). The script is re-run
+# on the test host instead.
 basic.tar

gix-attributes/tests/fixtures/generated-archives/.gitignore

@@ -1 +1,5 @@
+# The fixture bakes a `baseline` file from `git check-attr -a`
+# output produced by the host's `git` binary. The exact format/lookup-order may
+# be sensitive to the git version, so the fixture is re-run on the test host to
+# stay aligned with the comparing git.
 make_attributes_baseline.tar

gix-blame/tests/fixtures/generated-archives/.gitignore

@@ -1,2 +1,7 @@
+# The fixture bakes `git blame --porcelain` baseline files (under
+# `.git/*.baseline`) produced by the host's `git` binary. The exact textual
+# output may be sensitive to the git version, so the fixture is re-run locally to
+# stay aligned with the comparing git on the test host. Both SHA-1 and SHA-256
+# variants share this constraint.
 make_blame_repo.tar
-make_blame_repo_sha256.tar
+make_blame_repo_sha256.tar

gix-command/tests/fixtures/generated-archives/.gitignore

@@ -1 +1,7 @@
+# The fixture seeds a tree of files with `.exe`/`.com` names that
+# carry no content beyond their stub shebang. On Windows, executable extensions
+# are interpreted at runtime and committing such a tree adds little value over
+# regenerating it locally — every test host can produce the same files in a
+# fraction of a second. Re-running the script also keeps the test aligned with
+# installation-wide Git line-ending and executable-bit behavior on extraction.
 win_path_lookup.tar

gix-config/tests/fixtures/generated-archives/.gitignore

@@ -1 +1,7 @@
+# The test (`from_git_dir`) drives `gix-config` through
+# `GIT_CONFIG_SYSTEM`, `HOME` and `USERPROFILE` overrides that point at the
+# generated worktree directory. The fixture is regenerated on each host so the
+# `system.config`, `.gitconfig`, `c.config`, `b.config` and XDG-shaped
+# `.config/git/config` files always live at the absolute path the test injects
+# into the environment for the current run.
 /make_config_repo.tar

gix-diff/tests/fixtures/generated-archives/.gitignore

@@ -1,3 +1,6 @@
-# The auto-generated sliders fixtures. For now it's experimental, but we may store it later once it's all working.
+# `make_diff_for_sliders_repo.sh` is a placeholder generated by the
+# `create-diff-cases` subcommand of `internal-tools` (see
+# `gix-diff/tests/README.md`). The auto-generated sliders fixtures are
+# experimental for now; we may track them later once the format stabilizes.
 /make_diff_for_sliders_repo.tar
-/make_diff_for_sliders_repo_sha256.tar
+/make_diff_for_sliders_repo_sha256.tar

gix-dir/tests/fixtures/generated-archives/.gitignore

@@ -1,3 +1,14 @@
+# Archives below are intentionally not tracked. Each fixture uses host-only
+# features (absolute paths baked into config, symlinks, or FIFOs) that cannot
+# be round-tripped through a committed archive, so the script is re-run on the
+# test host instead.
+
+# `nonstandard-worktree` sets `core.worktree "$PWD"` (an absolute path).
+# Several other sub-repos clone with relative URLs that resolve via the host's
+# working directory.
 many.tar
+# Uses `ln -s`, including breakout symlinks (`../..`) that cannot be safely
+# extracted on Windows.
 many-symlinks.tar
-fifo.tar
+# Uses `mkfifo`; FIFOs cannot be represented in archives extracted on Windows.
+fifo.tar

gix-discover/tests/fixtures/generated-archives/.gitignore

@@ -1 +1,5 @@
+# The fixture creates linked worktrees (`git worktree add`) whose
+# `.git` files and `.git/worktrees/*/gitdir` entries store absolute paths into
+# the host's working directory. Re-running the script on the test host produces
+# the correct paths for that machine.
 /make_basic_repo.tar

gix-filter/tests/fixtures/generated-archives/.gitignore

@@ -1,2 +1,7 @@
+# `baseline.sh` runs the host's `git` through a clean/smudge
+# filter driver supplied as its `$1` argument (a host-absolute path to the test
+# helper binary). Both the driver path and any filter output baked into the
+# resulting working tree are host-specific, so the fixture must be regenerated
+# per run. Both SHA-1 and SHA-256 variants share this constraint.
 /baseline.tar
 /baseline_sha256.tar

gix-fsck/tests/fixtures/generated-archives/.gitignore

@@ -1 +1,5 @@
+# The fixture sets `GIT_CONFIG_GLOBAL` to a host-absolute path and
+# performs `git clone --no-local --no-hardlinks --filter=...` partial clones
+# whose alternates/promisor metadata embeds the host path of `./base`, so a
+# committed archive would not relocate to the test runner's checkout.
 make_test_repos.tar

gix-ignore/tests/fixtures/generated-archives/.gitignore

@@ -1 +1,5 @@
+# The fixture writes `git-check-ignore.baseline` files captured
+# from the host's `git check-ignore -vn --stdin` output. The baselines are then
+# diffed against `gix-ignore`, so they must match the comparing git binary on
+# the test host. Regenerating per-run avoids possible drift across git versions.
 make_global_and_external_and_dir_ignores.tar

gix-index/tests/fixtures/generated-archives/.gitignore

@@ -1 +1,7 @@
-file_metadata.tar
+# `file_metadata.sh` calls `touch -d` with extreme dates (a
+# post-2038 future date and a pre-1970 past date) and falls back to a
+# 32-bit-fitting date when the future one is rejected. The actual mtimes that
+# end up on disk depend on the host filesystem's time_t/seconds-resolution
+# range (e.g., ext4 vs HFS+/APFS vs NTFS), so they cannot be round-tripped
+# through a committed tar — the fixture must be regenerated per host.
+file_metadata.tar

gix-odb/tests/fixtures/generated-archives/.gitignore

@@ -1,2 +1,11 @@
-repo_with_loose_objects.tar
+# The fixtures rely on object-database state that cannot be reliably committed:
+# loose-object layout may depend on installation-wide Git auto-gc/repack
+# behavior, and alternates point at host-absolute paths.
+
+# `make_alternates_odb.sh` writes `$PWD/object_source/.git/objects` into
+# `.git/objects/info/alternates`; the absolute path is host-specific.
 make_alternates_odb.tar
+# Fixture deliberately uses loose objects; whether commits remain loose vs. get
+# packed depends on installation-wide Git auto-gc/repack behavior, so the
+# layout is regenerated per run.
+repo_with_loose_objects.tar

gix-ref/tests/fixtures/generated-archives/.gitignore

@@ -1,5 +1,16 @@
+# The fixtures use `git worktree add` and then rewrite the
+# linked-worktree `.git` files (`gitdir:` pointer) and `.git/worktrees/*/gitdir`
+# entries. Those paths are absolute or relative to the host's working
+# directory, so the layout cannot relocate cleanly when extracted from a
+# committed archive — it must be rebuilt per host.
+
 make_worktree_repo.tar
 make_worktree_repo_sha256.tar
+# `_packed` variants additionally run `git pack-refs --all --prune`, whose
+# pack-refs file format can vary slightly across git versions.
 make_worktree_repo_packed.tar
 make_worktree_repo_packed_sha256.tar
+# `make_multi_hop_ref.sh` writes raw symbolic-ref text files under `.git/refs`
+# whose target paths are validated by the host git; regenerating per run keeps
+# the format aligned with the git binary doing the comparison.
 make_multi_hop_ref*.tar

gix-refspec/tests/fixtures/generated-archives/.gitignore

@@ -1,2 +1,7 @@
+# The fixture captures `baseline.git` files from
+# `git fetch --refmap= --dry-run -v origin <spec>` output. That textual format
+# may change between git versions, so the baseline must be produced by the host's
+# `git` to keep the comparison meaningful. Both SHA-1 and SHA-256 variants
+# share this constraint.
 /match_baseline.tar
 /match_baseline_sha256.tar

gix-status/tests/fixtures/generated-archives/.gitignore

@@ -1,6 +1,18 @@
+# Archives below are intentionally not tracked: each fixture script uses
+# host-only features (symlinks, FIFOs, or restrictive permissions) that cannot
+# be round-tripped through a tar archive across all platforms (notably Windows).
+# The scripts are re-run on the test host instead.
+
+# Uses `ln -sf` to create a symlink (`dir/sub-dir/symlink`).
 status_unchanged.tar
+# Same as above; also relies on a `chmod -x` toggle.
 status_changed.tar
+# Composed entirely of symlinks (including a symlink-to-base-dir).
 symlink_stack.tar
+# Uses `mkfifo`; FIFOs cannot be represented in archives extracted on Windows.
 status_nonfile.tar
+# Uses `ln -sf` plus installation-wide `core.autocrlf` line-ending normalization
+# on checkout.
 status_unchanged_filter.tar
+# Uses `chmod 000` on a tracked file; the unreadable mode is not portable.
 unreadable_untracked.tar

gix-url/tests/fixtures/generated-archives/.gitignore

@@ -1 +1,5 @@
+# The fixture captures `git-baseline.unix` and `git-baseline.windows`
+# files by piping a large set of URLs through `git fetch-pack --diag-url`. That
+# textual output may be sensitive to the git version, so the baseline must be
+# produced by the host's `git` to keep the comparison meaningful.
 make_baseline.tar

gix-worktree-state/tests/fixtures/generated-archives/.gitignore

@@ -1,7 +1,26 @@
+# Archives below are intentionally not tracked. The fixtures bake output from
+# the host's `git` binary, use filesystem-specific features (case sensitivity,
+# symlinks), or rely on filter drivers — none of which round-trip through a
+# committed tar across all supported platforms.
+
+# Shares its script with `gix-worktree`; bakes `git check-ignore` baseline
+# output that may depend on the host git version.
 make_ignore_and_attributes_setup.tar
+# Uses `ln -sf` to create a symlink in the working tree.
 make_mixed_without_submodules.tar
+# Uses `ln -sf` and adds a submodule; submodule .git/modules paths embed the
+# host absolute path of the parent worktree.
 make_mixed.tar
+# Despite its name, configures a `filter=arrow` clean filter whose effect on
+# the working tree depends on the test driver being available at run time;
+# generating once per host avoids drift.
 make_mixed_without_submodules_and_symlinks.tar
+# Bakes `git check-attr` baseline output, which may vary by git version.
 make_attributes_baseline.tar
+# Constructs intentionally malicious symlinks (e.g., `FAKE-DIR`, `FAKE-FILE`);
+# these cannot be safely unpacked on every platform.
 make_dangerous_symlink.tar
+# Indexes multiple paths that differ only by case (e.g. `FILE_X`/`file_x`).
+# Checking such an archive out fails on case-insensitive filesystems
+# (default macOS, Windows), so the fixture must be (re)generated locally.
 make_ignorecase_collisions.tar

gix-worktree-stream/tests/fixtures/generated-archives/.gitignore

@@ -1 +1,4 @@
+# The fixture creates symlinks (`ln -s`) and registers a
+# `filter=arrow` filter driver. Symlinks cannot be unpacked on Windows without
+# elevated privileges, so the script is re-run on the test host instead.
 basic.tar

gix-worktree/tests/fixtures/generated-archives/.gitignore

@@ -1,3 +1,13 @@
+# Archives below are intentionally not tracked. The fixtures bake output from
+# the host's `git` binary or use POSIX-only filesystem features that cannot be
+# round-tripped through a committed tar across all supported platforms.
+
+# Bakes `git check-ignore -vn` baseline output and uses `core.excludesFile`
+# pointing at a file outside the repo; both may vary by git version and host
+# path.
 make_ignore_and_attributes_setup.tar
+# Bakes `git check-attr` baseline output, which may vary by git version.
 make_attributes_baseline.tar
+# Uses `ln -s` (including a symlink to the base directory); symlinks do not
+# unpack on Windows without elevated privileges.
 symlink_stack.tar

gix/tests/fixtures/generated-archives/.gitignore

@@ -1,12 +1,43 @@
+# Archives below are intentionally not tracked. Each fixture creates state
+# whose contents depend on the host's working directory or installed `git`
+# binary (linked worktrees that bake absolute paths, alternates pointing at
+# `$PWD`, submodules with embedded host paths, host-only filesystem features,
+# or shallow/promisor metadata produced by the host `git`). Re-running the
+# script per host produces the values the test code expects.
+
+# `git worktree add` writes absolute paths into `.git/worktrees/<name>/gitdir`
+# and the worktree's `.git` pointer file; both shared with the `_bare` variant.
 /make_worktree_repo.tar
 /make_worktree_repo_bare.tar
+# Same as above, plus per-worktree config created via `extensions.worktreeConfig`.
 /make_worktree_repo_with_configs.tar
+# `git clone --shared file://$PWD/base` records the host-absolute alternates
+# path; numerous sub-clones inherit that reference.
 /make_remote_repos.tar
+# Shallow clone created with `file://$remote`; `.git/shallow` and the alternates
+# record the host path of the source repo (this is the fixture called out in
+# issue #2316 / PR #2229 as a candidate for future commitment if those host
+# paths can be removed).
 /make_complex_shallow_repo.tar
+# Clones from a host-supplied base repo path (`$1`); the resulting alternates
+# embed that absolute path.
 /make_fetch_repos.tar
+# Sets `core.worktree` to `$PWD/worktree` (an absolute path) on multiple
+# clones to test relative-vs-absolute worktree resolution.
 /make_core_worktree_repo.tar
+# Writes `global.config`/`system.config` files whose absolute paths the test
+# injects via `GIT_CONFIG_GLOBAL`/`GIT_CONFIG_SYSTEM`; the path layout must
+# match the host running the test.
 /make_signatures_repo.tar
+# Reads tree blobs/messages from `$ROOT/assets/...` (a host-absolute path) via
+# `git update-index --index-info` to build commits.
 /make_diff_repos.tar
+# `git submodule add` with relative path produces `.git/modules/<name>/config`
+# entries containing host-absolute worktree paths; also adds a worktree.
 /make_submodule_with_worktree.tar
+# Uses `mkfifo`, `ln -s`, executable-bit changes, and adds a submodule —
+# none of which round-trip cleanly through a committed tar across platforms.
 /repo_with_untracked_files.tar
-/make_worktree_repo_with_info_exclude.tar
+# Adds a linked worktree (host-absolute paths in `.git/worktrees/<name>/gitdir`)
+# alongside `.git/info/exclude` content.
+/make_worktree_repo_with_info_exclude.tar