.gitattributes

# ============================================================
# .gitattributes (ALL-REPOS)
# ============================================================
# Updated: 2026-10-11
#
# WHAT: A Git configuration file that defines how Git handles project files.
#       It identifies text and binary files, controls line endings,
#       and influences how Git compares and merges files.
#
# WHEN: Use in professional projects where files are shared through Git,
#       particularly across Windows, macOS, and Linux.
#
# WHY: Different operating systems and development tools may handle files
#      differently. Inconsistent line endings can create unnecessary
#      Git changes, complicate code reviews, and cause execution problems.
#      Binary files also require different handling than text files.
#      Shared Git attributes help maintain consistent repository contents
#      and make changes easier to review and reproduce.
#
# HOW: Git reads this file when adding, checking out, comparing, or merging
#      project files. General rules apply unless more specific rules exist.
#      Text files normally use LF line endings, while binary files are
#      preserved without text conversion.
#
# SKILLS: Git, Git attributes, line endings, text and binary files,
#         cross-platform development, version control, and collaboration.
#
# TOOLS: Git uses .gitattributes to control file handling.
#        .editorconfig guides editors when creating and editing files.
#        Both support consistent formatting across development environments.
#
# REQ: Professional GitHub repositories SHOULD include .gitattributes.
# REQ: The filename MUST be exactly .gitattributes.
#
# OBS: .editorconfig and .gitattributes serve complementary purposes.
#      .editorconfig establishes editor formatting conventions.
#      .gitattributes establishes Git's rules for handling tracked files.
#      Neither replaces the other.
#
# CUSTOM: Add repository-specific rules when files require different handling.
#
# SEE: https://git-scm.com/docs/gitattributes
# ============================================================


# === Core defaults ===

# WHY: Auto-detect text files and normalize text to LF unless a later rule
# is more specific.
* text=auto eol=lf


# === Named root and metadata files ===

# WHY: Important repository metadata files are text and should use LF.
.gitattributes   text eol=lf
.gitignore       text eol=lf
.editorconfig    text eol=lf
.python-version  text eol=lf
CODEOWNERS       text eol=lf
LICENSE          text eol=lf
uv.lock          text eol=lf


# === Operating-system files ===

# WHY: OS metadata files are binary/noisy and should not be normalized or diffed.
.DS_Store    binary
Thumbs.db    binary
desktop.ini  binary


# === Markup and documentation ===

# WHY: Documentation, web, and math markup use LF for stable cross-platform diffs.
*.bib   text eol=lf
*.cff   text eol=lf
*.cls   text eol=lf
*.css   text eol=lf
*.html  text eol=lf
*.md    text eol=lf
*.qmd   text eol=lf
*.rst   text eol=lf
*.sty   text eol=lf
*.tex   text eol=lf
*.typ   text eol=lf
*.xml   text eol=lf


# === Configuration and structured text ===

# WHY: Configuration and structured text files should produce stable diffs.
*.cfg     text eol=lf
*.env     text eol=lf
*.ini     text eol=lf
*.json    text eol=lf
*.jsonc   text eol=lf
*.jsonl   text eol=lf
*.ndjson  text eol=lf
*.toml    text eol=lf
*.txt     text eol=lf
*.yaml    text eol=lf
*.yml     text eol=lf


# === Programming languages and scripts ===

# WHY: Source and script files use LF for CI, shells, containers, and tooling.
*.c     text eol=lf
*.cpp   text eol=lf
*.cs    text eol=lf
*.go    text eol=lf
*.h     text eol=lf
*.hpp   text eol=lf
*.java  text eol=lf
*.jl    text eol=lf
*.js    text eol=lf
*.jsx   text eol=lf
*.mjs   text eol=lf
*.cjs   text eol=lf
*.mojo  text eol=lf
*.ps1   text eol=lf
*.py    text eol=lf
*.pyi   text eol=lf
*.r     text eol=lf
*.R     text eol=lf
*.rs    text eol=lf
*.sh    text eol=lf
*.sql   text eol=lf
*.ts    text eol=lf
*.tsx   text eol=lf

# WHY: Windows batch scripts conventionally use CRLF and may be consumed by
# Windows tooling that expects Windows-style line endings.
*.bat  text eol=crlf
*.cmd  text eol=crlf


# === Formal, math, and proof languages ===

# WHY: Lean source files are text; Lean build artifacts are binary.
*.ilean  binary
*.lean   text eol=lf
*.olean  binary
*.trace  binary

# WHY: Lake build output should not be normalized if accidentally tracked.
.lake/**  binary


# === Notebooks ===

# WHY: Jupyter notebooks are JSON-based text files and benefit from stable
# cross-platform line endings.
*.ipynb  text eol=lf


# === Text and tabular data ===

# WHY: Small text data files benefit from readable diffs.
*.csv  text eol=lf
*.dat  text eol=lf
*.psv  text eol=lf
*.tsv  text eol=lf


# === Images and web binary assets ===

# WHY: Image and compiled web asset formats are binary; text diffs are not meaningful.
*.avif   binary
*.bmp    binary
*.gif    binary
*.ico    binary
*.jpeg   binary
*.jpg    binary
*.png    binary
*.webp   binary
*.wasm   binary

# WHY: SVG is XML-based text and benefits from readable diffs.
*.svg  text eol=lf


# === Databases ===

# WHY: Database files are binary; text diffs are not meaningful.
*.db       binary
*.duckdb   binary
*.sqlite   binary
*.sqlite3  binary


# === Columnar and analytical data ===

# WHY: Columnar and analytical formats are binary; text diffs are not meaningful.
*.arrow    binary
*.avro     binary
*.feather  binary
*.orc      binary
*.parquet  binary


# === Office, BI, PDF, and compressed artifacts ===

# WHY: Office, BI, PDF, and archive files are binary.
*.7z    binary
*.bz2   binary
*.doc   binary
*.docx  binary
*.gz    binary
*.odp   binary
*.ods   binary
*.odt   binary
*.pbix  binary
*.pbit  binary
*.pdf   binary
*.ppt   binary
*.pptx  binary
*.rar   binary
*.tar   binary
*.tgz   binary
*.xls   binary
*.xlsm  binary
*.xlsx  binary
*.xz    binary
*.zip   binary


# === Logs and generated runtime output ===

# WHY: Logs are text when intentionally committed and should remain readable
# and diffable.
# NOTE: Most logs are ignored by .gitignore. Repository-specific research
# evidence may override text normalization with -text when exact bytes matter.
*.log  text eol=lf


# === GitHub metadata and UI ===

# WHY: Exclude documentation and tests from GitHub language statistics.
docs/**   linguist-documentation
tests/**  linguist-documentation