Code-Graph-RAG 忽略模式.cgrignore完全指南精确控制多语言代码库的分析范围【免费下载链接】code-graph-ragThe ultimate RAG for your monorepo. Query, understand, and edit multi-language codebases with the power of AI and knowledge graphs项目地址: https://gitcode.com/GitHub_Trending/co/code-graph-ragdocs/advanced/ignore-patterns.md定义了 Code-Graph-RAG 的排除机制通过在仓库根目录创建.cgrignore文件即可用 gitignore 风格的模式指定从图索引分析中排除的文件与目录。本文以该文档为骨架结合codebase_rag/config.py、codebase_rag/utils/path_utils.py、codebase_rag/graph_updater.py等源码与测试完整展开语法规则、默认排除、可救回un-ignore语义与重同步原理帮助你在 monorepo 场景下把 vendor 代码、构建产物与编辑器残留挡在图谱之外并理解为何修改排除集合一定会触发一次增量同步。.cgrignore 是什么.cgrignore是 Code-Graph-RAG 在仓库根目录读取的可选配置文件用来指定在分析indexing/sync时额外排除的文件与目录。它遵循.gitignore约定因此熟悉 Git 的开发者可以零成本上手。典型的使用动机包括仓库里提交了不应进入图分析的 vendor 代码前端框架压缩包、第三方库构建产物没有完全被默认排除规则覆盖文档目录下混有生成文件而你只想索引第一方 Markdown希望保留某些被默认规则误伤的、确实需要被提问和检索的文件如自己维护的压缩 bundle。格式与一个最小可用的示例.cgrignore是纯文本文件每行一个模式。以下示例取自原文档并标注了每一行的语义# Comments start with # vendor # 任意深度下名为 vendor 的文件/目录 *.gen.ts # 任意路径下以 .gen.ts 结尾的文件 docs/*.md # 锚定到根仅 docs/ 下一层的 .md /generated # 前导斜杠仅根目录下的 generated fixtures/** # 递归匹配 fixtures 下的一切 !bin/keep.py # 否定把 bin/keep.py 重新纳入将其保存为仓库根目录的.cgrignore后下一次cgr同步就会按该集合建立索引。匹配规则排除模式遵循 gitignoregitwildmatch语法。规则逐条拆解如下规则说明*匹配段内*只在一个路径段内匹配不跨越/**跨越段**可以匹配任意层级的路径段?单字符?精确匹配一个字符裸名称vendor匹配任意深度下具有该名称的文件或目录含斜杠的模式docs/*.md、/generated锚定到仓库根目录尾部斜杠build/仅匹配目录!开头!bin/keep.py取消默认排除对匹配路径的忽略显式排除总是优先#开头注释行空行直接忽略从源码结构看这些模式经由pathspec库按gitignore风格编译——path_utils.py 中的compiled_ignore_spec使用PathSpec.from_lines(cs.GITWILDMATCH_STYLE, sorted(patterns))其中GITWILDMATCH_STYLE gitignore定义于 constants/languages.py。matches_ignore_patterns再以match_file对仓库相对路径进行判定。排除集合的三个来源与合并顺序.cgrignore中的模式并非唯一的排除通道实际生效的排除集合由三部分合并而成.cgrignore中的 exclude 模式非!开头的行CLI 的--exclude标志与.cgrignore使用同一套语法可重复传入多个模式见 cli.py帮助文本为 Exclude paths matching PATTERN from indexing. Repeat the option to add patterns.自动检测目录Code-Graph-RAG 在仓库根自动检测常见非源码目录作为交互式设置的候选。合并后的判定在 cli.py 的_run_graph_sync中完成exclude_paths cli_excludes | cgrignore.exclude而unignore_paths来自!行启用--interactive-setup时还会与交互选择结果合并。同时仓库根的.gitignore也会被读取并合并进排除集合——config.py 的load_ignore_patterns注释说明了权威性关系.cgrignore是 cgr 的权威通道.gitignore的排除会被合并但.cgrignore/.gitignore中精确的!否定模式可以取消.gitignore的对应排除仅限逐字取消如!generated/取消generated/.cgrignore的 exclude永不被.gitignore的否定取消即 cgr 自身的选择优先于 Git 的惯例。交互式设置当启用--interactive-setup时main.py 的prompt_for_unignored_directories会把自动检测目录与预先排除集合分组展示允许你按编号选择保留include哪些目录甚至逐项展开嵌套目录精细挑选。这里的保留选择本质上也是一组 un-ignore 路径与!行合并生效。改变排除集合 改变仓库重同步机制排除集合是索引建立时所依据的一部分因此改变它会被当作对仓库的一次变更传入不同的--exclude标志编辑.cgrignore或.gitignore中的模式包括!否定改变交互式设置中的保留选择以上任一操作都会在磁盘文件没有任何变化时也重新运行同步新被排除的文件其Module、Class、Method节点会从图中移除新被纳入的文件会被索引。原因很直接仅靠文件哈希无法感知排除集合的变动——graph_updater.py 的同步检查注释明确指出磁盘上没有任何东西改变仅排除集合变化时哈希缓存和目录 mtime 都看不到它仅由 CLI 标志排除的文件会保留上次运行赋予它的 Module、Class 和 Method 节点。为此GraphUpdater在同步前调用_exclusions_match_last_run()graph_updater.py比对当前排除集合与上次记录的集合不一致即判定需要重跑。每个索引建立时的排除集合被记录在仓库根目录的.cgr-exclusion-state.json中常量定义见 constants/core.py与哈希缓存.cgr-hash-cache.json并列。状态文件内容为 JSON 对象包含exclude、unignore两个排序后的模式列表以及可选的项目名与named标记见 graph_updater.py。特别地如果索引建立早于该状态文件的存在则没有记录的集合。此时升级后的第一次运行会无条件重跑一次以建立基线并记录原因——日志消息定义在 logs.pyNo recorded exclusion set for this graph, so it cannot be shown unchanged; re-running once to establish it. Expect this exactly once per existing index.每个已有索引恰好出现一次。重同步时被排除文件的节点通过CYPHER_DELETE_MODULE从图中整棵删除graph_updater.py保证重命名或移除后不会残留悬空的 Function/Class/Method 节点。默认排除目录与文件名结尾即使不写任何配置Code-Graph-RAG 也会自动排除常见的非源码目录。内置的自动检测目录集合定义于 constants/languages.py包括但不限于.git node_modules __pycache__ dist build target vendor .venv env venv .gradle .idea .vscode .mypy_cache .pytest_cache Pods obj out temp tmp .env .cache coverage htmlcov .tox .nox bower_components site-packages .dart_tool .yarn .npm .pnpm-store ...其中包含一个特例bin是构建输出目录除了 Cargo 的src/bin/布局第一方二进制源码目录构建系统不会向其中输出产物——path_utils.py 的has_ignored_dir_part对该组合放行。此外单个文件还会按文件名结尾被跳过覆盖构建产物与编辑器残留以及压缩 bundle无条件忽略.pyc、.pyo、.o、.a、.so、.dll、.class、.tmp、~可救回rescuable.min.js、.min.css。这两组常量分别定义于 constants/languages.pyUNCONDITIONAL_IGNORE_SUFFIXES与RESCUABLE_IGNORE_SUFFIXES。源码注释解释了取舍编译产物和编辑器残留没有任何配置应该让其复活而.min.js/.min.css虽是生成物却是解析器能读取的文本用户存在将其纳入图谱的合理诉求。为什么压缩 bundle 值得单列压缩 bundle 的重要性远超其数量占比一个提交了生成式 API 文档jazzy、YARD、JSDoc、Sphinx的项目通常会随文档附带 vendored 的 jQuery 或 Lunr而这些文件贡献的函数数量可能超过项目自身源码且函数名都是压缩器随意取的v、y、ce对图谱质量是纯噪声。这正是默认跳过.min.js/.min.css的原因。精确结尾匹配的边界默认规则只匹配精确的结尾app.min.js被跳过admin.js、min.js正常索引非压缩的 vendored 文件如docs/js/typeahead.jquery.js不受该规则覆盖需要你在.cgrignore中显式排除可以精确命名该文件或使用docs/**/js/**覆盖整个 vendored 目录。源码层面的实现细节判定用的是str.endswith而非Path.suffixpath_utils.py因为Path(jquery.min.js).suffix的结果是.js、Path(notes.py~).suffix的结果是.py~用 pathlib 后缀做成员测试会同时漏掉这两类文件导致索引器与实时监视器对哪些文件在图里产生分歧。对整目录的兜底模式docs/**要谨慎它会把文档层document tier刻意索引的第一方 Markdown 一起丢掉。救回un-ignore语义目录级!救不了生成文件与上述目录排除不同救回生成文件所在的目录并不能把它带回来!build/不会复活build/out.pyc或build/js/jquery.min.js。能否覆盖取决于文件类型结尾可覆盖.pyc、.pyo、.o、.a、.so、.dll、.class、.tmp、~否。任何配置下编译产物与编辑器残留都不是源码.min.js、.min.css是但必须用!行精确命名该文件因此一个你维护的 bundle或一个你想针对其提问的第三方 bundle可以被刻意纳入索引!docs/js/jquery.min.js而目录级!不够用这保证了默认行为在常见场景下不被意外破坏一个提交了生成式 API 文档的仓库除非逐个点名想要的文件否则其 vendored JavaScript 一个都不会进图。关键约束是救回行必须逐字命名文件——含*、?或[的!模式救不了 bundle所以!docs/js/*.min.js与!*.min.js都无效每个文件都需要单独一行。这是全文中唯一的例外规则其余位置的!模式照常接受 glob因为 glob 恰恰是整个子树的写法正是该默认规则要保护的目录级意图。这一精确命名判定由 path_utils.py 的unignore_names_this_file实现它去除尾部斜杠后比较模式与文件路径或裸文件名!docs/js/jquery.min.js与!jquery.min.js都能救回而!docs、!docs/js、!docs/**不能。should_skip_pathpath_utils.py中的判定顺序体现了全部优先级无条件忽略编译产物最先拦截 → 显式 exclude → 可救回后缀在此处检查!是否精确命名了文件→ 一般 un-ignore → 目录路径段检查。测试 test_gitignore_ignore_semantics.py 覆盖了排除目录不被救回“内置忽略目录被精确 un-ignore 救回等语义test_evals_honour_cgrignore.py 则验证了!build/keep.py能穿透内置的build/忽略、让文件进入图谱并产出真实的继承边。作用范围只读根目录子目录与子模块例外只有仓库根目录的.cgrignore和.gitignore会被读取对应常量CGRIGNORE_FILENAME、GITIGNORE_FILENAME见 config.py。以下内容不会被读取子目录中的 ignore 文件不支持嵌套 ignore 语义Git 子模块自带的.gitignore——子模块文件会作为父项目的一部分被索引除非父项目显式排除它们。关于子模块的详细处理参见 Git 子模块指南。解析层面的行为_load_ignore_fileconfig.py对每个非空、非#行做strip()后!开头归入unignore其余归入exclude读取失败OSError/ValueError或文件不存在时返回空集合不会中断同步。小结一份实用的 .cgrignore 清单结合以上规则为一个典型的 monorepo 编写.cgrignore的推荐姿势# 排除 vendored 与生成目录 vendor/ third_party/ generated/ # 文档目录下只需第一方 Markdown 时排除生成物而非整个 docs docs/api/out/** docs/static/vendor/** # 精确点名要纳入的压缩 bundleglob 无效必须逐字 !docs/js/jquery.min.js写完配置后观察同步日志即可验证效果排除集合变化时会出现Exclusion set changed since the last sync ...见 logs.py随后新排除文件会从图中移除节点。若只想临时排除而不用文件直接给cgr start或对应索引命令追加可重复的--exclude标志即可——它与.cgrignore使用同一套 gitignore 语法并同样计入排除状态。相关源码与测试索引模式加载与合并config.py、test_cgrignore.py、test_gitignore_patterns.py路径判定与优先级path_utils.py、test_gitignore_ignore_semantics.py内置忽略集合constants/languages.py排除状态与重同步graph_updater.py、constants/core.py交互式设置main.py【免费下载链接】code-graph-ragThe ultimate RAG for your monorepo. Query, understand, and edit multi-language codebases with the power of AI and knowledge graphs项目地址: https://gitcode.com/GitHub_Trending/co/code-graph-rag创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考