跳到主要内容

让新工作树适合你的项目

可以先使用默认配置。发现自己总在重复某个初始化步骤、选择同一个编辑器或复制相同文件时,再添加对应配置。

选择配置保存位置​

位置用途
~/.config/gji/config.json跨仓库使用的个人默认值
全局文件中的 repos 条目特定仓库的个人设置,包括私有本地文件名
仓库内的 .gji.json共享的项目默认值

配置按上述顺序读取:全局默认值、全局文件中的仓库设置、再到本地 .gji.json。后读取的层覆盖前面的值。钩子按事件键合并;同一事件由后面的层覆盖。

保存编辑器或分支前缀​

gji open --editor cursor --save
gji config set branchPrefix feature/

请使用已经安装的编辑器命令。config 修改的是全局默认值:

gji config get
gji config get branchPrefix
gji config unset branchPrefix

复制私有本地文件​

在需要把文件带入后续新工作树的仓库中运行:

gji sync-files add .env.local .npmrc
gji sync-files list
gji sync-files remove .npmrc

清单保存在全局配置中对应仓库的条目里。新工作树会在准备依赖前从主工作树复制文件。源文件不存在时会跳过,目标已有的文件不会被覆盖。这只是在创建时复制一次,不会持续同步。

对于共享的项目文件,请改用 .gji.json 中的 syncFiles:

{
"syncFiles": [".env.example", ".nvmrc"]
}

依赖初始化​

新工作树使用自己的一套依赖。gji new 或 gji pr 检测到支持的锁文件时,会在项目中执行相应的初始化:

项目初始化操作
pnpm, Yarn, Bun, npm安装 JavaScript 依赖
uv, Poetry, Pipenv安装 Python 环境
Bundler安装到 vendor/bundle
Composer安装到 vendor
Gogo mod download
Cargocargo check 或配置的 dependencyBuildCommand

工作树之间不会复制依赖树或构建缓存。初始化可能需要一些时间,也需要相应工具和远程访问权限。已配置的本地文件会先复制;初始化成功后才运行 afterCreate 钩子。

仅跳过这一次安装:

gji new feature/search --no-install
gji pr 1234 --no-install

若要对整个仓库关闭此功能,在 .gji.json 中设置:

{
"dependencyBootstrap": "off"
}

用 gji new feature/search --dry-run 可以查看创建计划。除非禁用,JSON 和非交互式命令也会执行同样的依赖初始化。如果失败,请进入提示的工作树路径修复,不要重新创建任务;详见问题排查。

选择工作树目录​

默认位置是 ../worktrees/<repo>/<branch>。如果某个仓库需要不同的基础目录,可以在它的 .gji.json 或全局仓库设置中指定 worktreePath:

{
"worktreePath": "~/worktrees/my-repo"
}

分支会放在该基础路径下:feature/search 对应 ~/worktrees/my-repo/feature/search。请使用绝对路径或以 ~/ 开头的路径;相对路径会被忽略,并显示警告。此设置只影响后续创建,不会改变已有工作树的位置。

使用其他同步目标​

{
"syncRemote": "upstream",
"syncDefaultBranch": "main"
}

这些设置控制 gji sync 的同步目标,以及 gji new --branch-only 使用的远程默认分支。详见同步与清理。

不把个人仓库设置提交到 Git​

在 ~/.config/gji/config.json 中配置:

{
"repos": {
"/home/me/code/my-repo": {
"editor": "zed",
"syncFiles": [".env.local"],
"hooks": {
"afterCreate": ["pnpm", "run", "generate"]
}
}
}
}

仓库条目使用绝对路径。覆盖设置只对指定的仓库生效。

配置项参考​

键用途
branchPrefix新分支名的前缀,例如 feature/
editoropen 和 new --open 默认使用的编辑器命令
worktreePath新工作树的基础目录,使用绝对路径或 ~/ 路径
syncRemote同步使用的远程仓库
syncDefaultBranch同步目标默认分支
syncFiles创建时从主工作树复制的文件
dependencyBootstrap设为 off 可关闭自动依赖初始化
dependencyBuildCommand可选的 Cargo 初始化命令,默认为 cargo check
shellIntegration设置向导保存的 Shell 配置选择
installSaveTarget设置向导的配置保存在本地还是全局
hooks创建、进入、切换和移除时执行的生命周期命令
repos全局配置中的仓库级覆盖设置