gitpane 1.0.0__py3-none-any.whl

gitpane/history_rewrite/guard.py

@@ -0,0 +1,288 @@
+"""Authorize an exact repository state for history removal."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+from gitpane.config import LOCAL_PREFIX, REMOTE_PREFIX
+from gitpane.history.repository_value import validate_oid
+from gitpane.history_rewrite.graph import affected_branch_closure, ordered_history
+from gitpane.history_rewrite.protocol import check_cancelled, matches_target, read_line
+from gitpane.history_rewrite.value import ChangeKind, RewriteProtectedKind, RewriteRefusal, RewriteRefusalKind
+from gitpane.operation.repository_operation import MERGE_MARKER_BASENAMES, REBASE_MARKER_BASENAMES, REPLAY_MARKER_BASENAMES
+from gitpane.process.process_runner import READ_PROFILE
+from gitpane.reference.reference_edit import reference_signature
+from gitpane.reference.reference_snapshot import REFERENCE_FORMAT, parse_reference_read
+from gitpane.system.path_identity import canonical_path
+from gitpane.worktree.command_sequence import FileTask, GitCommand
+from gitpane.worktree.worktree_file import stat_identity
+from gitpane.worktree.worktree_snapshot import read_index
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.history_rewrite.value import ExportCommit, HistoryAnalysis, RawCommit, RewriteCapture, RewriteTarget
+
+UPSTREAM_CONFIG_PATTERN = r"^(branch\..*\.(remote|merge)|remote\..*\.fetch)$"
+# Git answers the active Git directory, then the common directory that linked worktrees share, one per line.
+GIT_STORAGE_ARGUMENTS = ("rev-parse", "--absolute-git-dir", "--path-format=absolute", "--git-common-dir")
+GIT_ANSWER_LINE_FEED = b"\n"
+
+
+def git_storage_matches(context: RepositoryContext, output: bytes) -> bool:
+    """Tell whether Git's answer to GIT_STORAGE_ARGUMENTS names exactly the Git directory and common directory of the context.
+
+    The folders are compared by identity, never by spelling: Git for Windows writes forward slashes where Python writes
+    backslashes, so a text comparison would refuse the same folder every time. A folder name may hold a line feed, so
+    each answer takes as many lines as the context's own path has; an answer of any other shape is refused.
+    """
+    if not output.endswith(GIT_ANSWER_LINE_FEED):
+        return False
+    lines = output.removesuffix(GIT_ANSWER_LINE_FEED).split(GIT_ANSWER_LINE_FEED)
+    git_dir_line_count = len(os.fsencode(context.git_dir).split(GIT_ANSWER_LINE_FEED))
+    common_git_dir_line_count = len(os.fsencode(context.common_git_dir).split(GIT_ANSWER_LINE_FEED))
+    if len(lines) != git_dir_line_count + common_git_dir_line_count:
+        return False
+    git_dir = os.fsdecode(GIT_ANSWER_LINE_FEED.join(lines[:git_dir_line_count]))
+    common_git_dir = os.fsdecode(GIT_ANSWER_LINE_FEED.join(lines[git_dir_line_count:]))
+    return canonical_path(git_dir) == canonical_path(context.git_dir) and canonical_path(common_git_dir) == canonical_path(context.common_git_dir)
+
+
+def _worktree_entry(record: bytes) -> tuple[str, str | None]:
+    """Interpret one complete native worktree entry without relying on field order."""
+    worktree_dir = None
+    branch = None
+    has_head = False
+    for field in record.split(b"\0"):
+        key, _separator, value = field.partition(b" ")
+        if key == b"worktree":
+            if worktree_dir is not None or not value:
+                raise ValueError("Incomplete worktree listing; refresh the repository")
+            worktree_dir = os.fsdecode(value)
+        elif key == b"branch":
+            if branch is not None or not value:
+                raise ValueError("Incomplete worktree branch; refresh the repository")
+            branch = os.fsdecode(value)
+        elif key == b"HEAD":
+            validate_oid(value.decode("ascii"))
+            has_head = True
+        elif key == b"bare":
+            has_head = True
+    if worktree_dir is None or not has_head:
+        raise ValueError("Incomplete worktree listing; refresh the repository")
+    return worktree_dir, branch
+
+
+def parse_worktree_listing(output: bytes) -> tuple[bytes, ...]:
+    """Normalize complete native worktree records so command ordering grants no authority."""
+    if not output or not output.endswith(b"\0\0"):
+        raise ValueError("Incomplete worktree listing; refresh the repository")
+    records = []
+    for record in output.removesuffix(b"\0\0").split(b"\0\0"):
+        _worktree_entry(record)
+        records.append(b"\0".join(sorted(record.split(b"\0"))))
+    return tuple(sorted(records))
+
+
+def other_worktree_dir_by_branch(context: RepositoryContext, worktrees: tuple[bytes, ...]) -> dict[str, str]:
+    """Identify checked-out branches outside the active worktree, including absorbed submodules.
+
+    Folders are compared by canonical_path, the identity the Git folder check of this guard uses, so the active worktree
+    listed by Git in another letter case or Unicode form is still known as the active one.
+    """
+    active_dir_set = {canonical_path(context.repository_dir)}
+    # Git reports an absorbed submodule's main worktree using its administration directory.
+    # It denotes this checkout only when the active Git directory is also the common one.
+    if canonical_path(context.git_dir) == canonical_path(context.common_git_dir):
+        active_dir_set.add(canonical_path(context.git_dir))
+    worktree_dir_by_branch = {}
+    for record in worktrees:
+        worktree_dir, branch = _worktree_entry(record)
+        if branch and canonical_path(worktree_dir) not in active_dir_set:
+            # The folder is only shown to the user: spell it the system's way, since Git for Windows writes forward slashes.
+            worktree_dir_by_branch[branch] = os.path.normpath(worktree_dir)
+    return worktree_dir_by_branch
+
+
+def _read_local_state(capture: RewriteCapture) -> RewriteCapture:
+    """Capture exact index bytes plus native operation markers without refreshing the index."""
+    index_filename = os.path.join(capture.context.git_dir, "index")
+    index_identity = read_index(index_filename)
+    index_stat = stat_identity(os.lstat(index_filename)) if index_identity is not None else None
+    native_states = []
+    for basename in REBASE_MARKER_BASENAMES + REPLAY_MARKER_BASENAMES + MERGE_MARKER_BASENAMES:
+        if os.path.lexists(os.path.join(capture.context.git_dir, basename)):
+            native_states.append(basename)
+    return replace(capture, index_identity=index_identity, index_stat=index_stat, native_state=tuple(sorted(native_states)))
+
+
+def capture_rewrite_state(capture: RewriteCapture) -> Generator[GitCommand | FileTask, object, RewriteCapture]:
+    """Read local authority in a fixed number of native commands, with no network access."""
+    if capture.context.is_bare:
+        raise RewriteRefusal(RewriteRefusalKind.INCOMPLETE_HISTORY, "A working repository is required; open its worktree before building a preview")
+    authority = yield FileTask(lambda: reference_signature(capture.context))
+    locations = yield GitCommand(list(GIT_STORAGE_ARGUMENTS), profile=READ_PROFILE)
+    if not git_storage_matches(capture.context, locations):
+        raise RewriteRefusal(RewriteRefusalKind.STALE_CAPTURE, "The repository Git storage changed; reopen the repository and build a new preview")
+    initial = yield FileTask(lambda: _read_local_state(capture))
+    output = yield GitCommand(["for-each-ref", "--format=" + REFERENCE_FORMAT, LOCAL_PREFIX, REMOTE_PREFIX])
+    reference = parse_reference_read(output)
+    for entry in reference.references:
+        if entry.full_name.startswith(LOCAL_PREFIX) and entry.symbolic_target is not None:
+            raise RewriteRefusal(RewriteRefusalKind.STALE_CAPTURE, f"Local branch {entry.full_name} is symbolic. Use ordinary local branches before building a new preview.")
+    symbolic_head = (yield GitCommand(["symbolic-ref", "--quiet", "HEAD"], accepted_codes=(0, 1))).rstrip(b"\n")
+    head_ref = os.fsdecode(symbolic_head) if symbolic_head else None
+    if reference.head_ref != head_ref and reference.head_ref is not None:
+        raise RewriteRefusal(RewriteRefusalKind.STALE_CAPTURE, "HEAD changed during the read; build a new preview")
+    local_ref_by_name = {}
+    remote_ref_by_name = {}
+    for name, oid in reference.object_oid_by_name.items():
+        if name.startswith(LOCAL_PREFIX):
+            local_ref_by_name[name] = oid
+        elif name.startswith(REMOTE_PREFIX):
+            remote_ref_by_name[name] = oid
+    upstream_config = yield GitCommand(["config", "--null", "--get-regexp", UPSTREAM_CONFIG_PATTERN], accepted_codes=(0, 1))
+    worktree_output = yield GitCommand(["worktree", "list", "--porcelain", "-z"])
+    worktrees = parse_worktree_listing(worktree_output)
+    current = yield FileTask(lambda: _read_local_state(capture))
+    if (initial.index_identity, initial.index_stat, initial.native_state) != (current.index_identity, current.index_stat, current.native_state):
+        raise RewriteRefusal(RewriteRefusalKind.STALE_CAPTURE, "The index or native operation changed during the read; build a new preview")
+    shared_path = (yield GitCommand(["rev-parse", "--path-format=absolute", "--shared-index-path"])).removesuffix(b"\n")
+    shared_index_filename = os.fsdecode(shared_path)
+    shared_identity = (yield FileTask(lambda: read_index(shared_index_filename))) if shared_index_filename else None
+    if (yield FileTask(lambda: reference_signature(capture.context))) != authority:
+        raise RewriteRefusal(RewriteRefusalKind.STALE_CAPTURE, "References, configuration or worktrees changed during the read; build a new preview")
+    return replace(current, head_ref=head_ref, local_ref_by_name=local_ref_by_name, remote_ref_by_name=remote_ref_by_name,
+                   upstream_by_name=reference.upstream_by_name, upstream_config=upstream_config, worktrees=worktrees, complete=True,
+                   shared_index_filename=shared_index_filename, shared_index_identity=shared_identity)
+
+
+def publication_authority(capture: RewriteCapture) -> tuple:
+    """Bracket the final native reads with local evidence of refs, configuration and native operations."""
+    local = _read_local_state(capture)
+    shared_identity = read_index(capture.shared_index_filename) if capture.shared_index_filename else None
+    return reference_signature(capture.context), local.index_identity, local.index_stat, local.native_state, shared_identity
+
+
+def validate_publication_authority(capture: RewriteCapture, expected: tuple) -> None:
+    """Reject local authority changes while the collective reference transaction waits to launch."""
+    if publication_authority(capture) != expected:
+        raise RewriteRefusal(RewriteRefusalKind.STALE_CAPTURE, "Repository authority changed before publication; build a new preview")
+
+
+def validate_rewrite_capture(expected: RewriteCapture, observed: RewriteCapture) -> None:
+    """Refuse every authority change, including a newly created ref or an absent index."""
+    if not expected.complete or not observed.complete or expected != observed:
+        raise RewriteRefusal(RewriteRefusalKind.STALE_CAPTURE, "Preview is out of date. Repository, HEAD, references, index, upstream settings or worktrees changed; build a new preview")
+
+
+def protected_target_refusal(target: RewriteTarget, path: bytes, mode: bytes, commit_oid: str | None = None) -> None:
+    """Refuse submodule boundaries or metadata with their exact historical witness."""
+    _parent, _separator, basename = path.rpartition(b"/")
+    protected_kind = RewriteProtectedKind.SUBMODULE if mode == b"160000" else RewriteProtectedKind.MODULE_CONFIGURATION if basename == b".gitmodules" else None
+    if protected_kind is None:
+        return
+    if not matches_target(path, target) and not (mode == b"160000" and target.path.startswith(path + b"/")):
+        return
+    witness = f"commit {commit_oid} contains" if commit_oid else "it contains"
+    raise RewriteRefusal(RewriteRefusalKind.PROTECTED_TARGET,
+                         f"Cannot remove {target.path!r}: {witness} {path!r}, which is {protected_kind.value}. Choose a path that does not include a submodule or .gitmodules. No history was changed.",
+                         path=path, commit_oid=commit_oid)
+
+
+def validate_history_protection(capture: RewriteCapture, target: RewriteTarget, records: list[ExportCommit], raw_by_oid: dict[str, RawCommit],
+                                cancelled: Callable[[], bool] | None = None) -> None:
+    """Check protected entries only in the final affected ancestry, including deleted gitlinks."""
+    ordered_records = ordered_history(records, raw_by_oid, cancelled)
+    included_oid_set = affected_branch_closure(capture, target, ordered_records, raw_by_oid, cancelled)
+    for record in ordered_records:
+        check_cancelled(cancelled)
+        if record.oid not in included_oid_set:
+            continue
+        for change in record.changes:
+            if change.kind == ChangeKind.MODIFY:
+                protected_target_refusal(target, change.path, change.mode, record.oid)
+
+
+def validate_initial_state(capture: RewriteCapture, target: RewriteTarget) -> Generator[GitCommand, bytes]:
+    """Reject unsafe source states while allowing unrelated staged or unstaged changes."""
+    if capture.head_ref is None:
+        raise RewriteRefusal(RewriteRefusalKind.DETACHED_HEAD, "HEAD is detached. Check out a local branch, then build a new preview.")
+    if capture.head_ref not in capture.local_ref_by_name:
+        raise RewriteRefusal(RewriteRefusalKind.UNBORN_BRANCH, f"Branch {capture.head_ref} is unborn. Create a commit before building a new preview.", branch=capture.head_ref)
+    if capture.native_state:
+        operation = ", ".join(capture.native_state)
+        raise RewriteRefusal(RewriteRefusalKind.NATIVE_OPERATION, f"This repository is busy with {operation}. Finish or stop that operation, then build a new preview.")
+    protected_target_refusal(target, target.path, b"")
+    listing = yield GitCommand(["ls-files", "--stage", "-z"])
+    for record in listing.removesuffix(b"\0").split(b"\0") if listing else ():
+        metadata, separator, path = record.partition(b"\t")
+        if not separator:
+            raise ValueError("Incomplete index listing; build a new preview")
+        mode, _oid, stage = metadata.split(b" ")
+        if stage != b"0":
+            raise RewriteRefusal(RewriteRefusalKind.UNMERGED_INDEX, f"The index has conflicts at {path!r}. Resolve the conflicts, then build a new preview.", path=path)
+        protected_target_refusal(target, path, mode)
+    staged = yield GitCommand(["diff", "--cached", "--name-only", "-z", "--no-renames", "--ita-visible-in-index", "--ignore-submodules=none",
+                               capture.local_ref_by_name[capture.head_ref], "--"])
+    for path in staged.removesuffix(b"\0").split(b"\0") if staged else ():
+        if matches_target(path, target):
+            raise RewriteRefusal(RewriteRefusalKind.STAGED_TARGET,
+                                 f"{path!r} has staged changes. Unstage this path first so its staged version is not lost, then build a new preview. Other staged files can stay staged.", path=path)
+
+
+def validate_branch_state(capture: RewriteCapture, analysis: HistoryAnalysis, ancestry_filename: str,
+                          cancelled: Callable[[], bool] | None = None) -> HistoryAnalysis:
+    """Check all moving branches against known upstream ancestry plus other worktrees."""
+    parent_oids_by_oid = {}
+    with open(ancestry_filename, "rb") as stream:
+        while line := read_line(stream, cancelled):
+            oid, *parent_oids = line.decode("ascii").split()
+            parent_oids_by_oid[validate_oid(oid)] = tuple(validate_oid(parent) for parent in parent_oids)
+
+    def ancestor_set(tip_oid: str) -> set[str]:
+        """Visit each ancestor once, refusing incomplete local knowledge."""
+        visited_oid_set = set()
+        pending_oids = [tip_oid]
+        while pending_oids:
+            check_cancelled(cancelled)
+            oid = pending_oids.pop()
+            if oid in visited_oid_set:
+                continue
+            if oid not in parent_oids_by_oid:
+                raise RewriteRefusal(RewriteRefusalKind.INCOMPLETE_HISTORY, f"Missing history at {oid}; make the missing objects available, then build a new preview. No fetch was performed.", commit_oid=oid)
+            visited_oid_set.add(oid)
+            pending_oids.extend(parent_oids_by_oid[oid])
+        return visited_oid_set
+
+    worktree_dir_by_branch = other_worktree_dir_by_branch(capture.context, capture.worktrees)
+    changed_oid_set = set()
+    for oid, replacement in analysis.replacement_by_oid.items():
+        if oid != replacement:
+            changed_oid_set.add(oid)
+    published_oid_set_by_ref = {}
+    for name, oid in capture.remote_ref_by_name.items():
+        published_oid_set_by_ref[name] = ancestor_set(oid) & changed_oid_set
+    branches = []
+    for branch in analysis.branches:
+        if branch.name in worktree_dir_by_branch:
+            raise RewriteRefusal(RewriteRefusalKind.OTHER_WORKTREE,
+                                 f"{branch.name} is checked out in another worktree: {worktree_dir_by_branch[branch.name]}. Release that branch in the other worktree, then build a new preview. GitPane will not change that worktree.",
+                                 branch=branch.name)
+        local_ancestor_set = ancestor_set(branch.old_oid)
+        if branch.upstream:
+            upstream_oid = capture.remote_ref_by_name.get(branch.upstream, capture.local_ref_by_name.get(branch.upstream))
+            if upstream_oid is None:
+                raise RewriteRefusal(RewriteRefusalKind.INCOMPLETE_HISTORY, f"The known upstream {branch.upstream} of {branch.name} is unavailable. Make its history available, then build a new preview. No fetch was performed.", branch=branch.name)
+            if upstream_oid not in local_ancestor_set:
+                raise RewriteRefusal(RewriteRefusalKind.BEHIND_UPSTREAM,
+                                     f"{branch.name} is behind {branch.upstream} according to the last fetch. Update that local branch before removing this path from history, then build a new preview.", branch=branch.name)
+        remote_refs = []
+        for name, published_oid_set in published_oid_set_by_ref.items():
+            if published_oid_set & local_ancestor_set:
+                remote_refs.append(name)
+        branches.append(replace(branch, remote_refs=tuple(sorted(remote_refs))))
+    return replace(analysis, branches=tuple(branches))

gitpane/history_rewrite/index.py

@@ -0,0 +1,125 @@
+"""Prepare a verified private index without changing the working repository."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+from gitpane.config import EXACT_PATH_CASE_ARGUMENTS, GIT_ALTERNATE_OBJECT_ENVIRONMENT_NAME, SUBMODULE_RECURSION_OFF_ARGUMENTS
+from gitpane.history.repository_value import validate_oid
+from gitpane.history_rewrite.protocol import check_cancelled, matches_target
+from gitpane.history_rewrite.value import RewriteIndex, RewriteRefusal, RewriteRefusalKind
+from gitpane.process.process_runner import LOCAL_WRITE_PROFILE, READ_PROFILE
+from gitpane.worktree.command_sequence import FileTask, GitCommand
+from gitpane.worktree.worktree_snapshot import read_index
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+    from gitpane.history_rewrite.value import RewriteCapture, RewriteTarget
+
+# Native debug output is deliberately checked rather than guessed: Git documents it as unstable.
+# Unknown formats must refuse publication, because flags cannot otherwise be verified faithfully.
+INDEX_DEBUG_PATTERN = re.compile(rb"  ctime: \d+:\d+\n  mtime: \d+:\d+\n  dev: \d+\tino: \d+\n  uid: \d+\tgid: \d+\n  size: \d+\tflags: (?P<flags>[0-9a-fA-F]+)\n")
+INDEX_ASSUME_UNCHANGED_FLAG = 0x8000
+INDEX_INTENT_TO_ADD_FLAG = 1 << 29
+INDEX_SKIP_WORKTREE_FLAG = 1 << 30
+INDEX_PERSISTENT_FLAG_MASK = INDEX_ASSUME_UNCHANGED_FLAG | INDEX_INTENT_TO_ADD_FLAG | INDEX_SKIP_WORKTREE_FLAG
+INDEX_LIST_ARGUMENTS = ["ls-files", "--stage", "--debug", "-z"]
+
+
+def parse_index_entry(output: bytes, cancelled: Callable[[], bool] | None = None) -> dict[tuple[bytes, bytes], tuple[bytes, str, int]]:
+    """Read literal paths, stages and persistent flags from a complete native listing."""
+    entry_by_key = {}
+    position = 0
+    while position < len(output):
+        check_cancelled(cancelled)
+        end = output.find(b"\0", position)
+        if end < 0:
+            raise RewriteRefusal(RewriteRefusalKind.UNSUPPORTED_INDEX, "Incomplete private index listing; no history was changed")
+        metadata, separator, path = output[position:end].partition(b"\t")
+        debug = INDEX_DEBUG_PATTERN.match(output, end + 1)
+        if not separator or not path or debug is None:
+            raise RewriteRefusal(RewriteRefusalKind.UNSUPPORTED_INDEX, "Cannot verify this Git index format without losing entry flags; no history was changed")
+        mode, oid, stage = metadata.split(b" ")
+        key = (path, stage)
+        if key in entry_by_key:
+            raise RewriteRefusal(RewriteRefusalKind.UNSUPPORTED_INDEX, "Duplicate private index entry; no history was changed")
+        entry_by_key[key] = (mode, validate_oid(oid.decode("ascii")), int(debug.group("flags"), 16) & INDEX_PERSISTENT_FLAG_MASK)
+        position = debug.end()
+    return entry_by_key
+
+
+def verify_candidate_index(target: RewriteTarget, original: bytes, candidate: bytes, cancelled: Callable[[], bool] | None = None) -> None:
+    """Require every retained entry to keep its mode, blob, stage and persistent flags."""
+    expected_by_key = {}
+    for key, entry in parse_index_entry(original, cancelled).items():
+        path, _stage = key
+        if not matches_target(path, target):
+            expected_by_key[key] = entry
+    if parse_index_entry(candidate, cancelled) != expected_by_key:
+        raise RewriteRefusal(RewriteRefusalKind.UNSUPPORTED_INDEX, "The candidate index changed unrelated entries or flags; no history was changed. Inspect the index before building another preview.")
+
+
+def index_digest(filename: str) -> bytes | None:
+    """Distinguish an absent index from every exact byte representation used for publication."""
+    content = read_index(filename)
+    return hashlib.sha256(content).digest() if content is not None else None
+
+
+def _copy_captured_index(capture: RewriteCapture, operation_dir: str, private_dir: str) -> RewriteIndex:
+    """Materialize only captured index bytes and its shared base inside owned private storage."""
+    source_filename = os.path.join(capture.context.git_dir, "index")
+    if read_index(source_filename) != capture.index_identity:
+        raise RewriteRefusal(RewriteRefusalKind.STALE_CAPTURE, "The index changed before candidate preparation; build a new preview")
+    original_filename = os.path.join(operation_dir, "original.index")
+    candidate_filename = os.path.join(private_dir, "index")
+    os.mkdir(os.path.join(operation_dir, "index-worktree"))
+    if capture.shared_index_filename:
+        shared_content = read_index(capture.shared_index_filename)
+        if shared_content is None or shared_content != capture.shared_index_identity:
+            raise RewriteRefusal(RewriteRefusalKind.STALE_CAPTURE, "The shared index changed before candidate preparation; build a new preview")
+        with open(os.path.join(private_dir, os.path.basename(capture.shared_index_filename)), "xb") as stream:
+            stream.write(shared_content)
+    if capture.index_identity is not None:
+        for filename in (original_filename, candidate_filename):
+            with open(filename, "xb") as stream:
+                stream.write(capture.index_identity)
+    return RewriteIndex(original_filename, candidate_filename, index_digest(original_filename), index_digest(candidate_filename))
+
+
+def _write_removal_request(filename: str, target: RewriteTarget, original: bytes, cancelled: Callable[[], bool] | None) -> bool:
+    """Pass only exact indexed target paths to native Git through NUL-framed input."""
+    paths = []
+    for path, _stage in parse_index_entry(original, cancelled):
+        if matches_target(path, target):
+            paths.append(path)
+    with open(filename, "xb") as stream:
+        for path in sorted(paths):
+            check_cancelled(cancelled)
+            stream.write(path + b"\0")
+    return bool(paths)
+
+
+def prepare_candidate_index(capture: RewriteCapture, target: RewriteTarget, operation_dir: str, private_dir: str,
+                            cancelled: Callable[[], bool] | None = None) -> Generator[GitCommand | FileTask, object, RewriteIndex]:
+    """Remove target entries in private Git storage, preserving every unrelated staged decision."""
+    check_cancelled(cancelled)
+    index = yield FileTask(lambda: _copy_captured_index(capture, operation_dir, private_dir))
+    original = yield GitCommand(INDEX_LIST_ARGUMENTS.copy(), profile=READ_PROFILE)
+    request_filename = os.path.join(operation_dir, "remove-index.in")
+    remove = yield FileTask(lambda: _write_removal_request(request_filename, target, original, cancelled))
+    environment_by_name = {"GIT_INDEX_FILE": index.candidate_filename, GIT_ALTERNATE_OBJECT_ENVIRONMENT_NAME: os.path.join(capture.context.common_git_dir, "objects")}
+    private_arguments = [*SUBMODULE_RECURSION_OFF_ARGUMENTS, *EXACT_PATH_CASE_ARGUMENTS, "--git-dir=" + private_dir, "--work-tree=" + os.path.join(operation_dir, "index-worktree"),
+                         "-c", "core.bare=false", "-c", "core.splitIndex=false", "-c", "core.sparseCheckout=false", "-c", "index.sparse=false"]
+    if remove:
+        yield GitCommand([*private_arguments, "update-index", "--no-split-index", "--force-remove", "-z", "--stdin"], stdin_filename=request_filename,
+                         environment_by_name=environment_by_name, profile=LOCAL_WRITE_PROFILE, before_start=lambda: check_cancelled(cancelled))
+    # The candidate index and the private repository are deleted with the private folder as soon as this read ends.
+    candidate = yield GitCommand([*EXACT_PATH_CASE_ARGUMENTS, "-C", private_dir, *INDEX_LIST_ARGUMENTS], environment_by_name=environment_by_name, profile=READ_PROFILE,
+                                 opens_files_deleted_at_end=True)
+    yield FileTask(lambda: verify_candidate_index(target, original, candidate, cancelled))
+    return replace(index, candidate_identity=(yield FileTask(lambda: index_digest(index.candidate_filename))))