diff --git a/claude.sh b/claude.sh index 6252e76989..a66ed2abef 100755 --- a/claude.sh +++ b/claude.sh @@ -84,6 +84,46 @@ fi # The entrypoint creates /home/claude-user for the mapped user. CONTAINER_HOME="/home/claude-user" +# --- Git data of a worktree --- +# A worktree's .git file, and the .git files of its submodules, point to the +# main checkout's git directory by host path, absolute or relative. Mount that +# directory and the worktree at their host paths, and start in the worktree's +# host path, so these links resolve in the container. /workspace stays. +HOST_DIR=$(cd "${SCRIPT_DIR}" && pwd -P) +CONTAINER_WORKDIR=/workspace +GIT_TOP="" +GIT_COMMON_DIR="" +if git_top=$(git -C "${HOST_DIR}" rev-parse --show-toplevel 2> /dev/null) && + git_common=$(git -C "${HOST_DIR}" rev-parse --git-common-dir 2> /dev/null); then + GIT_TOP=$(cd "${git_top}" 2> /dev/null && pwd -P) || GIT_TOP="" + GIT_COMMON_DIR=$(cd "${HOST_DIR}" && cd "${git_common}" 2> /dev/null && pwd -P) || + GIT_COMMON_DIR="" +fi + +# True when host path $1 does not overlap a path that the container already uses. +outside_container_paths() { + [[ "$1/" != /workspace/* && "$1/" != "${CONTAINER_HOME}/"* ]] +} + +GIT_MOUNTS=() +# Only for the top of a checkout: a plain folder inside another repository +# must not get that repository's .git. +if [[ "${GIT_TOP}" == "${HOST_DIR}" && -n "${GIT_COMMON_DIR}" && + "${GIT_COMMON_DIR}/" != "${HOST_DIR}/"* ]]; then + if outside_container_paths "${HOST_DIR}" && + outside_container_paths "${GIT_COMMON_DIR}"; then + GIT_MOUNTS=( + -v "${HOST_DIR}:${HOST_DIR}" + -v "${GIT_COMMON_DIR}:${GIT_COMMON_DIR}" + ) + CONTAINER_WORKDIR=${HOST_DIR} + else + echo "Warning: ${HOST_DIR} and its git data in ${GIT_COMMON_DIR} cannot" \ + "both be mounted at their host paths, because one of them is under" \ + "/workspace or ${CONTAINER_HOME}. Git does not work in the container." >&2 + fi +fi + # --- Assemble docker run arguments --- DOCKER_RUN_ARGS=( --rm @@ -91,7 +131,18 @@ DOCKER_RUN_ARGS=( -v "${SCRIPT_DIR}:/workspace" -e "HOST_UID=$(id -u)" -e "HOST_GID=$(id -g)" - -w /workspace + -w "${CONTAINER_WORKDIR}" +) +if [[ ${#GIT_MOUNTS[@]} -gt 0 ]]; then + DOCKER_RUN_ARGS+=("${GIT_MOUNTS[@]}") +fi + +# The host paths of other worktrees do not exist in the container, so git gc +# there would prune their records from the shared .git directory. Stop that. +DOCKER_RUN_ARGS+=( + -e GIT_CONFIG_COUNT=1 + -e GIT_CONFIG_KEY_0=gc.worktreePruneExpire + -e GIT_CONFIG_VALUE_0=never ) # TTY/stdin handling for interactive, CI, and piped-input cases: diff --git a/docker/claude-entrypoint.sh b/docker/claude-entrypoint.sh index 18b77b98c9..28280421eb 100755 --- a/docker/claude-entrypoint.sh +++ b/docker/claude-entrypoint.sh @@ -4,6 +4,13 @@ # inside the container have the correct ownership on the host volume. set -e +# claude.sh starts a git worktree in its host path. env.sh sets paths from +# its own location, so source the copy there to keep the paths the same. +ENV_SH=/workspace/env.sh +if [ -f "${PWD}/env.sh" ]; then + ENV_SH="${PWD}/env.sh" +fi + if [ -n "${HOST_UID}" ] && [ -n "${HOST_GID}" ]; then USER_NAME="claude-user" USER_HOME="/home/${USER_NAME}" @@ -40,9 +47,9 @@ if [ -n "${HOST_UID}" ] && [ -n "${HOST_GID}" ]; then # Set up ORFS environment (PATH to tools, FLOW_HOME, etc.) # Sourced here; inherited through setpriv into all child processes. - if [ -f /workspace/env.sh ]; then + if [ -f "${ENV_SH}" ]; then set +e - . /workspace/env.sh > /dev/null + . "${ENV_SH}" > /dev/null set -e fi @@ -53,9 +60,9 @@ if [ -n "${HOST_UID}" ] && [ -n "${HOST_GID}" ]; then -- "$@" else # No UID/GID mapping requested; run as root - if [ -f /workspace/env.sh ]; then + if [ -f "${ENV_SH}" ]; then set +e - . /workspace/env.sh > /dev/null + . "${ENV_SH}" > /dev/null set -e fi exec "$@" diff --git a/docker/test-claude-sh.sh b/docker/test-claude-sh.sh new file mode 100755 index 0000000000..ea75830b74 --- /dev/null +++ b/docker/test-claude-sh.sh @@ -0,0 +1,130 @@ +#!/usr/bin/env bash +# Check the git mounts that claude.sh adds, with a stub docker command, and +# which env.sh the entrypoint sources. +# Needs bash and git only; no container engine runs. +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +tmp=$(mktemp -d) +trap 'rm -rf "${tmp}"' EXIT + +mkdir -p "${tmp}/bin" "${tmp}/home" +cat > "${tmp}/bin/docker" << 'EOF' +#!/usr/bin/env bash +# The image exists. For "run", print each argument on its own line. +if [[ "$1" == run ]]; then + shift + printf '%s\n' "$@" +fi +EOF +chmod +x "${tmp}/bin/docker" + +git -c init.defaultBranch=main init -q "${tmp}/main" +cp "${SCRIPT_DIR}/../claude.sh" "${tmp}/main/claude.sh" +git -C "${tmp}/main" add claude.sh +git -C "${tmp}/main" -c user.name=test -c user.email=test@example.invalid \ + -c core.hooksPath=/dev/null -c commit.gpgsign=false commit -q -m init +git -C "${tmp}/main" worktree add -q "${tmp}/wt" +common=$(cd "${tmp}/main/.git" && pwd -P) +wt=$(cd "${tmp}/wt" && pwd -P) +mkdir "${tmp}/plain" +cp "${SCRIPT_DIR}/../claude.sh" "${tmp}/plain/claude.sh" +# A plain folder inside another repository, for example a home in git. +git -c init.defaultBranch=main init -q "${tmp}/parent" +mkdir -p "${tmp}/parent/src/orfs" +cp "${SCRIPT_DIR}/../claude.sh" "${tmp}/parent/src/orfs/claude.sh" +parent_git=$(cd "${tmp}/parent/.git" && pwd -P) + +# Git before 2.31 does not know --path-format. rev-parse then prints the +# option as output and exits 0. This wrapper does the same. +mkdir "${tmp}/oldgit" +cat > "${tmp}/oldgit/git" << EOF +#!/usr/bin/env bash +args=() +for arg in "\$@"; do + case "\${arg}" in + --path-format=*) echo "\${arg}" ;; + *) args+=("\${arg}") ;; + esac +done +exec "$(command -v git)" "\${args[@]}" +EOF +chmod +x "${tmp}/oldgit/git" + +run_args() { # Print the docker run arguments of claude.sh in checkout $1. + env -u SSH_AUTH_SOCK HOME="${tmp}/home" PATH="${tmp}/bin:${PATH}" \ + bash "$1/claude.sh" --shell < /dev/null +} + +workdir() { # Print the value of -w in the arguments $1. + grep -A1 -xF -- -w <<< "$1" | tail -n 1 +} + +fail() { + echo "FAIL: $*" >&2 + exit 1 +} + +check_plain() { # check_plain NAME ARGS: only /workspace, prune guard set. + if grep -qF "${common}:" <<< "$2" || grep -qF "${wt}:" <<< "$2"; then + fail "$1: unexpected git mount" + fi + [[ "$(workdir "$2")" == /workspace ]] || fail "$1: workdir is not /workspace" + grep -qxF GIT_CONFIG_VALUE_0=never <<< "$2" || + fail "$1: automatic worktree prune is not disabled" +} + +check_worktree() { # check_worktree NAME ARGS: host-path mounts and workdir. + grep -qxF "${common}:${common}" <<< "$2" || + fail "$1: ${common} is not mounted at its host path" + grep -qxF "${wt}:${wt}" <<< "$2" || + fail "$1: ${wt} is not mounted at its host path" + [[ "$(workdir "$2")" == "${wt}" ]] || fail "$1: workdir is not ${wt}" + grep -qxF GIT_CONFIG_VALUE_0=never <<< "$2" || + fail "$1: automatic worktree prune is not disabled" +} + +check_worktree worktree "$(run_args "${tmp}/wt")" +echo "A worktree gets its host path and the main .git at their host paths" + +check_plain "main checkout" "$(run_args "${tmp}/main")" +echo "A main checkout gets no extra mount" + +check_plain "not a repository" "$(run_args "${tmp}/plain")" +echo "A folder outside git gets no extra mount" + +args=$(run_args "${tmp}/parent/src/orfs") +check_plain "folder in a parent repository" "${args}" +if grep -qF "${parent_git}" <<< "${args}"; then + fail "folder in a parent repository: the parent .git is mounted" +fi +echo "A folder inside another repository does not get its .git" + +check_worktree "old git, worktree" "$(PATH="${tmp}/oldgit:${PATH}" run_args "${tmp}/wt")" +check_plain "old git, main checkout" "$(PATH="${tmp}/oldgit:${PATH}" run_args "${tmp}/main")" +echo "Git without --path-format gives the same mounts" + +# The entrypoint, here without UID mapping, sources env.sh from its start +# directory, which claude.sh sets to the worktree's host path. +mkdir "${tmp}/start" +echo 'export CLAUDE_TEST_ENV="${BASH_SOURCE[0]}"' > "${tmp}/start/env.sh" +sourced() { # Print which env.sh the entrypoint sourced when started in $1. + (cd "$1" && env -u HOST_UID -u HOST_GID \ + bash "${SCRIPT_DIR}/claude-entrypoint.sh" printenv CLAUDE_TEST_ENV) || true +} +[[ "$(sourced "${tmp}/start")" == "${tmp}/start/env.sh" ]] || + fail "entrypoint: env.sh in the start directory is not sourced" +[[ -z "$(sourced "${tmp}/plain")" ]] || + fail "entrypoint: a start directory without env.sh sourced something" +echo "The entrypoint sources env.sh from its start directory" + +# The entrypoint sources env.sh from a host path, which can contain spaces. +mkdir "${tmp}/with space" +cp "${SCRIPT_DIR}/../env.sh" "${tmp}/with space/env.sh" +printf '#!/bin/sh\necho /brew\n' > "${tmp}/bin/brew" # env.sh calls brew on macOS +chmod +x "${tmp}/bin/brew" +flow_home=$(PATH="${tmp}/bin:${PATH}" bash -c \ + '. "$1/env.sh" > /dev/null && echo "${FLOW_HOME}"' _ "${tmp}/with space") +[[ "${flow_home}" == "$(cd "${tmp}/with space" && pwd -P)/flow" ]] || + fail "env.sh in a path with a space: FLOW_HOME is '${flow_home}'" +echo "env.sh works in a path with a space" diff --git a/docs/user/ClaudeCode.md b/docs/user/ClaudeCode.md index c4128cb78f..251bdc68e5 100644 --- a/docs/user/ClaudeCode.md +++ b/docs/user/ClaudeCode.md @@ -93,6 +93,7 @@ are mounted so their contents survive: | `~/.claude/` | `~/.claude/` | Credentials, settings, conversation history | | `~/.cache/bazel-claude/` | `~/.cache/bazel/` | Bazel external dependencies | | `~/.gitconfig` | `~/.gitconfig` | Git identity (read-only) | +| Worktree and main `.git` (worktree only) | Same host paths | Git refs, objects, hooks, config | | `$SSH_AUTH_SOCK` | forwarded | SSH agent for git over SSH | ## Environment variables @@ -132,7 +133,7 @@ Handles UID/GID mapping so files created inside the container have the correct ownership on the host. The entrypoint: 1. Creates a user matching the host UID/GID -2. Sources `env.sh` to set up tool paths +2. Sources `env.sh` to set up tool paths, from the start directory if it has one, else from `/workspace` 3. Drops privileges via `setpriv` before running the command This follows the same pattern as `tools/OpenROAD/etc/docker-entrypoint.sh` @@ -143,13 +144,38 @@ and the `--user` mode in `flow/util/docker_shell`. Wrapper script that assembles the `docker run` command with the correct volume mounts, environment variables, and entrypoint arguments. +When you run `claude.sh` from the top of a git worktree, it also mounts the worktree and the main checkout's `.git` directory at their host paths. +The shell starts in the worktree's host path. +The worktree's `.git` file and the `.git` files of its submodules point to these paths, so git works in the container. +The entrypoint sources `env.sh` from there, so `OPENROAD`, `FLOW_HOME` and `PATH` use the host path too. +Rebuild the image with `./claude.sh --build` to get this entrypoint. +The worktree is also at `/workspace`, but git links in submodules do not resolve from that path. +If one of these host paths is under `/workspace` or `/home/claude-user`, the wrapper prints a warning and adds no mounts, and git does not work in the container. + +The paths of the other worktrees do not exist in the container, so git sees them as stale. +The wrapper sets `gc.worktreePruneExpire=never` in the container, so `git gc` keeps their records. +`git gc` still removes the record of a worktree that has no index file. +Do not run `git worktree prune` or `git worktree repair` in the container: they change the records of the other worktrees. + +The start directory is part of some keys and caches. +Claude Code stores the history of a worktree session under the host path, not under `/workspace`, so earlier `/workspace` sessions of that worktree do not resume. +Bazel uses a new output base, and a CMake build directory that you configured under `/workspace` must be configured again. + +Check the mounts with a stub `docker` command, without a container engine: + +```shell +bash docker/test-claude-sh.sh +``` + ## Security model Claude Code runs with `--dangerously-skip-permissions` **inside** the container, meaning it can execute any shell command without confirmation. The Docker container provides the isolation: -- File access is limited to the mounted repository +- File access is limited to the mounted repository. + From a git worktree, this includes the main checkout's `.git` directory, with the refs and objects of all its worktrees. + It also holds git hooks and config, which run on the host at the next git command, so code in the container can run code on the host. - No access to host system packages, services, or other projects - No access to host network services bound to localhost - `docker kill claude-orfs` stops everything instantly diff --git a/env.sh b/env.sh index e4194c306f..2c84d52c51 100755 --- a/env.sh +++ b/env.sh @@ -1,9 +1,9 @@ #!/usr/bin/env bash function __setpaths() { if [[ "$OSTYPE" == "darwin"* ]]; then - DIR="$(dirname $(perl -e 'use Cwd "abs_path";print abs_path(shift)' "${BASH_SOURCE[0]:-${(%):-%x}}"))" + DIR="$(dirname "$(perl -e 'use Cwd "abs_path";print abs_path(shift)' "${BASH_SOURCE[0]:-${(%):-%x}}")")" else - DIR="$(dirname $(readlink -f "${BASH_SOURCE[0]:-${(%):-%x}}"))" + DIR="$(dirname "$(readlink -f "${BASH_SOURCE[0]:-${(%):-%x}}")")" fi export OPENROAD=${DIR}/tools/OpenROAD