如何让GitHub正确检测到项目中的SQL代码？

我完全懂你现在的烦恼——项目里放在docs/sql/目录下的SQL建表语句明明是标准写法，但GitHub就是没把它识别成SQL语言，折腾了.gitattributes配置也没搞定。别担心，我们一步步来解决这个问题，你的SQL语法本身是没问题的，问题出在配置的细节上。

先确认：你的SQL代码完全符合标准 #

首先可以放心，你写的建表语句是标准的SQL语法，GitHub Linguist（GitHub用来检测语言的工具）完全能识别这种格式，比如你的这段代码：

CREATE TABLE action (
 id INTEGER,
 created_at TIMESTAMP,
 updated_at TIMESTAMP,
 description VARCHAR(255),
 name VARCHAR(75) NOT NULL UNIQUE,
 PRIMARY KEY (id)
);
CREATE TABLE brand (
 id INTEGER,
 created_at TIMESTAMP,
 updated_at TIMESTAMP,
 description VARCHAR(255),
 name VARCHAR(75) NOT NULL UNIQUE,
 PRIMARY KEY (id)
);
CREATE TABLE flavor (
 id INTEGER,
 created_at TIMESTAMP,
 updated_at TIMESTAMP,
 description VARCHAR(255),
 name VARCHAR(75) NOT NULL UNIQUE,
 available BOOLEAN NOT NULL,
 PRIMARY KEY (id)
);
CREATE TABLE product (
 id INTEGER,
 created_at TIMESTAMP,
 updated_at TIMESTAMP,
 description VARCHAR(255),
 name VARCHAR(75) NOT NULL UNIQUE,
 price NUMERIC(8,2) NOT NULL,
 stock INTEGER NOT NULL,
 brand_id BIGINT NOT NULL,
 PRIMARY KEY (id)
);
CREATE TABLE role (
 id INTEGER,
 created_at TIMESTAMP,
 updated_at TIMESTAMP,
 description VARCHAR(255),
 name VARCHAR(75) NOT NULL UNIQUE,
 PRIMARY KEY (id)
);
CREATE TABLE role_action (
 role_id BIGINT NOT NULL,
 action_id BIGINT NOT NULL,
 PRIMARY KEY (role_id, action_id)
);
CREATE TABLE size (
 id INTEGER,
 created_at TIMESTAMP,
 updated_at TIMESTAMP,
 description VARCHAR(255),
 name VARCHAR(75) NOT NULL UNIQUE,
 available BOOLEAN NOT NULL,
 price NUMERIC(8,2) NOT NULL,
 PRIMARY KEY (id)
);
CREATE TABLE user (
 id INTEGER,
 created_at TIMESTAMP,
 updated_at TIMESTAMP,
 passwd_hash VARCHAR(60) NOT NULL UNIQUE,
 phone_number VARCHAR(30) NOT NULL UNIQUE,
 salt VARCHAR(50) NOT NULL UNIQUE,
 username VARCHAR(50) NOT NULL UNIQUE,
 role_id BIGINT NOT NULL,
 PRIMARY KEY (id)
);

所以问题肯定不在SQL代码本身，而是.gitattributes的配置或者文件路径的匹配上。

修正你的.gitattributes配置 #

你之前尝试的配置有几个小问题，比如路径匹配不精确、语法格式不对。我们来写一个精确且正确的配置：

# 确保docs/sql目录下的所有SQL文件被正确识别
docs/sql/**/*.sql linguist-detectable=true
docs/sql/**/*.sql linguist-language=SQL

# 如果你还有query/目录下的SQL文件，同样配置
query/**/*.sql linguist-detectable=true
query/**/*.sql linguist-language=SQL

# 保留你之前的Kotlin DSL配置（如果需要的话）
*.kts linguist-detectable=true
*.kts linguist-language=Kotlin

配置的关键细节：

• 用docs/sql/**/*.sql而不是*.sql：这样只会匹配docs/sql/下所有子目录和文件里的.sql文件，不会误匹配项目中其他可能的.sql文件（比如某些依赖里的）。
• 每个属性配置要明确：linguist-detectable=true告诉Linguist这个文件需要被检测，linguist-language=SQL强制指定语言为SQL（虽然默认应该识别，但强制指定更保险）。
• 避免语法错误：你之前写的*.sql linguist-detectable缺少=true，Linguist需要明确的布尔值。

额外的验证步骤 #

配置好后，按以下步骤确认：

• 把更新后的.gitattributes推送到GitHub，等待1-2分钟（GitHub需要重新扫描仓库语言统计），然后查看仓库主页的语言卡片，应该能看到SQL的占比了。
• 本地测试（可选）：如果你想提前验证，可以安装GitHub Linguist工具（需要Ruby环境），在项目根目录运行linguist命令，输出的语言列表里应该包含SQL。
• 检查文件命名：确保你的SQL文件都是以.sql为后缀的，比如schema.sql而不是schema（没有后缀的话Linguist很难识别）。

为什么之前的配置没生效？ #

主要是两个原因：一是全局的*.sql配置可能被项目中其他规则覆盖，二是配置语法不完整（比如缺少=true）。用精确路径的配置后，就能确保目标目录下的SQL文件被正确识别了。

内容来源于stack exchange