如何用 GitHub Linguist 为现有语言添加新的文件扩展名并提交 PR【免费下载链接】linguistLanguage Savant. If your repositorys language is being reported incorrectly, send us a pull request!项目地址: https://gitcode.com/GitHub_Trending/li/linguist当仓库的语言统计不符合预期或某类重要文件没有被识别为对应语言时一个常见原因是该语言在 Linguist 中缺少你正在使用的文件扩展名。要正式把这个扩展名加进某门语言需要按照 Linguist 的贡献指南 完成一条固定路径修改 languages.yml 中的语言定义、在 samples 目录补充样例、本地验证再提交 pull request。本文覆盖这条完整操作路径从环境搭建一直讲到 PR 合并后变更何时出现在 GitHub 上。先确认扩展名是否满足使用量要求动手之前先确认扩展名能否被接受。Linguist 只接纳在公开 GitHub 仓库中有足够真实使用量的新扩展名非常新或纯兴趣向语言的 PR 会被直接关闭。文档给出的使用量标准是对于预期在单个仓库中出现多次的扩展名如 Ruby 的.rb近一年被 GitHub Search 索引的文件数至少 2000 个即搜索结果顶部的数字不含 forks对于预期只在每个仓库中出现一次的扩展名或文件名如Makefile近一年至少 200 个文件不含 forks结果应在不同的:user/:repo组合间有合理分布需要手动随机抽查判断如果某个用户例如语言的主要作者占比过高用-user:username过滤后重新评估。评估依据是 GitHub Search 的结果项目文档同时提示 GitHub Search 对索引范围本身有限制。这条搜索查询是 PR 模板的必填项用来佐证扩展名在真实项目中被使用所以建议先拿到搜索结果再开始改代码。搭建贡献环境文档提供了三种环境搭建方式推荐首选 GitHub Codespaces它提供预配置好的一致性环境且免额外设置。下面给出其余两种可用路径。方式一本地 dev container按 VS Code Dev Containers 的官方说明安装好容器支持后用 VS Code 打开 linguist 仓库。VS Code 会自动提议在 dev container 中运行该项目接受即可不需要其他设置。方式二纯本地系统这是步骤最多的一种。Linguist 是 Ruby 库需要一个较新版本的 Ruby文档特别指出 macOS/Xcode 自带的 Ruby 在安装依赖时有已知问题建议改用 Homebrew、rbenv、rvm、ruby-build、asdf等方式安装 Ruby。其余依赖包括charlock_holmes字符编码检测库底层依赖 ICU和ruggedRuby 的 libgit2 绑定Bundler v1.10.0 或更高版本Docker——文档说明它在添加或更新语法高亮 grammar 时才必需仅添加文件扩展名不涉及 grammaricu4c、cmake、pkg-config等底层组件可能需要先安装。在 Ubuntu 上一条命令即可装齐apt-get install cmake pkg-config libicu-dev docker.io ruby ruby-dev zlib1g-dev build-essential libssl-devBundler 用gem install bundler安装最新版。装完依赖后克隆仓库并运行 bootstrap 脚本安装项目依赖git clone https://gitcode.com/GitHub_Trending/li/linguist cd linguist/ script/bootstrap环境是否就绪可以用下面的命令验证——从克隆出的仓库直接运行 Linguist 并输出语言分布bundle exec bin/github-linguist --breakdown在 languages.yml 中添加扩展名语言定义都集中在 languages.yml。找到目标语言的条目把新扩展名加进它的extensions列表。文档明确了排序规则扩展名按字母序排列排序区分大小写大写排在小写前面唯一的例外是主扩展名列表中的第一个它必须始终放在第一位。仓库中一个现成的条目可以作格式参照languages.yml 中的 Futhark 语言节选Futhark: type: programming color: #5f021f extensions: - .fut tm_scope: source.futhark ace_mode: text language_id: 97358117添加新扩展名时只需在extensions列表的合适位置插入一行例如- .yourextension不要改动language_id、tm_scope等其他字段。添加样例文件在 samples 目录下对应语言的子目录中至少添加一个该扩展名的样例文件。比如仓库里samples/Futhark/gaussian_blur.fut就是 Futhark 语言的样例。文档对样例的要求是优先提供展示常见用法的真实世界代码越贴近该语言的实际结构越好“Hello world” 之类教程示例不会被接受。如果新扩展名已经列在languages.yml中并关联到另一门语言还需要多做两步确保samples目录下每个使用该扩展名的语言至少有两个该扩展名的示例文件如果两门语言看起来有些相似或其中一门有可辨识的特征考虑编写一条 heuristic 帮助分类避免误判。文档强调这一步的目标是避免 false positives误报。本地验证贡献指南提供了两个本地测试命令bundle exec rake test bundle exec script/cross-validation --test第二条用于本地测试语言分类器。如果 Ruby 经验不多、跑测试本身成本太高文档也说明可以直接开 PR让 GitHub Actions 替你跑测试。提交 pull request提交 PR 时内容必须包含一条指向 GitHub 搜索结果的链接展示该扩展名在真实项目中的使用这也是 PR 模板要求的查询明确声明样例代码所覆盖的许可证能直接链接到样例的原始来源更好如果样例是你为这个 PR 专门编写的可以改为声明你愿意让它以 Linguist 所采用的 MIT 许可证收录。文档明确警告不使用或未填写 PR 模板的 pull request 不会被审查。合并之后变更何时出现在 GitHubPR 合并不等于立刻在 GitHub 生效。根据 troubleshooting 文档Linguist 的变更要等到新版本发布并部署到 GitHub.com 之后才会体现发布没有固定时间表目标是每三到四个月至少一次。另外GitHub 搜索的语言检测使用一个独立的内部库通常会滞后 Linguist 数周到数月所以新扩展名在搜索结果中生效的时间会比语言统计条更晚。【免费下载链接】linguistLanguage Savant. If your repositorys language is being reported incorrectly, send us a pull request!项目地址: https://gitcode.com/GitHub_Trending/li/linguist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考