create-worktree

name	create-worktree
description	Create a ClickHouse git worktree with submodules hardlinked from the main repo. Use when the user wants to create a new worktree for ClickHouse development.
argument-hint	<branch-name>
disable-model-invocation	false
allowed-tools	Bash(git:*), Bash(cp:*), Bash(ln:*), Bash(ls:*), Bash(rm:*), Bash(mkdir:*), Bash(find:*), Bash(pwd:*), AskUserQuestion

Create ClickHouse Worktree Skill

Create a new git worktree for ClickHouse development. When the worktree will be built or tested, submodules are hardlinked from the main repo (independent copies, no network, no extra disk for git objects). For text-only tasks (docs, comments, typo fixes), submodule setup is skipped — it's the slow part of the workflow and is pure overhead when nothing will be compiled.

Arguments

• $0 (required): Branch name. If the branch already exists, the worktree will check it out. If it doesn't exist, a new branch will be created from the current HEAD of the main repo.

Process

1. Determine the source repo

• Detect the source repo (MAIN_REPO) by running git rev-parse --show-toplevel from the current working directory.
• Verify it is a git repository. If not, report an error and stop.

2. Validate inputs

• Ensure $0 (branch name) is provided. If not, use AskUserQuestion to ask the user for a branch name.
• Compute SAFE_BRANCH by replacing all / characters in the branch name with -. For example, branch release/25.12 → SAFE_BRANCH=release-25.12. This avoids creating nested directories from slashes in branch names.
• Use AskUserQuestion to ask the user for the worktree destination path. Suggest <MAIN_REPO>/../<MAIN_REPO_NAME>-<SAFE_BRANCH> as the default — this places the worktree as a sibling of the main repo directory, named after both the repo and the branch (e.g. ../ClickHouse-my-feature or ../ClickHouse-release-25.12). The user may enter a different path if preferred.

Let WORKTREE_PATH be the chosen path (resolved to an absolute path).

3. Determine worktree path and branch state

• Worktree path: <WORKTREE_PATH> (from step 2)
• Check if the worktree directory already exists. If it does, report to the user and stop.
• Check if the branch already exists:

  git -C <MAIN_REPO> branch --list <branch-name>
  git -C <MAIN_REPO> branch --list -r "origin/<branch-name>"
  

4. Create the worktree

If branch exists locally:

git -C <MAIN_REPO> worktree add <WORKTREE_PATH> <branch-name>

If branch exists on remote only:

git -C <MAIN_REPO> worktree add <WORKTREE_PATH> -b <branch-name> origin/<branch-name>

If branch does not exist (create new):

git -C <MAIN_REPO> worktree add -b <branch-name> <WORKTREE_PATH>

5. Decide whether to set up submodules

The submodule hardlink step below is the slow part of this skill — it walks every contrib module, runs cp -al over all of them, rewrites configs, and checks out every submodule's working tree.

Skip step 6 entirely (jump to step 7) when the planned work is text-only and won't be built or tested locally:

• docs, comments, changelog entries, .md files
• typo fixes in source files where no compile is needed to verify

Run step 6 when the task will involve ninja or running tests against this worktree.

If genuinely unsure, use AskUserQuestion: "Will you build or run tests in this worktree? (No → skip submodule setup, much faster)"

6. Set up submodules via hardlinks

Only do this step if step 5 selected the build/test path. Instead of cloning each submodule from the network, hardlink the git modules directory from the main repo. This gives each worktree an independent copy of the submodule git data (safe to modify independently) without using extra disk space for the object files, and without any network access.

Determine GIT_DIR — the .git directory of the main repo. For a regular repo this is <MAIN_REPO>/.git. For a worktree it may differ; use git -C <MAIN_REPO> rev-parse --git-common-dir to get the correct path.

Determine WORKTREE_ENTRY — the name git uses for this worktree's entry in $GIT_DIR/worktrees/. This is $(basename <WORKTREE_PATH>).

GIT_DIR=$(git -C <MAIN_REPO> rev-parse --git-common-dir)
WORKTREE_ENTRY=$(basename <WORKTREE_PATH>)

# Hardlink-copy the modules directory from the main repo
cp -al $GIT_DIR/modules \
       $GIT_DIR/worktrees/$WORKTREE_ENTRY/modules

# Fix the worktree pointer inside each submodule's config.
# The hardlinked configs still reference the main repo's worktree path,
# so update them to point to the new worktree's contrib directories.
find $GIT_DIR/worktrees/$WORKTREE_ENTRY/modules -name config -exec \
    sed -i "s|worktree = .*/contrib/|worktree = <WORKTREE_PATH>/contrib/|" {} +

# Some submodules (e.g. contrib/boost) use the worktreeConfig extension,
# storing the actual core.worktree in config.worktree instead of config.
# The hardlinked config.worktree files contain relative paths like
# "../../../../contrib/boost" that resolve correctly from the main repo's
# modules dir but incorrectly from the worktree's modules dir.
# Fix them to use absolute paths pointing to the new worktree.
find $GIT_DIR/worktrees/$WORKTREE_ENTRY/modules -name config.worktree -exec \
    sed -i "s|worktree = .*/contrib/|worktree = <WORKTREE_PATH>/contrib/|" {} +

# Register submodules and write .git pointer files into contrib/ directories
# (no network — uses hardlinked objects). This does NOT populate working trees.
git -C <WORKTREE_PATH> submodule update

# Populate submodule working trees. The previous command only writes .git pointer
# files but leaves working trees empty because the hardlinked index files are empty.
# We must explicitly reset each submodule's index from HEAD and checkout the files.
# Some submodules may fail if their git data is incomplete — safe to skip.
git -C <WORKTREE_PATH> submodule foreach \
    '(git read-tree HEAD && git checkout -- .) 2>/dev/null || echo "SKIP: $name"'

Important: git submodule update (without --init) is sufficient for the first step because the hardlinked modules directory already contains all the submodule git data. Everything is purely local — no network access occurs. However, it only creates .git pointer files in each contrib/ subdirectory without populating the working trees. The subsequent git read-tree HEAD && git checkout -- . in each submodule is required to actually check out the files.

If git submodule update fails with errors about uninitialized submodules, run:

git -C <WORKTREE_PATH> submodule init
git -C <WORKTREE_PATH> submodule update

7. Report results

Report to the user:

• Source repo: <MAIN_REPO>
• Worktree path: <WORKTREE_PATH>
• Branch: <branch-name> (newly created or existing)
• Submodules: either "hardlinked from main repo (independent copies, no network cloning)" or "skipped (text-only task)" depending on the choice in step 5
• Suggest: cd <WORKTREE_PATH>

Examples

• /create-worktree my-feature — Create a new worktree with a new branch my-feature
• /create-worktree fix/issue-12345 — Create a new worktree, branch name can contain slashes (slashes are replaced with dashes in the default directory name)

Notes

• For text-only tasks (docs, comments, typo fixes, changelog entries), step 6 is skipped — git worktree add alone is enough, and the worktree is ready immediately. If you later need to build there, run step 6's commands by hand.
• Submodules use hardlinks (cp -al) — git object files are hardlinked (no extra disk space) but each worktree has its own independent directory structure and config. Modifying submodules in one worktree does not affect others.
• The main repo must have submodules already cloned (git submodule update --init must have been run in the main repo at least once).
• To remove a worktree later:

  rm -rf <WORKTREE_PATH>
  git -C <MAIN_REPO> worktree prune
  

• Build directories are NOT shared — you'll need to set up CMake/build separately in the new worktree.