# ============================================================
# .gitignore (ALL-REPOS)
# ============================================================
# Updated: 2026-09-25
#
# REQ: All professional GitHub project repositories MUST include .gitignore.
# WHY: Keep generated artifacts, local state, secrets, temporary files,
# machine-specific files, and reproducible build output out of the repository.
# ALT: Repository may customize ignores, but MUST preserve universal safety rules.
#
# ============================================================
# === How .gitignore patterns work ===
# ============================================================
# NOTE: .gitignore uses glob-style patterns, not regular expressions.
#
# /name
# WHY: A leading slash anchors the pattern to the directory containing this
# .gitignore file. In a repository-root .gitignore, /name matches only name
# at the repository root.
# EXAMPLE: /pyproject.toml.ruff ignores only the root-level temporary fragment.
#
# name/
# WHY: A trailing slash means the pattern matches directories, not files.
# EXAMPLE: bin/ ignores directories named bin and their contents.
#
# *.ext
# WHY: An asterisk (*) matches any number of characters within one path component.
# EXAMPLE: *.log ignores files ending in .log.
#
# **
# WHY: A double asterisk (**) can match across directory levels.
# EXAMPLE: **/src/**/_version.py matches generated _version.py files inside
# src trees regardless of repository depth or package name.
#
# ?
# WHY: A question mark (?) matches exactly one character within a path component.
# EXAMPLE: temp?.txt matches temp1.txt and tempa.txt, but not temp10.txt.
#
# [abc]
# WHY: Square brackets match one character from the listed set or range.
# EXAMPLE: file[0-9].txt matches file0.txt through file9.txt.
#
# !pattern
# WHY: An exclamation point (!) negates an earlier ignore rule and re-includes
# a matching file when its parent directory has not itself been excluded.
# EXAMPLE: !.env.example keeps the safe example file even though .env.* is ignored.
#
# # text
# WHY: A leading # makes the line a comment unless the # is escaped.
#
# NOTE: Prefer the narrowest pattern that expresses the intent.
# Anchored patterns such as /name are safer when
# only a repository-root file should be ignored.
# ============================================================


# === Generated files for supported repositories ===

# WHY: Generated analytics and guide-context artifacts should be rebuilt rather
# than committed.
# NOTE: These entries are harmless in repositories that do not generate them.
docs/assets/data/view-analytics.json
docs/assets/data/guide-context.json
# marimo WASM export; built at deploy time, not committed
docs/app/


# === Environment variables and secrets ===

# WHY: Never commit credentials or environment-specific configuration.
*.env
.env
.env.*

# WHY: Commit .env.example as a safe template showing which variables to set.
# NOTE: Copy .env.example to .env locally and customize the local copy.
!.env.example


# === Private notes and local-only files ===

# WHY: Private working notes should remain local unless intentionally published.
PRIVATE-NOTES.md
PRIVATE_NOTES.md

# WHY: The root-level refs directory holds local reference papers and source
# materials that should be cited or linked to rather than committed.
# NOTE: The leading slash limits this rule to the repository-root refs directory.
# ALT: Commit only reference material that is intentionally redistributable and
# appropriate to include in the repository.
/refs/


# === Operating-system files ===

# WHY: OS-generated metadata files are machine-specific and should not be tracked.
.AppleDouble
.DS_Store
.LSOverride
.Spotlight-V100/
.Trashes
._*
Icon\r
Thumbs.db
desktop.ini
ehthumbs.db


# === Editors and IDEs ===

# WHY: IDE metadata is generally machine-local and should not be tracked.
*.code-workspace
.idea/


# === VS Code ===

