paseo/public-docs/worktrees/worktreeinclude.zh-CN.md

title, description, nav, order, category

title	description	nav	order	category
.worktreeinclude	将 Git 忽略的本地文件复制到新的 Paseo worktree。	.worktreeinclude	12	Workspaces

.worktreeinclude

在源检出的根目录添加 .worktreeinclude，将本地配置复制到新的 Git worktree。Paseo 会在 setup、终端和首个 Agent 启动之前复制匹配的 Git 忽略文件。

复制本地配置

如果项目的 .gitignore 包含 .env 和 config/*.local.json，创建以下 .worktreeinclude：

.env
config/*.local.json

通过 Paseo 创建 worktree 时，已有的 .env 和 config/dev.local.json 等匹配文件会被复制到新 worktree 中的相同相对路径。文件内容仍不会纳入 Git。

提交 .worktreeinclude，与团队共享这些模式。每位团队成员在用于创建 worktree 的检出中提供自己的忽略文件。

模式语法

使用 gitignore 语法，每行一个模式。注释以 # 开头。模式前加 ! 可排除匹配项：

# Local environment and configuration
.env
config/*.local.json
!config/production.local.json

模式只会选择 Git 已忽略的文件。在此添加路径不会使 Git 忽略该文件，需要时还应配置 .gitignore。已跟踪的文件和未被 Git 忽略的未跟踪文件都不会被复制。

文件复制时机

内置的 worktree-include 插件从用于创建 worktree 的检出读取该文件。源检出也可以是另一个 worktree。保持该插件启用才能执行复制。

• 没有 .worktreeinclude 时，插件不会复制任何文件。
• 匹配的文件必须存在于源检出中。
• 目标中已存在的文件会被跳过，保留原有内容。
• 复制发生在创建期间，之后不会在检出之间持续同步。
• 复制错误会中止创建并删除新 worktree。避免包含符号链接目录或嵌套仓库，因为它们无法作为文件复制。

在 setup 期间运行命令

使用 .worktreeinclude 复制本地已有文件。使用 setup 钩子 安装依赖、生成文件或获取密钥：

{
  "worktree": {
    "setup": "npm ci"
  }
}

将此配置放入新 worktree 所用基准分支的 paseo.json 中。setup 运行时，复制的文件已可使用。