big-AGI 开发工作流使用 create-dev-worktree.sh 管理 git worktree 并行开发【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI导读本指南讲解 big-AGI 仓库内置的 git worktree 开发工作流工具create-dev-worktree.sh它把「git worktree 创建」「环境文件同步」「IDE 打开」整合成一条命令让你在 main、dev、staging、prod 多分支并行开发时不再手动处理.env、IntelliJ 运行配置和依赖安装。读完本文你将掌握创建、物化、列出、移除 worktree 的全部命令理解脚本内部的保护机制与可移植性设计并能够把这套模式复用到自己的项目中。一、为什么要为 big-AGI 引入 worktree 开发工作流big-AGI 是一个多分支、多远端协作的 Next.js 项目。从 AGENTS.md 可以看到它的 Git 拓扑很有代表性opensource远端对应公开仓库默认分支main是 local-first、BYO-keys 的开源构建private远端是主开发仓库维护dev - staging - prod的发布管线dev通过 rebase 保持在main之上两条长期分支以及大量功能分支需要同时在本地存在。传统做法是在同一个工作目录里反复git checkout切换分支。问题是切换会中断当前工作区状态、重新触发构建缓存失效而且不同分支的node_modules、.env配置混在一起。git worktree 的解法是把不同分支物理隔离到各自独立的目录每个 worktree 可以独立运行npm run dev、独立持有自己的.env文件。但裸用git worktree add仍很繁琐新建分支、复制环境文件、准备 IDE 配置、安装依赖这些步骤每次都要手工重复。create-dev-worktree.sh正是为消除这套重复劳动而生的开发脚手架。二、快速上手命令速查脚本位于 tools/develop/worktrees/create-dev-worktree.sh其官方用法在 tools/develop/worktrees/README.md 中定义如下create-dev-worktree.sh branch-name # Create worktree from HEAD create-dev-worktree.sh branch-name --from ref # Create from a specific ref create-dev-worktree.sh branch-name --no-env # Create without copying .env* files create-dev-worktree.sh --remove branch-name # Remove worktree create-dev-worktree.sh --list # List worktrees实际脚本第 286-293 行的 Usage 输出还补充了两个 README 未完全展开的选项--no-ide创建时不自动打开 IDE和--materialize对已存在的 worktree 补齐开发配置。全部命令形态如下命令作用create-dev-worktree.sh branch-name以当前 HEAD 为基线创建新分支与 worktreecreate-dev-worktree.sh branch-name --from ref从指定 ref如opensource/main、某个 tag 或 commit创建create-dev-worktree.sh branch-name --no-env不复制.env*文件用于密钥敏感场景create-dev-worktree.sh branch-name --no-ide创建后不自动拉起 IDEcreate-dev-worktree.sh --materialize branch\|path给已存在的 worktree 补齐环境文件、运行配置并npm installcreate-dev-worktree.sh --remove branch-name删除 worktree 并在安全前提下删除分支create-dev-worktree.sh --list或-l以表格形式列出所有 worktree脚本约定 worktree 目录固定为仓库同级目录../big-agi_branch-namecreate-dev-worktree.sh并自动完成四件事在指定 ref 上创建新分支、复制全部.env*文件、同步 IntelliJ/WebStorm 运行配置、自动执行npm install。三、创建 worktree参数解析与执行流程3.1 参数解析规则脚本主流程create-dev-worktree.sh接受三种参数branch-name必填新分支名。重复传入或与--from冲突时分别报错--from ref指定基线 ref默认HEAD。ref 不存在时直接退出通过git rev-parse --verify校验--no-env跳过.env*复制--no-ide创建后不打开 IDE。创建前还会做两道防线检查create-dev-worktree.sh若分支refs/heads/name已存在、或../big-agi_name目录已存在都会以红色提示并退出避免覆盖既有工作。3.2 核心命令git worktree add实际的创建命令只有一行create-dev-worktree.shgit worktree add $WORKTREE_PATH --no-track -b $NEW_BRANCH_NAME $SOURCE_REF其中--no-track是刻意为之的细节当--from传入的是远端跟踪 ref例如opensource/main时git 默认会把该远端记为新分支的 upstream进而让 push 默认指向那个远端。脚本注释明确说明push 必须默认走remote.pushDefault因此用--no-track切断这层隐含绑定防止误推。3.3 创建后输出与 IDE 打开创建成功后脚本打印操作摘要分支名、基线 commit 的 7 位缩写、worktree 路径和下一步提示cd进入、IDE 打开命令、--remove清理方式最后调用open_ide()create-dev-worktree.sh自动打开 IDE。四、materialize新 worktree 的「物化」过程创建 worktree 后脚本调用materialize_worktree()create-dev-worktree.sh把主 checkout 的开发配置同步进新目录这是整个脚本最核心的环节顺序如下创建 IDE 目录结构mkdir -p $target_path/.idea/runConfigurations复制环境文件遍历主 checkout 下所有.env*文件cp .env*通配统计并报告复制数量--no-env时跳过并提示skipped复制next-env.d.ts这是 git 忽略但类型检查必需的 Next.js 类型声明文件脚本会在复制前先确认主目录存在它create-dev-worktree.sh复制 IntelliJ 运行配置若.idea/runConfigurations存在把其中全部*.xml复制到目标 worktree并报告配置数量安装依赖若目标存在package.json在目标目录内执行npm install --optionalcreate-dev-worktree.sh否则提示no package.json。脚本中还有几段被注释掉的复制逻辑dataSources 数据源配置、其他.idea/*.xml配置说明作者刻意只同步「跨环境共享」的部分而workspace.xml这类用户专属文件被明确排除避免把本地窗口状态污染到其他 worktree。这套物化逻辑与 big-AGI 的工程结构高度契合项目的环境配置是文件形态参考 docs/environment-variables.md 列出的环境变量而npm install对node_modules是幂等的新目录可以安全并行安装。五、--materialize让 AI Agent 创建的 worktree 也「开发就绪」--materialize branch|pathcreate-dev-worktree.sh是一个面向现代工作流的扩展当 worktree 不是由本脚本创建例如由 AI Agent 或裸git worktree add创建时用它把开发配置补齐到同等水平。目标解析支持三种形式create-dev-worktree.sh直接路径目标目录存在且含.git文件分支名在git worktree list中匹配已检出的分支目录基名匹配big-agi_name、旧式big-agi-name或纯name。两个安全约束值得注意它拒绝物化主 worktree 或当前 checkout 自身防止把副本源覆盖到自己头上见 create-dev-worktree.sh同时声明重复运行是安全的因为复制环境文件和npm install都是幂等操作可用于刷新过期配置。该模式同样支持--no-env、--no-ide子选项适合完全离线的打包场景。六、--list一眼看清所有 worktree 状态list_worktrees()create-dev-worktree.sh把git worktree list的输出渲染成信息密度很高的表格每行包含路径当前目录显示绝对路径其余显示相对路径优先用realpath --relative-tofallback 到 shell 字符串处理分支名从行内[branch]提取并去掉括号创建日期通过读取 worktree admin 目录里gitdir文件的 mtime 推断create-dev-worktree.sh因为该文件只在git worktree add时写入一次主 worktree 没有此文件所以不显示commit 哈希7 位与commit 标题超过 44 字符截断到 42 加..脏标记*通过git status --porcelain -uno检测未提交的已跟踪文件改动[MAIN]标记标注主 worktree← you are here绿色标注当前所在目录尾部统计worktree 总数以及* uncommitted changes的图例说明。时间戳格式化也是可移植的优先用 GNUdate -rLinux、Git-Bashfallback 到 BSDstat -fmacOS见 create-dev-worktree.sh。终端彩色输出则通过[ ! -t 1 ]检测非 TTY 环境并自动降级为无色保证管道输出干净。七、--remove安全清理与三层分支保护--remove branch-namecreate-dev-worktree.sh负责拆除 worktree 和分支其设计重心是绝不误删主 worktree 不可移除若传入分支等于主 worktree 当前检出的分支直接报错create-dev-worktree.sh目标解析宽容同--materialize可按分支名、big-agi_name、big-agi-name、name目录基名匹配能处理「目录名与检出分支不一致」的 scratch worktree例如在某临时目录里git checkout main的情况worktree 删除分级先git worktree remove失败则--force重试再失败才打印错误create-dev-worktree.sh分支删除保护硬编码保护main dev staging prod四个长生命周期分支create-dev-worktree.sh同时如果目标分支仍被其他 worktree 检出也拒绝删除。删除时先试安全的git branch -d未合并则-D强制并给出对应提示结果自检删除后重新查询git worktree list与refs/heads输出Cleanup complete!、kept (protected)或partially complete三种明确结论。脚本注释特别解释了为何需要这层保护git 自身的机制救不了这个场景——worktree 先被移除会释放分支后续裸git branch -D main就会成功因此必须由脚本主动拦截。八、IDE 集成自动检测 WebStormopen_ide()之前脚本在启动时自动探测可用的 IDE 启动器create-dev-worktree.sh按webstorm64Windows/JetBrains Toolbox与webstormmacOS/Linux顺序遍历command -v取第一个命中的作为IDE_CMD均未命中则回退到默认值webstorm64。打开 IDE 时把 worktree 的绝对路径作为参数在后台启动并重定向输出若启动器不在 PATH 中则降级为黄色警告并打印手动打开命令webstorm64 abs_path不影响其他流程。九、周边配套DevTools workspace 生成器与 npm 钩子worktree 工作流不是孤立的。big-AGI 的 package.json 在predev钩子里调用了 tools/develop/gen-devtools-workspace/generate-devtools-workspace.mjs该工具为当前 worktree生成 Chrome DevTools 的自动 workspace 描述文件public/.well-known/appspecific/com.chrome.devtools.json。其关键设计见文件头注释与_uuidV5实现与 worktree 模式直接呼应UUID 由 worktree 的绝对路径通过 RFC 4122 v5SHA-1派生因此每个 worktree 都会广播一组不同的 (root, uuid)。Chrome 按 UUID 记忆文件夹授权这意味着两个 worktree 轮流占用同一端口开发时不会互相继承对方的授权绑定同时每次授权在 dev server 重启后仍被保留。在 CI、Vercel 或NODE_ENVproduction下该生成器会自动跳过--clean可显式清理保证绝不因开发者便利功能破坏构建。十、实战建议与最佳实践结合脚本设计与 big-AGI 仓库规范推荐以下工作流功能开发create-dev-worktree.sh feature-xxx一键创建隔离环境cd ../big-agi_feature-xxx后即可独立npm run dev互不干扰基于远端分支开发create-dev-worktree.sh hotfix-yyy --from opensource/main--no-track保证推送目标始终受控密钥隔离团队共享的 CI 密钥环境使用--no-env避免.env漂移Agent 协作AI Agent 创建 worktree 后用--materialize一键补齐.env*、IntelliJ 配置和依赖再--list核对状态安全清理用--remove而非手写git worktree remove git branch -D让main/dev/staging/prod等保护分支永不被误删。十一、源码导读tools/develop/worktrees/README.md - 官方命令速查本文依据的主体文档tools/develop/worktrees/create-dev-worktree.sh - 全部实现重点函数list_worktreesL65、materialize_worktreeL157、open_ideL261、--materialize分支L310、--remove分支L419、参数解析L613tools/develop/gen-devtools-workspace/generate-devtools-workspace.mjs - 与 worktree 配套的 DevTools workspace 生成器package.json -predev/prebuild钩子展示工具链挂载方式AGENTS.md - 仓库多分支/多远端拓扑与dev - staging - prod工作流解释脚本保护分支选择的工程背景。【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 big-AGI 开发工作流：使用 create-dev-worktree.sh 管理 git worktree 并行开发
big-AGI 开发工作流使用 create-dev-worktree.sh 管理 git worktree 并行开发【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI导读本指南讲解 big-AGI 仓库内置的 git worktree 开发工作流工具create-dev-worktree.sh它把「git worktree 创建」「环境文件同步」「IDE 打开」整合成一条命令让你在 main、dev、staging、prod 多分支并行开发时不再手动处理.env、IntelliJ 运行配置和依赖安装。读完本文你将掌握创建、物化、列出、移除 worktree 的全部命令理解脚本内部的保护机制与可移植性设计并能够把这套模式复用到自己的项目中。一、为什么要为 big-AGI 引入 worktree 开发工作流big-AGI 是一个多分支、多远端协作的 Next.js 项目。从 AGENTS.md 可以看到它的 Git 拓扑很有代表性opensource远端对应公开仓库默认分支main是 local-first、BYO-keys 的开源构建private远端是主开发仓库维护dev - staging - prod的发布管线dev通过 rebase 保持在main之上两条长期分支以及大量功能分支需要同时在本地存在。传统做法是在同一个工作目录里反复git checkout切换分支。问题是切换会中断当前工作区状态、重新触发构建缓存失效而且不同分支的node_modules、.env配置混在一起。git worktree 的解法是把不同分支物理隔离到各自独立的目录每个 worktree 可以独立运行npm run dev、独立持有自己的.env文件。但裸用git worktree add仍很繁琐新建分支、复制环境文件、准备 IDE 配置、安装依赖这些步骤每次都要手工重复。create-dev-worktree.sh正是为消除这套重复劳动而生的开发脚手架。二、快速上手命令速查脚本位于 tools/develop/worktrees/create-dev-worktree.sh其官方用法在 tools/develop/worktrees/README.md 中定义如下create-dev-worktree.sh branch-name # Create worktree from HEAD create-dev-worktree.sh branch-name --from ref # Create from a specific ref create-dev-worktree.sh branch-name --no-env # Create without copying .env* files create-dev-worktree.sh --remove branch-name # Remove worktree create-dev-worktree.sh --list # List worktrees实际脚本第 286-293 行的 Usage 输出还补充了两个 README 未完全展开的选项--no-ide创建时不自动打开 IDE和--materialize对已存在的 worktree 补齐开发配置。全部命令形态如下命令作用create-dev-worktree.sh branch-name以当前 HEAD 为基线创建新分支与 worktreecreate-dev-worktree.sh branch-name --from ref从指定 ref如opensource/main、某个 tag 或 commit创建create-dev-worktree.sh branch-name --no-env不复制.env*文件用于密钥敏感场景create-dev-worktree.sh branch-name --no-ide创建后不自动拉起 IDEcreate-dev-worktree.sh --materialize branch\|path给已存在的 worktree 补齐环境文件、运行配置并npm installcreate-dev-worktree.sh --remove branch-name删除 worktree 并在安全前提下删除分支create-dev-worktree.sh --list或-l以表格形式列出所有 worktree脚本约定 worktree 目录固定为仓库同级目录../big-agi_branch-namecreate-dev-worktree.sh并自动完成四件事在指定 ref 上创建新分支、复制全部.env*文件、同步 IntelliJ/WebStorm 运行配置、自动执行npm install。三、创建 worktree参数解析与执行流程3.1 参数解析规则脚本主流程create-dev-worktree.sh接受三种参数branch-name必填新分支名。重复传入或与--from冲突时分别报错--from ref指定基线 ref默认HEAD。ref 不存在时直接退出通过git rev-parse --verify校验--no-env跳过.env*复制--no-ide创建后不打开 IDE。创建前还会做两道防线检查create-dev-worktree.sh若分支refs/heads/name已存在、或../big-agi_name目录已存在都会以红色提示并退出避免覆盖既有工作。3.2 核心命令git worktree add实际的创建命令只有一行create-dev-worktree.shgit worktree add $WORKTREE_PATH --no-track -b $NEW_BRANCH_NAME $SOURCE_REF其中--no-track是刻意为之的细节当--from传入的是远端跟踪 ref例如opensource/main时git 默认会把该远端记为新分支的 upstream进而让 push 默认指向那个远端。脚本注释明确说明push 必须默认走remote.pushDefault因此用--no-track切断这层隐含绑定防止误推。3.3 创建后输出与 IDE 打开创建成功后脚本打印操作摘要分支名、基线 commit 的 7 位缩写、worktree 路径和下一步提示cd进入、IDE 打开命令、--remove清理方式最后调用open_ide()create-dev-worktree.sh自动打开 IDE。四、materialize新 worktree 的「物化」过程创建 worktree 后脚本调用materialize_worktree()create-dev-worktree.sh把主 checkout 的开发配置同步进新目录这是整个脚本最核心的环节顺序如下创建 IDE 目录结构mkdir -p $target_path/.idea/runConfigurations复制环境文件遍历主 checkout 下所有.env*文件cp .env*通配统计并报告复制数量--no-env时跳过并提示skipped复制next-env.d.ts这是 git 忽略但类型检查必需的 Next.js 类型声明文件脚本会在复制前先确认主目录存在它create-dev-worktree.sh复制 IntelliJ 运行配置若.idea/runConfigurations存在把其中全部*.xml复制到目标 worktree并报告配置数量安装依赖若目标存在package.json在目标目录内执行npm install --optionalcreate-dev-worktree.sh否则提示no package.json。脚本中还有几段被注释掉的复制逻辑dataSources 数据源配置、其他.idea/*.xml配置说明作者刻意只同步「跨环境共享」的部分而workspace.xml这类用户专属文件被明确排除避免把本地窗口状态污染到其他 worktree。这套物化逻辑与 big-AGI 的工程结构高度契合项目的环境配置是文件形态参考 docs/environment-variables.md 列出的环境变量而npm install对node_modules是幂等的新目录可以安全并行安装。五、--materialize让 AI Agent 创建的 worktree 也「开发就绪」--materialize branch|pathcreate-dev-worktree.sh是一个面向现代工作流的扩展当 worktree 不是由本脚本创建例如由 AI Agent 或裸git worktree add创建时用它把开发配置补齐到同等水平。目标解析支持三种形式create-dev-worktree.sh直接路径目标目录存在且含.git文件分支名在git worktree list中匹配已检出的分支目录基名匹配big-agi_name、旧式big-agi-name或纯name。两个安全约束值得注意它拒绝物化主 worktree 或当前 checkout 自身防止把副本源覆盖到自己头上见 create-dev-worktree.sh同时声明重复运行是安全的因为复制环境文件和npm install都是幂等操作可用于刷新过期配置。该模式同样支持--no-env、--no-ide子选项适合完全离线的打包场景。六、--list一眼看清所有 worktree 状态list_worktrees()create-dev-worktree.sh把git worktree list的输出渲染成信息密度很高的表格每行包含路径当前目录显示绝对路径其余显示相对路径优先用realpath --relative-tofallback 到 shell 字符串处理分支名从行内[branch]提取并去掉括号创建日期通过读取 worktree admin 目录里gitdir文件的 mtime 推断create-dev-worktree.sh因为该文件只在git worktree add时写入一次主 worktree 没有此文件所以不显示commit 哈希7 位与commit 标题超过 44 字符截断到 42 加..脏标记*通过git status --porcelain -uno检测未提交的已跟踪文件改动[MAIN]标记标注主 worktree← you are here绿色标注当前所在目录尾部统计worktree 总数以及* uncommitted changes的图例说明。时间戳格式化也是可移植的优先用 GNUdate -rLinux、Git-Bashfallback 到 BSDstat -fmacOS见 create-dev-worktree.sh。终端彩色输出则通过[ ! -t 1 ]检测非 TTY 环境并自动降级为无色保证管道输出干净。七、--remove安全清理与三层分支保护--remove branch-namecreate-dev-worktree.sh负责拆除 worktree 和分支其设计重心是绝不误删主 worktree 不可移除若传入分支等于主 worktree 当前检出的分支直接报错create-dev-worktree.sh目标解析宽容同--materialize可按分支名、big-agi_name、big-agi-name、name目录基名匹配能处理「目录名与检出分支不一致」的 scratch worktree例如在某临时目录里git checkout main的情况worktree 删除分级先git worktree remove失败则--force重试再失败才打印错误create-dev-worktree.sh分支删除保护硬编码保护main dev staging prod四个长生命周期分支create-dev-worktree.sh同时如果目标分支仍被其他 worktree 检出也拒绝删除。删除时先试安全的git branch -d未合并则-D强制并给出对应提示结果自检删除后重新查询git worktree list与refs/heads输出Cleanup complete!、kept (protected)或partially complete三种明确结论。脚本注释特别解释了为何需要这层保护git 自身的机制救不了这个场景——worktree 先被移除会释放分支后续裸git branch -D main就会成功因此必须由脚本主动拦截。八、IDE 集成自动检测 WebStormopen_ide()之前脚本在启动时自动探测可用的 IDE 启动器create-dev-worktree.sh按webstorm64Windows/JetBrains Toolbox与webstormmacOS/Linux顺序遍历command -v取第一个命中的作为IDE_CMD均未命中则回退到默认值webstorm64。打开 IDE 时把 worktree 的绝对路径作为参数在后台启动并重定向输出若启动器不在 PATH 中则降级为黄色警告并打印手动打开命令webstorm64 abs_path不影响其他流程。九、周边配套DevTools workspace 生成器与 npm 钩子worktree 工作流不是孤立的。big-AGI 的 package.json 在predev钩子里调用了 tools/develop/gen-devtools-workspace/generate-devtools-workspace.mjs该工具为当前 worktree生成 Chrome DevTools 的自动 workspace 描述文件public/.well-known/appspecific/com.chrome.devtools.json。其关键设计见文件头注释与_uuidV5实现与 worktree 模式直接呼应UUID 由 worktree 的绝对路径通过 RFC 4122 v5SHA-1派生因此每个 worktree 都会广播一组不同的 (root, uuid)。Chrome 按 UUID 记忆文件夹授权这意味着两个 worktree 轮流占用同一端口开发时不会互相继承对方的授权绑定同时每次授权在 dev server 重启后仍被保留。在 CI、Vercel 或NODE_ENVproduction下该生成器会自动跳过--clean可显式清理保证绝不因开发者便利功能破坏构建。十、实战建议与最佳实践结合脚本设计与 big-AGI 仓库规范推荐以下工作流功能开发create-dev-worktree.sh feature-xxx一键创建隔离环境cd ../big-agi_feature-xxx后即可独立npm run dev互不干扰基于远端分支开发create-dev-worktree.sh hotfix-yyy --from opensource/main--no-track保证推送目标始终受控密钥隔离团队共享的 CI 密钥环境使用--no-env避免.env漂移Agent 协作AI Agent 创建 worktree 后用--materialize一键补齐.env*、IntelliJ 配置和依赖再--list核对状态安全清理用--remove而非手写git worktree remove git branch -D让main/dev/staging/prod等保护分支永不被误删。十一、源码导读tools/develop/worktrees/README.md - 官方命令速查本文依据的主体文档tools/develop/worktrees/create-dev-worktree.sh - 全部实现重点函数list_worktreesL65、materialize_worktreeL157、open_ideL261、--materialize分支L310、--remove分支L419、参数解析L613tools/develop/gen-devtools-workspace/generate-devtools-workspace.mjs - 与 worktree 配套的 DevTools workspace 生成器package.json -predev/prebuild钩子展示工具链挂载方式AGENTS.md - 仓库多分支/多远端拓扑与dev - staging - prod工作流解释脚本保护分支选择的工程背景。【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考