# WHY: Ignore editor state by default while allowing shared project configuration.
# NOTE: Use .vscode/* (contents), not .vscode/ (directory). Git will not
# re-include a file whose parent directory is excluded.
.vscode/*
!.vscode/ABOUT_THIS_FOLDER.md
!.vscode/extensions.json
!.vscode/settings.json
!.vscode/launch.json
!.vscode/tasks.json
!.vscode/*.code-snippets


# === Temporary, lock, and swap files ===

# WHY: Temporary and swap files are machine-local noise and create meaningless diffs.
*.swo
*.swp
*.tmp
*~

# WHY: Microsoft Office creates temporary owner/lock files beside open documents.
# NOTE: These patterns cover Word, Excel, and PowerPoint temporary files without
# ignoring the actual Office documents.
~$*.doc*
~$*.xls*
~$*.ppt*

# WHY: LibreOffice and OpenOffice create temporary lock files beside open documents.
.~lock.*#


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

# WHY: Ignore logs and runtime output by default.
# ALT: Explicitly re-include a specific log only when it is intentionally used
# as project evidence.
*.log
logs/
# !/project.log


# === Generic caches ===

# WHY: Generic caches are machine-local and should not be tracked.
.cache/


# === Generic bin (binary) folder ===

# WHY: The root-level bin directory contains generated executable or build output.
# NOTE: The leading slash limits this rule to the repository-root bin directory
# and avoids ignoring a nested source directory that happens to be named bin.
/bin/


# === Markup and documentation ===

# WHY: Static site build output is generated from the documentation source.
# NOTE: Zensical uses site/ as the generated site output directory.
site/


# === Python environments ===

# WHY: Virtual environments are machine-local and reproducible from project files.
.venv/
venv/


# === Python project state ===

# REQ: Do NOT git ignore .python-version.
# WHY: Commit .python-version to declare the Python version used by the project.

# REQ: Do NOT git ignore uv.lock.
# WHY: Commit uv.lock to preserve the resolved dependency environment and use it
# in CI/CD pipelines.

# WHY: Generated SCM version modules should not be tracked.
# NOTE: This recursive pattern works regardless of repository depth or package name.
**/src/**/_version.py


# === Python bytecode ===

# WHY: Python bytecode is generated automatically and is machine-specific.
*.pyc
*.pyd
*.pyo
__pycache__/


# === Python build and packaging artifacts ===

# WHY: Build and packaging artifacts are generated from project source.
*.egg
*.egg-info/
*.whl
.eggs/
build/
dist/


# === Python testing and coverage output ===

# WHY: Test and coverage reports are generated and can be reproduced.
.coverage
.coverage.*
.pytest_cache/
htmlcov/
coverage.xml
coverage.json
coverage.lcov


# === Python tooling caches ===

# WHY: Tooling caches improve local performance but should not be tracked.
.mypy_cache/
.pytype/
.ruff_cache/
.tox/


# === Notebooks and marimo ===

# WHY: Jupyter notebook checkpoint state is generated.
.ipynb_checkpoints/

# REQ: Do NOT git ignore layouts/ when using marimo custom layouts.
# WHY: Marimo layout files are project source and should be version controlled.

# REQ: Do NOT git ignore public/ when it contains source assets or data
# used by marimo or WASM applications.
# WHY: These files may be required to reproduce or publish the application.


# === Node dependencies ===

# WHY: Node dependencies are restored from package-lock.json with npm ci.
node_modules/

# REQ: Do NOT git ignore package-lock.json.
# WHY: Commit package-lock.json to preserve reproducible Node dependency
# resolution and use it in CI/CD pipelines.


# === Node package-manager caches ===

# WHY: Package-manager caches are machine-local and should not be tracked.
.npm/
.pnpm-store/
.yarn/cache/
.yarn/unplugged/
.yarn/build-state.yml
.yarn/install-state.gz


# === TypeScript and JavaScript build output ===

# WHY: Compiled JavaScript output is generated from TypeScript source.
out/

# WHY: TypeScript incremental build metadata is generated.
*.tsbuildinfo


# === TypeScript and JavaScript tooling caches ===

# WHY: Tooling caches and generated coverage output should not be tracked.
.eslintcache
.nyc_output/
coverage/


# === VS Code extension test and package output ===

# WHY: VS Code extension test-host files are generated by @vscode/test-electron.
.vscode-test/

# WHY: VSIX packages are generated release artifacts.
*.vsix


# === pup-up temporary fragments ===

# WHY: pup-up may provide temporary configuration fragments for manual merging.
# WHY: Ruff settings belong in the repository's authoritative pyproject.toml.
# NOTE: Remove this rule when pup-up directly reconciles the managed Ruff
# configuration in pyproject.toml and no longer creates this fragment.
/pyproject.toml.ruff
