task md:lint corrupts the .github/copilot-instructions.md symlink on Windows
Nadie ha tomado este issue todavía.
Evaluación
- Dificultad
- 1/5
- Tiempo estimado
- Menos de una hora
- Aptitud para principiantes
- 88/100
- Tipo de issue
- Error
- Claridad
- Bien especificado
- Estado de actividad
- Tranquilo
- Stack tecnológico
- markdown, yaml
- Área
- tooling
Línea de trabajo
Abre .github/linters/.markdownlint-cli2.yaml y revisa los patrones de exclusión junto con el flujo de trabajo documentado de task md:lint. Reproduce el comportamiento de Windows si es posible y, después, verifica que task md:lint ya no modifique .github/copilot-instructions.md y que el destino del enlace simbólico permanezca sin cambios.
Escrito por el modelo de indexación a partir del texto del issue.
Descripción
What happened
Running the documented task md:lint on Windows modifies .github/copilot-instructions.md, which is a symlink to ../AGENTS.md. Committing that change would replace the symlink with a broken target path and silently detach the repository's Copilot instructions from AGENTS.md.
Why it happens
.github/copilot-instructions.md is stored as a symlink (mode 120000) whose blob content is the literal string ../AGENTS.md with no trailing newline.
Git for Windows defaults to core.symlinks=false. Under that setting the entry is checked out as a plain text file containing the target path rather than a real symlink. markdownlint-cli2 then sees an ordinary .md file that does not end in a newline and "fixes" it:
.github/copilot-instructions.md:1:12 error MD047/single-trailing-newline Files should end with a single newline character
The resulting diff against a clean tree:
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index be77ac8..6afa560 120000
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1 +1 @@
-../AGENTS.md
\ No newline at end of file
+../AGENTS.md
The mode stays 120000, so the entry is still a symlink as far as Git is concerned, but its target becomes "../AGENTS.md\n" — a path that does not exist.
Reproduction
On Windows with core.symlinks=false (the default):
git clone https://github.com/Azure/mpf.git
cd mpf
task md:tools
task md:lint
git status --short # M .github/copilot-instructions.md
Isolated to confirm which tool is responsible:
task md:run:markdownlint-cli2:fix --force
git status --short # M .github/copilot-instructions.md
markdown-table-formatter does not touch the file. markdownlint-cli2 is the one that rewrites it.
Why it is easy to miss
The change is a single invisible trailing newline in a one line file. Anyone who runs the documented lint task and then stages with git add -A or git commit -a will pick it up without noticing, and the diff looks harmless in review. I hit this while fixing an unrelated markdown table in #314 and only caught it because the file was outside the scope of my change.
Suggested fix
Exclude the symlink from linting in .github/linters/.markdownlint-cli2.yaml:
ignores:
- .git
- "**/node_modules/**"
- .copilot-tracking/**
- venv/**
- .venv/**
- .github/copilot-instructions.md
That keeps the current symlink layout, which is nice because AGENTS.md stays the single source of truth.
Alternatives, if you would prefer not to special case a path:
- Disable
MD047for that file via an inline configuration comment, though that is awkward since any content added to a symlink defeats its purpose. - Replace the symlink with a small stub file that points readers at
AGENTS.md, avoiding symlink portability issues altogether at the cost of duplication.
The ignore entry seems like the smallest change.
Environment
- Windows, Git for Windows with
core.symlinks=false markdownlint-cli2v0.23.1 (markdownlint v0.41.1), as pinned bytask md:install:markdownlint-cli2mainas of 2026-07-27
This is not specific to my checkout. Any Windows contributor with default Git settings who runs the documented lint task will reproduce it.
- Lenguaje dominante
- Go
- Estrellas
- 66
- Forks
- 11
- Merge medio
- 2 h 7 min
- PR fusionados (30 d)
- 5
Preparar el entorno
Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.
- Sin Dockerfile ni archivo de Docker Compose
- Sin plantilla de pull request
- Sin guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Más de Azure/mpf
-
CreateUpdateCustomRole returns nil after exhausting its retry budget, reporting success when the role was never updatedPosiblemente ocupada Un pull request vinculado a esta issue está abierto o ya se fusionó. Abiertobug
Dificultad 2/5 1-3 horas Aptitud para principiantes 76/100
-
Dificultad 5/5 Más de una semana Aptitud para principiantes 35/100
-
E2E Tests: Intermittent TestTerraformModuleTest failures due to stale RBAC permissions from previous testPosiblemente ocupada @maniSbindra la tomó hace 224 días. Abiertobug
-
Add optional flag which does not destroy the resources created including the custom role definitionQuizá libre de nuevo Un pull request para esta issue se cerró sin fusionarse. Abiertoenhancement terraform
-
For Terraform azurerm provider resources which use LRO polling add RESOURCE_TYPE/operationStatuses/read permissionsPosiblemente ocupada @bgdnext64 la tomó hace 72 días. Abiertoenhancement terraform
Issues similares
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 76/100
evilmartians/lefthook#1588 ·
Los mantenedores suelen responder en 1 día
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 85/100
kubernetes-sigs/kubebuilder#6084 ·
Los mantenedores suelen responder en 3 días
-
agent-research-recommend agent-review-finding chore
Dificultad 2/5 1-3 horas Aptitud para principiantes 78/100
jordansmall/spindrift#4821 · 1 comentario ·
Los mantenedores suelen responder en 1 día
-
area:web
Dificultad 2/5 1-3 horas Aptitud para principiantes 82/100
praetorianer777/GoTome#178 ·
Los mantenedores suelen responder en 1 día
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 70/100
oracle/go-oracledb#105 ·
Los mantenedores suelen responder en 1 día