企业官网建设流程全解析

ctxsync 文件分类指南：用 category 高效管理大型项目的同步内容

【免费下载链接】ctxsyncctxsync is a Python tool that automates the synchronization of local files with Claude.ai Projects项目地址: https://gitcode.com/gh_mirrors/cl/ctxsync

ctxsync 是一款开源的 Python 文件同步工具，核心功能是自动把本地文件与 Claude.ai Projects 保持同步。当项目文件越来越多时，一次性把所有文件推送到云端既浪费时间又浪费额度。本文的 ctxsync 文件分类指南将带你掌握category命令的完整用法，用分类精准控制同步范围，让大型项目的同步更高效、更省心。

为什么大型项目需要文件分类同步？

很多用户把整个仓库推送到 Claude.ai，结果node_modules、构建产物、历史文档全部上传，既慢又容易触发大小限制。ctxsync 提供的category 文件分类机制，本质上是给同步过程加一道"过滤器"：你只需要定义"哪些文件该同步"，其余的一律跳过。

在源码中，这一逻辑由get_local_files()函数（见 utils.py）实现，它通过pathspec匹配模式决定文件去留，分类规则本身则存储在配置管理的file_categories结构中（见 base_config_manager.py）。

开箱即用的 6 个预置分类

ctxsync 不需要你从零开始配置，安装后自带 6 个实用的预置分类，覆盖绝大多数使用场景：

这些预置分类定义在默认配置字典里，你可以随时查看、修改，也可以删除后重建，完全自定义。

一条命令查看所有分类

在项目目录执行claudesync category ls，即可列出全部已定义的分类名称、描述和匹配模式：

$ claudesync category ls Category: all_source_code Description: All source code files Patterns: - *.java - *.py - *.js - *.ts

如果显示No file categories defined.，说明分类被清空过，可以按下面的方法重新添加。

最快配置方法：新增自定义分类

面对大型项目，最常做的事就是按业务模块建分类。用category add一步到位：

claudesync category add backend \ --description "后端业务代码" \ --patterns "**/backend/**/*.py" \ --patterns "**/backend/**/*.sql"

命令格式为category add <名称> --description <描述> --patterns <模式>，--patterns可以重复多次，把多个路径模式归入同一个分类。该命令最终调用配置管理层的add_file_category()方法（见 file_config_manager.py），把规则写入全局配置。

修改分类的两种方式

• 局部调整：category update backend --patterns "**/backend/**/*.go"，只更新模式，描述保持不变；
• 彻底重写：category update backend --description "新描述" --patterns "**/core/**/*.py"，同时更新描述和模式。

如果某个分类不再需要，category rm <名称>一键删除。这三个命令组成了分类的完整"增删改查"闭环。

同步时指定分类的两条路径

分类配好后，有两条使用路径：

1. 临时指定：在claudesync push时加上--category参数，本次同步立即生效。push命令会读取该分类的 patterns 并过滤本地文件（见 main.py）。
2. 设为默认：执行claudesync category set-default backend，之后不带参数执行push也会自动使用该分类。默认分类被持久化到本地配置中，下次运行无需重复指定。

一个实战案例：前后端分离项目

假设你的仓库同时包含frontend/和backend/两个目录，还混着大量文档和图片：

1. 分别创建分类：frontend（匹配**/frontend/**/*.{js,ts,vue}）和backend（匹配**/backend/**/*.py）；
2. 用claudesync push --category frontend只同步前端代码给 Claude.ai 分析；
3. 需要分析后端时，再执行claudesync push --category backend，互不干扰，也不会误传.md文档或node_modules里的垃圾文件。

文件分类同步的三个避坑建议

• 模式语法：分类模式使用 gitwildmatch 语法，**表示任意层级目录，*只匹配当前层级，写模式前先用category ls验证；
• 忽略规则优先级：.gitignore和.claudeignore中的忽略项始终优先于分类模式，被忽略的文件即使匹配分类也不会同步；
• 谨慎删除：category rm会删除该分类及其全部模式，如果它正被设为默认，记得重新执行set-default指定新分类。

结语

ctxsync 的 category 文件分类功能，让"同步什么、不同步什么"完全掌握在你手中。无论是只想推送源码、只同步测试文件，还是按业务模块分批推送，一套分类配置就能让大型项目的同步又快又准。现在就运行claudesync category ls看看你的预置分类，从创建第一个自定义分类开始，体验更聪明的同步方式吧！

【免费下载链接】ctxsyncctxsync is a Python tool that automates the synchronization of local files with Claude.ai Projects项目地址: https://gitcode.com/gh_mirrors/cl/ctxsync