task md:lint corrupts the .github/copilot-instructions.md symlink on Windows
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 1/5
- 预计耗时
- 1 小时以内
- 新手友好度
- 88/100
- Issue 类型
- 缺陷
- 描述清晰度
- 描述清楚
- 活跃度
- 冷清
- 技术栈
- markdown, yaml
- 领域
- tooling
调研方向
打开 .github/linters/.markdownlint-cli2.yaml，结合已记录的 task md:lint 工作流检查 ignore 模式。如果可以，复现 Windows 行为，然后验证 task md:lint 不再修改 .github/copilot-instructions.md，并且符号链接的目标保持不变。
由索引模型根据 Issue 内容生成。
描述
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.
- 主要语言
- Go
- 星标
- 66
- 派生
- 11
- 平均合并
- 2 天 10 小时
- 30 天内合并 PR
- 8
环境准备
在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。
- 没有 Dockerfile 或 Docker Compose 文件
- 没有 Pull Request 模板
- 没有贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
Azure/mpf 的其他 Issue
-
CreateUpdateCustomRole returns nil after exhausting its retry budget, reporting success when the role was never updated可能已有人在做 关联的 PR 仍在进行中或已合并。 未关闭bug
难度 2/5 1-3 小时 新手友好度 76/100
维护者通常 1 天内回复
-
govulncheck
难度 3/5 1-2 天 新手友好度 58/100
维护者通常 1 天内回复
-
难度 5/5 一周以上 新手友好度 35/100
维护者通常 1 天内回复
-
E2E Tests: Intermittent TestTerraformModuleTest failures due to stale RBAC permissions from previous test可能已有人在做 @maniSbindra 于 245 天前认领。 未关闭bug
Azure/mpf#231 · 6 条评论 · 1 个 reaction · 已指派 2 人 ·
维护者通常 1 天内回复
-
Add optional flag which does not destroy the resources created including the custom role definition可能重新可做 关联的 PR 已关闭且未合并。 未关闭enhancement terraform
Azure/mpf#84 · 1 个 reaction · 已指派 1 人 ·
维护者通常 1 天内回复
相似的 Issue
-
[Bug]: Anthropic Responses converter forwards empty text blocks, upstream rejects with 400可能已有人在做 @david-choi-querypie 今天认领。 未关闭
难度 2/5 1-3 小时 新手友好度 76/100
维护者通常 1 天内回复
-
area:web p3
难度 2/5 1-3 小时 新手友好度 72/100
Lets-Parley/Parley#912 ·
维护者通常 1 天内回复
-
bug observability
难度 2/5 1-3 小时 新手友好度 86/100
sagar2395/snowopslabs#164 ·
维护者通常 1 天内回复
-
enhancement help wanted
难度 2/5 1-3 小时 新手友好度 76/100
Git-Hospital/githealthcheck#61 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 78/100
afreidah/s3-orchestrator#1824 ·
维护者通常 1 天内回复