Wiedii — Política de Configuración Cross-Platform

Todo repositorio debe tener .gitignore, .gitattributes y .editorconfig configurados para compatibilidad entre plataformas (Windows, Linux, macOS).

---

.gitignore

Combinar los templates oficiales de github/gitignore sin modificar su contenido interno. Cada sección se identifica con su fuente.

Estructura de secciones (en este orden)

1. Template del stack

Stack	Template
Bun / Node.js	bun.gitignore
Python	Python.gitignore
Go	Go.gitignore
Java	Java.gitignore

Nota: Para proyectos Bun usar bun.gitignore, no Node.gitignore. Son diferentes.

2. Globales de herramientas del stack

Incluir los globales que correspondan a las herramientas que usa el proyecto:

Herramienta	Template
Lefthook	Global/Lefthook.gitignore
mise	Global/mise.gitignore

3. Globales de SO

Siempre incluir los tres:

• Global/macOS.gitignore
• Global/Windows.gitignore
• Global/Linux.gitignore

4. Globales de editores

Editor	Template	Notas
VS Code	Global/VisualStudioCode.gitignore	Usa whitelist — permite compartir settings.json, tasks.json, launch.json, extensions.json, *.code-snippets
JetBrains	Global/JetBrains.gitignore	Template completo con 30+ patrones por plugin/IDE

No usar .vscode/ ni .idea/ como entradas manuales — los templates oficiales son más completos y correctos.

5. Globales de seguridad y archivos

Template	Qué cubre
Global/GPG.gitignore	secring.* — claves GPG privadas
Global/Backup.gitignore	*.bak, *.tmp, *.orig, etc.
Global/Diff.gitignore	*.patch, *.diff

6. Project-specific

Al final del archivo, solo entradas que no cubre ningún template oficial:

### Project-specific ###
.claude/
graphify-out/

Formato del archivo

Cada sección debe identificar su fuente:

### Bun — github/gitignore/bun.gitignore ###
<contenido del template sin modificar>

### Lefthook — github/gitignore/Global/Lefthook.gitignore ###
<contenido del template sin modificar>

### mise — github/gitignore/Global/mise.gitignore ###
<contenido del template sin modificar>

### macOS — github/gitignore/Global/macOS.gitignore ###
...

### Project-specific ###
...

---

.gitattributes

Usar los templates oficiales de gitattributes/gitattributes.

Template base

Common.gitattributes — base para todos los proyectos. Cubre documentos, gráficos, scripts, serialización (JSON, TOML, YAML, XML), archivos comprimidos y exclusiones de export.

La regla global debe forzar siempre LF:

*    text=auto eol=lf

Template de editor

Global/VisualStudioCode.gitattributes — linguist hints para archivos JSON-with-Comments de VS Code:

.vscode/*.json linguist-language=JSON-with-Comments

Reglas explícitas adicionales (project-specific)

Common.gitattributes no cubre algunos archivos comunes. Agregarlos explícitamente:

# Project-specific
# Explicit rules for files not covered by Common.gitattributes
.editorconfig  text eol=lf
.gitattributes text eol=lf
.gitignore     text eol=lf

# Lockfiles — a prueba de merge (sin corrupción) + colapsados pero expandibles en diffs
bun.lock       text eol=lf -merge gitlab-generated linguist-generated linguist-language=JSON
bun.lockb      binary
mise.lock      text eol=lf -merge gitlab-generated linguist-generated linguist-language=TOML

bun.lock — formato texto JSON desde Bun 1.1+. No es binario como bun.lockb (formato legacy). mise.lock — formato TOML autogenerado por mise lock.

⚠️ merge y diff son atributos INDEPENDIENTES (git docs). Confundirlos es un error común — el macro binary agrupa ambos (-diff -merge -text), de ahí la confusión.

Evitar conflictos de merge → -merge (NO -diff)

Los lockfiles son autogenerados; no se editan a mano y no deberían producir conflictos de contenido (a diferencia de package.json, que sí). El atributo que logra esto es -merge: cuando dos ramas modifican el lockfile, git mantiene la versión "ours" y marca conflicto sin inyectar marcadores <<<<<< ====== >>>>>> (que corromperían el JSON/TOML). Se resuelve regenerando: bun install / mise install, luego git add.

❌ -diff no hace esto. -diff solo controla la visualización (marca el archivo como binario para diffs): git emite "Binary files differ", GitLab muestra el mensaje engañoso de "Archivo eliminado por una entrada de .gitattributes", y el lockfile nunca se puede inspeccionar (impide auditar dependencias — riesgo de supply-chain). Y encima no protege contra conflictos de merge. Usar -merge para eso, nunca -diff.

Colapsar el diff pero dejarlo expandible → gitlab-generated + linguist-generated

gitlab-generated lo honra GitLab (GA desde 16.11): colapsa el diff por defecto pero lo deja expandible cuando el reviewer necesita auditarlo. Se acompaña de linguist-generated para paridad si el repo se espeja a GitHub (GitLab no honra linguist-generated para colapsar; solo GitHub lo hace). linguist-language mantiene el resaltado al expandir.

Validación

El repo gitattributes/gitattributes incluye check.sh para verificar que todos los archivos del repo tengan una regla explícita (no solo el catch-all *):

curl -s https://raw.githubusercontent.com/gitattributes/gitattributes/master/check.sh | sh

Correr después de modificar .gitattributes. Si algún archivo reporta text: auto, agregar una regla explícita para él.

Al agregar .gitattributes a un repo existente

git add --renormalize .
git commit -m "chore: normalize line endings with .gitattributes"

---

.editorconfig (requerido en todos los repos)

root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.md]
trim_trailing_whitespace = false

[*.py]
indent_size = 4

---

Referencias

• github/gitignore — templates oficiales de gitignore
• gitattributes/gitattributes — templates oficiales de gitattributes
• repo-setup — checklist de nuevo repositorio
• wiedii-configs — repo de configuraciones compartidas donde se implementó esta política