.gitattributes

# Line endings the tooling depends on.
#
# EVERYTHING IS LF UNLESS A LATER RULE SAYS OTHERWISE. This file used to name
# only the trees whose bytes are hashed, which left every other text file at the
# mercy of the checker-out's core.autocrlf - and that is not a cosmetic
# difference here, for three reasons:
#
#   1. A DISTRIBUTION ships text files that are compared by hash. The
#      distributer records a sha256 per shipped file and the release publishes
#      SHA256SUMS.txt, so "the zip you downloaded" and "the commit it came from"
#      have to agree byte for byte. With autocrlf=true a fresh Windows checkout
#      materialised 177 of these files as CRLF, so a recipient verifying a file
#      against the repository would see a difference that is not a difference.
#   2. Every pinned tree below is pinned for exactly this reason already, and
#      those local rules cannot help a file nobody named.
#   3. LF is what the repository STORES either way - git normalises on commit -
#      so this rule only stops the checkout from disagreeing with the commit.
#
# The batch and cmd files are the deliberate exception, and because the LAST
# matching rule wins, their `eol=crlf` lines sit BELOW this one on purpose.
* text=auto eol=lf

# A CRLF shebang breaks `./install.sh` on macOS/Linux, so shell scripts are
# pinned to LF no matter which OS checks the repo out. (Kept explicit even
# though the catch-all above already covers it: it is the rule that must not be
# lost if the catch-all is ever narrowed.)
*.sh text eol=lf

# Batch files are the Windows launchers; CRLF is what cmd.exe expects. *.cmd is
# listed for the same reason: scripts/console/adapt.cmd is the `call`ed console
# helper every entry point shares, and a launcher whose line endings depend on
# who checked it out is a launcher that works on one machine.
*.bat text eol=crlf
*.cmd text eol=crlf

# The forked browser bundles are GENERATED and byte-compared by
# scripts/sync-vendored.ps1 (-Check hashes the working copy). With git's
# autocrlf the Windows checkout would rewrite them to CRLF and report phantom
# drift, so they are pinned to LF too.
packages/*/lib/client.js text eol=lf

# The vendored pdf.js tree is GENERATED and byte-hashed by
# packages/dsh-pdf/vendor/build.mjs --check (every file's sha256 plus a digest
# over each tree, recorded in lib/vendor/VERSION.json), so its TEXT files are
# pinned to LF for exactly the reason the forked bundles above are: a Windows
# checkout would rewrite them to CRLF and report phantom drift - and the LICENSE
# files live INSIDE the hashed cMap, standard-font and wasm trees, so converting
# them would change a tree digest too. The .bcmap, .pfb/.ttf and .wasm binaries
# are detected as binary and are never touched.
packages/dsh-pdf/lib/vendor/*.mjs text eol=lf
packages/dsh-pdf/lib/vendor/VERSION.json text eol=lf
packages/dsh-pdf/lib/vendor/LICENSE text eol=lf
packages/dsh-pdf/lib/vendor/cmaps/LICENSE text eol=lf
packages/dsh-pdf/lib/vendor/standard_fonts/LICENSE_* text eol=lf
packages/dsh-pdf/lib/vendor/wasm/LICENSE_* text eol=lf
packages/dsh-pdf/lib/vendor/wasm/*.js text eol=lf

# The vendored Diagram Design kit is GENERATED and byte-hashed by
# packages/dsh-diagrams/vendor/design/build.mjs --check (every file's sha256, plus
# the motion controller's, recorded in lib/vendor/design/VERSION.json).
#
# `-text`, not `text eol=lf`, and the difference matters. The kit's own build
# normalizes the tree to LF (7 upstream examples were committed CRLF) and records
# the LF bytes, so what is stored is already LF; `-text` then tells git to leave
# the tree COMPLETELY alone in both directions, and the bytes on disk are the
# bytes in the commit on every platform. `text eol=lf` would instead ask git to
# normalize on the way IN - rewriting the very bytes the manifest records - and
# the working tree would no longer match its own manifest until the next build.
# The tree is 277 HTML/Markdown/Python files, so there is no binary inside it to
# protect with the usual reason for this attribute.
packages/dsh-diagrams/lib/vendor/design/** -text

# The same treatment for the vendored Mermaid engine: it is one GENERATED 3.4 MB
# file whose sha256 is recorded in lib/vendor/VERSION.json and re-computed by the
# tracked route check, so its bytes must survive a checkout unchanged.
packages/dsh-diagrams/lib/vendor/mermaid.min.js -text