GitHub Linguist 如何添加一种新语言languages.yml、语法与样本的完整流程【免费下载链接】linguistLanguage Savant. If your repositorys language is being reported incorrectly, send us a pull request!项目地址: https://gitcode.com/GitHub_Trending/li/linguist如果你的语言目前不被 GitHub 识别仓库语言统计栏里没有它或者你的扩展名被归到了别的语言下Linguist 官方给出的解决方式就是向 linguist 仓库提交一个 pull request走「languages.yml登记语言 添加高亮语法 补充样本代码」的完整流程。本文按 CONTRIBUTING.md 中 “Adding a language” 一节的实际操作路径展开先搭好开发环境再依次修改 lib/linguist/languages.yml、运行script/add-grammar引入 TextMate 兼容语法、在 samples/ 目录下放好真实代码样本、生成语言 ID最后通过测试并开 PR。开始之前有两个前提需要确认使用量门槛Linguist 只接受在公开 GitHub 仓库中有足够使用量的新语言非常新或纯兴趣型hobby语言会被直接关闭。CONTRIBUTING.md 给出的量化标准是每仓库会多次出现的扩展名如.rb要求近一年内被 GitHub Search 索引的文件数至少2000不含 fork每仓库只出现一次的文件名如Makefile要求近一年内至少200个文件不含 fork结果需要在不同的:user/:repo组合间分布合理如果某个用户比如语言作者本人占比过高评估时会用-user:username将其过滤后再看。这些证据要通过 PR 模板中要求的 GitHub 搜索链接提供且要留意 GitHub Search 本身对可索引内容的限制。语法许可证script/add-grammar只接受带有 CONTRIBUTING.md 所链接许可证列表 之一的高亮语法许可证不符的语法无法添加。准备开发环境Linguist 是 Ruby 库本地贡献需要较新版本的 Ruby。macOS/XCode 自带的 Ruby 安装依赖时已知有问题文档建议改用 Homebrew、rbenv、rvm、ruby-build、asdf等包管理方式安装。依赖方面见 CONTRIBUTING.md字符编码检测库charlock_holmes依赖 ICU即icu4crugged提供的 libgit2 绑定依赖cmake和pkg-config安装 gem 依赖需要 Bundler v1.10.0 或更新版本添加或更新语法时还需要 Docker。在 Ubuntu 上文档给出的系统依赖安装命令需要 root 权限会修改系统软件包是apt-get install cmake pkg-config libicu-dev docker.io ruby ruby-dev zlib1g-dev build-essential libssl-devmacOS 上则依赖 Getting started 步骤里的script/bootstrap自动处理。环境搭建有三种方式GitHub Codespaces文档推荐开箱即用、本地 VS Code dev container打开仓库后 VS Code 会提示在容器内运行无需额外配置、或直接在本地系统安装。本文按本地系统方式写。克隆仓库并运行script/bootstrap安装依赖。script/bootstrap的作用见 script/bootstrap在 macOS 上自动执行brew bundle安装 Homebrew 依赖然后bundle install安装 gem 依赖安装到vendor/gems接着git submodule init/git submodule sync并调用 script/fast-submodule-update 初始化语法子模块最后bundle exec rake samples生成样本数据。git clone https://github.com/github/linguist.git cd linguist/ script/bootstrap验证环境可用从克隆的仓库直接运行 Linguistbundle exec bin/github-linguist --breakdown能输出当前仓库的语言占比和文件明细说明环境搭建完成。在 languages.yml 中添加语言条目在 lib/linguist/languages.yml 中为新语言添加一条目。该文件头部注释定义了各字段的含义和必填项其中type必填取值为data、programming、markup或prosedata/prose类型的语言不计入仓库语言统计见 docs/how-linguist-works.mdextensions关联的文件扩展名列表按升序 ASCII 排序主扩展名必须放在第一位filenames关联的文件名列表与extensions二者至少其一tm_scope该语言对应的 TextMate scope需要与grammars.yml中列出的 scope 之一匹配没有 TextMate 语法时填nonelanguage_idGitHub 内部使用的唯一标识由script/update-ids生成文档明确要求不要手工填写——所以这一步先留空。如果新语言定义的扩展名已经存在于languages.yml并被别的语言使用还有两个额外要求与“给已有语言加扩展名”一节相同samples目录中每个使用该扩展名的语言至少要有两个示例文件如果两种语言外观相似或其中一种有可唯一识别的特征考虑写一个启发式heuristic帮助分类。目标是尽量减少误判false positives。用 script/add-grammar 添加高亮语法语法高亮由 TextMate 兼容语法驱动。为新语言添加语法的命令script/add-grammar https://github.com/某作者/MyGrammar这条命令会分析语法仓库没有问题时把它以子模块形式加入 Linguist 仓库如果分析发现问题你需要向该语法的维护者报告否则无法添加见 CONTRIBUTING.md。命令的参数就是语法仓库的 URL示例中https://github.com/某作者/MyGrammar需替换为你要添加的语言语法仓库地址。script/add-grammar 本身还定义了-q/--quiet失败时不输出额外信息和-r/--replace submodule替换已有语法子模块两个选项--replace用于切换已有语言的语法来源属于另一个维护场景添加新语言时用不到。该脚本启动时会检查docker git sed ruby bundle是否可用缺失时会直接报错退出——这对应上面“添加语法需要 Docker”的前提。语法的正则表达式兼容性会在编译阶段检查Linguist 使用 PCRE而 TextMate 语法基于 Oniguruma两者大多兼容但偶有差异CONTRIBUTING.md 说明语法更新时 Linguist 的 grammar compiler 会标出这些问题。向 samples 目录添加样本代码在 samples/ 目录下对应语言的子目录中添加样本文件文件名使用该语言的扩展名。文档对样本的要求优先选择展示常用写法的真实世界代码越能代表该语言的结构越好“Hello world” 和教程里的示例不会被接受开 PR 时须明确说明样本代码的许可证能直接链接到原始来源最好如果样本是专为这个 PR 编写且同意按 Linguist 的 MIT 许可证收录也可以这样声明。样本的作用之一是喂给分类器docs/how-linguist-works.md 描述了检测策略链modeline、常见文件名、shebang、扩展名、XML header、man page section、启发式、朴素贝叶斯分类按序生效样本是分类器学习材料的来源docs/troubleshooting.md 也提到“增加样本可以让分类器更聪明”。生成 language_id语言条目和样本都就位后运行script/update-idsscript/update-ids 会读取lib/linguist/languages.yml为所有缺少language_id字段的语言生成 ID 并写回文件。脚本输出的 “Updated N language(s)” 列表就是它更新的条目没有缺失 ID 时会输出 “No languages were found with missing IDs.”。它还提供--check参数只做检查不改文件用于查看哪些语言缺 ID。注意它更新的是所有缺 ID 的语言——因此不要在自己的分支上遗留他人未合并的改动避免把无关语言一并带进你的 PR。运行测试验证CONTRIBUTING.md 给出两条本地验证命令# 运行完整测试套件 bundle exec rake test # 单独测试分类器 bundle exec script/cross-validation --test如果本地跑测试困难比如没有太多 Ruby 经验文档明确表示可以让 GitHub Actions 代劳直接开 pull requestCI 会自动开始跑测试。开 PR 与后续PR 必须使用并填写 PR 模板未填模板的 PR 不会被 review。模板要求的关键内容链接到展示该语言实际使用量的 GitHub 搜索结果对应上面的使用量门槛样本代码的许可证说明能直接链接原始来源最好。PR 合并后不会立刻出现在 GitHub 上变更要等新的 Linguist 版本发布并部署到 GitHub.com 才生效发布节奏没有固定时间目标是每三到四个月至少一次见 docs/troubleshooting.md。另外注意新语言在合并且新版本部署后还会在 GitHub 的搜索结果中延迟数周到数月才出现因为 GitHub 搜索使用一个独立于 Linguist 的内部语言检测库会滞后于 Linguist。限制与边界使用量不足的语言非常新、纯兴趣型PR 会被关闭这是硬性门槛样本和语法再完整也无法绕过语法分析失败时script/add-grammar无法继续只能向语法上游维护者报告问题没有旁路语法许可证不在允许列表内时同样无法添加共享扩展名冲突新语言复用了已被别的语言使用的扩展名必须用“每个语言至少两个样本 必要时写启发式”来处理这是为避免误判而设的要求。按以上路径走完——languages.yml条目留空language_id、script/add-grammar引入语法、samples/样本、script/update-ids生成 ID、bundle exec rake test通过、按模板开 PR——就是为 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），仅供参考