grit_lib/

split_index.rs

//! Split index: `link` extension and `sharedindex.<sha1>` (Git `split-index.c`).

use crate::config::ConfigSet;
use crate::error::{Error, Result};
use crate::ewah_bitmap::EwahBitmap;
use crate::git_date::approx::approxidate_careful;
use crate::git_path::CanonicalizeExt;
use crate::index::{Index, IndexEntry};
use crate::objects::{HashAlgo, ObjectId};
use std::fs;
use std::io;
use std::path::{Path, PathBuf};

/// Split-index metadata carried on an [`Index`] (in-memory; bitmaps cleared after merge/write).
#[derive(Debug, Clone)]
pub(crate) struct SplitIndexLink {
    /// OID of the shared index file (`sharedindex.<hex>`).
    pub base_oid: ObjectId,
    pub delete_bitmap: Option<EwahBitmap>,
    pub replace_bitmap: Option<EwahBitmap>,
}

fn parse_shared_repository_perm(raw: Option<&str>) -> i32 {
    const PERM_UMASK: i32 = 0;
    const OLD_PERM_GROUP: i32 = 1;
    const OLD_PERM_EVERYBODY: i32 = 2;
    const PERM_GROUP: i32 = 0o660;
    const PERM_EVERYBODY: i32 = 0o664;

    let Some(value) = raw.map(str::trim).filter(|s| !s.is_empty()) else {
        return PERM_UMASK;
    };
    if value.eq_ignore_ascii_case("umask") {
        return PERM_UMASK;
    }
    if value.eq_ignore_ascii_case("group") {
        return PERM_GROUP;
    }
    if value.eq_ignore_ascii_case("all")
        || value.eq_ignore_ascii_case("world")
        || value.eq_ignore_ascii_case("everybody")
    {
        return PERM_EVERYBODY;
    }
    if !value.is_empty() && value.chars().all(|c| ('0'..='7').contains(&c)) {
        if let Ok(i) = i32::from_str_radix(value, 8) {
            return match i {
                PERM_UMASK => PERM_UMASK,
                OLD_PERM_GROUP => PERM_GROUP,
                OLD_PERM_EVERYBODY => PERM_EVERYBODY,
                _ => {
                    if (i & 0o600) != 0o600 {
                        return PERM_UMASK;
                    }
                    -(i & 0o666)
                }
            };
        }
    }
    if value.eq_ignore_ascii_case("true") {
        PERM_GROUP
    } else {
        PERM_UMASK
    }
}

#[cfg(unix)]
fn calc_shared_perm(shared_repo: i32, mode: u32) -> u32 {
    let tweak = if shared_repo < 0 {
        (-shared_repo) as u32
    } else {
        shared_repo as u32
    };

    let mut new_mode = if shared_repo < 0 {
        (mode & !0o777) | tweak
    } else {
        mode | tweak
    };

    if mode & 0o200 == 0 {
        new_mode &= !0o222;
    }
    if mode & 0o100 != 0 {
        new_mode |= (new_mode & 0o444) >> 2;
    }

    new_mode
}

#[cfg(unix)]
fn adjust_shared_perm_file(path: &Path, shared_repo: i32) -> io::Result<()> {
    if shared_repo == 0 {
        return Ok(());
    }
    use std::os::unix::fs::PermissionsExt;
    let meta = fs::metadata(path)?;
    let old = meta.permissions().mode();
    let new_mode = calc_shared_perm(shared_repo, old);
    if (old ^ new_mode) & 0o777 != 0 {
        let mut p = meta.permissions();
        p.set_mode(new_mode & 0o777);
        fs::set_permissions(path, p)?;
    }
    Ok(())
}

#[cfg(not(unix))]
fn adjust_shared_perm_file(_path: &Path, _shared_repo: i32) -> io::Result<()> {
    Ok(())
}

/// Apply `core.sharedRepository` to the file that was just written.
///
/// When `staged_lock_path` is set, bytes were staged in the lock file (flush without commit); do
/// not chmod the live index path until [`crate::index::IndexLock::commit_replace_index`].
fn adjust_shared_perm_written_index(
    index_path: &Path,
    staged_lock_path: Option<&Path>,
    shared_repo: i32,
) -> Result<()> {
    let target = staged_lock_path.unwrap_or(index_path);
    adjust_shared_perm_file(target, shared_repo).map_err(Error::Io)
}

fn staged_lock_path_buf_for_perm(
    existing_lock: Option<&crate::index::IndexLock>,
    commit_lock: bool,
) -> Option<PathBuf> {
    if commit_lock {
        None
    } else {
        existing_lock.map(|lock| lock.lock_path.clone())
    }
}

/// Compare on-disk-relevant fields (Git `compare_ce_content` in `split-index.c`).
pub(crate) fn entries_equal_for_split(a: &IndexEntry, b: &IndexEntry) -> bool {
    let mask: u16 = 0xF000 | 0x8000;
    let a_flags = a.flags & mask;
    let b_flags = b.flags & mask;
    let ext_mask: u16 = 0x7000;
    let a_ext = a.flags_extended.unwrap_or(0) & ext_mask;
    let b_ext = b.flags_extended.unwrap_or(0) & ext_mask;
    a.ctime_sec == b.ctime_sec
        && a.ctime_nsec == b.ctime_nsec
        && a.mtime_sec == b.mtime_sec
        && a.mtime_nsec == b.mtime_nsec
        && a.dev == b.dev
        && a.ino == b.ino
        && a.mode == b.mode
        && a.uid == b.uid
        && a.gid == b.gid
        && a.size == b.size
        && a.oid == b.oid
        && a_flags == b_flags
        && a_ext == b_ext
}

fn replace_positions_in_order(link: &SplitIndexLink) -> Vec<usize> {
    let Some(bm) = &link.replace_bitmap else {
        return Vec::new();
    };
    if bm.bit_size == 0 {
        return Vec::new();
    }
    let mut v = Vec::new();
    bm.each_set_bit(|p| v.push(p));
    v
}

fn bitmap_has_bit(bm: &EwahBitmap, i: usize) -> bool {
    let mut found = false;
    bm.each_set_bit(|pos| {
        if pos == i {
            found = true;
        }
    });
    found
}

/// Merge split index + shared base into `index.entries` (Git `merge_base_index`).
pub(crate) fn merge_split_into_index(
    index: &mut Index,
    link: SplitIndexLink,
    base_entries: Vec<IndexEntry>,
) -> Result<()> {
    let saved = std::mem::take(&mut index.entries);
    let replace_pos = replace_positions_in_order(&link);
    let stubs: Vec<IndexEntry> = saved
        .iter()
        .filter(|e| e.path.is_empty())
        .cloned()
        .collect();
    if stubs.len() != replace_pos.len() {
        return Err(Error::IndexError(format!(
            "split index: expected {} replacement stubs, found {}",
            replace_pos.len(),
            stubs.len()
        )));
    }
    let mut stub_iter = stubs.into_iter();
    let rest: Vec<IndexEntry> = saved.into_iter().filter(|e| !e.path.is_empty()).collect();

    let delete = &link.delete_bitmap;
    let replace = &link.replace_bitmap;

    let mut merged: Vec<IndexEntry> = Vec::new();

    for (i, mut base_e) in base_entries.into_iter().enumerate() {
        if delete
            .as_ref()
            .is_some_and(|b| b.bit_size > 0 && bitmap_has_bit(b, i))
        {
            continue;
        }
        if replace
            .as_ref()
            .is_some_and(|b| b.bit_size > 0 && bitmap_has_bit(b, i))
        {
            let Some(rep) = stub_iter.next() else {
                return Err(Error::IndexError(
                    "split index: missing replacement entry".to_owned(),
                ));
            };
            let mut e = rep;
            e.path = base_e.path.clone();
            e.base_index_pos = (i + 1) as u32;
            merged.push(e);
        } else {
            base_e.base_index_pos = (i + 1) as u32;
            merged.push(base_e);
        }
    }

    if stub_iter.next().is_some() {
        return Err(Error::IndexError(
            "split index: too many replacement stubs".to_owned(),
        ));
    }

    for mut e in rest {
        e.base_index_pos = 0;
        merged.push(e);
    }

    merged.sort_by(|a, b| a.path.cmp(&b.path).then_with(|| a.stage().cmp(&b.stage())));
    index.entries = merged;
    Ok(())
}

/// Parse the `link` extension payload (Git `read_link_extension`).
pub(crate) fn parse_link_extension(data: &[u8], algo: HashAlgo) -> Result<SplitIndexLink> {
    let hash_len = algo.len();
    if data.len() < hash_len {
        return Err(Error::IndexError(
            "corrupt link extension (too short)".to_owned(),
        ));
    }
    let base_oid = ObjectId::from_bytes(&data[..hash_len])?;
    let mut rest = &data[hash_len..];
    if rest.is_empty() {
        return Ok(SplitIndexLink {
            base_oid,
            delete_bitmap: None,
            replace_bitmap: None,
        });
    }
    let Some((del, consumed)) = EwahBitmap::deserialize_prefix(rest) else {
        return Err(Error::IndexError(
            "corrupt delete bitmap in link extension".to_owned(),
        ));
    };
    rest = &rest[consumed..];
    let Some((rep, consumed2)) = EwahBitmap::deserialize_prefix(rest) else {
        return Err(Error::IndexError(
            "corrupt replace bitmap in link extension".to_owned(),
        ));
    };
    rest = &rest[consumed2..];
    if !rest.is_empty() {
        return Err(Error::IndexError(
            "garbage at the end of link extension".to_owned(),
        ));
    }
    Ok(SplitIndexLink {
        base_oid,
        delete_bitmap: Some(del),
        replace_bitmap: Some(rep),
    })
}

/// Serialize `link` extension: base OID plus two EWAH bitmaps (Git always writes both after `prepare_to_write_split_index`).
pub(crate) fn serialize_link_extension_payload(
    base_oid: &ObjectId,
    delete: &EwahBitmap,
    replace: &EwahBitmap,
) -> Vec<u8> {
    let mut out = base_oid.as_bytes().to_vec();
    delete.serialize(&mut out);
    replace.serialize(&mut out);
    out
}

/// Resolve path to shared index file (Git `read_index_from`), with fallbacks when `git_dir` does
/// not match the repo that owns the index (nested trash repo + `GIT_INDEX_FILE`).
fn resolve_shared_index_file(git_dir: &Path, index_path: &Path, base_oid: &ObjectId) -> PathBuf {
    let name = format!("sharedindex.{}", base_oid.to_hex());
    let primary = git_dir.join(&name);

    let try_path = |p: PathBuf| -> Option<PathBuf> {
        if p.is_file() {
            Some(p)
        } else {
            None
        }
    };

    if let Some(p) = try_path(primary.clone()) {
        return p;
    }
    if let Some(parent) = index_path.parent() {
        if let Some(p) = try_path(parent.join(&name)) {
            return p;
        }
    }
    {
        let cwd = crate::environment::Environment::empty().cwd.clone();
        let mut dir = cwd.as_path();
        loop {
            if let Some(p) = try_path(dir.join(".git").join(&name)) {
                return p;
            }
            let Some(p) = dir.parent() else {
                break;
            };
            dir = p;
        }
    }
    if let Some(d) = index_path.parent() {
        if let Ok(read) = fs::read_dir(d) {
            for ent in read.flatten() {
                let Ok(ft) = ent.file_type() else {
                    continue;
                };
                if !ft.is_dir() {
                    continue;
                }
                if let Some(p) = try_path(ent.path().join(".git").join(&name)) {
                    return p;
                }
            }
        }
    }
    primary
}

/// Read the trailing checksum of the index file at `path`, which is the oid a split index's
/// `link` extension names it by.
fn read_index_trailer(path: &Path, algo: HashAlgo) -> Result<ObjectId> {
    use std::io::{Read, Seek, SeekFrom};
    let hash_len = algo.len();
    let mut file = fs::File::open(path).map_err(Error::Io)?;
    file.seek(SeekFrom::End(-(hash_len as i64)))
        .map_err(Error::Io)?;
    let mut trailer = vec![0u8; hash_len];
    file.read_exact(&mut trailer).map_err(Error::Io)?;
    ObjectId::from_bytes(&trailer)
}

pub(crate) fn hash_index_body(body: &[u8], algo: HashAlgo) -> ObjectId {
    ObjectId::from_bytes(&algo.checksum_digest(body))
        .unwrap_or_else(|_| unreachable!("checksum digest length matches object id"))
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum SplitIndexConfig {
    Disabled,
    Unset,
    Enabled,
}

pub(crate) fn split_index_config(cfg: &ConfigSet) -> SplitIndexConfig {
    match cfg.get("core.splitIndex") {
        None => SplitIndexConfig::Unset,
        Some(v) => {
            let t = v.trim();
            if t.eq_ignore_ascii_case("false") || t == "0" {
                SplitIndexConfig::Disabled
            } else if t.eq_ignore_ascii_case("true") || t == "1" {
                SplitIndexConfig::Enabled
            } else {
                SplitIndexConfig::Unset
            }
        }
    }
}

pub(crate) fn max_percent_split_change(cfg: &ConfigSet) -> i32 {
    match cfg.get("splitIndex.maxPercentChange") {
        None => -1,
        Some(v) => v.trim().parse::<i32>().unwrap_or(-1),
    }
}

fn default_max_percent() -> i32 {
    20
}

pub(crate) fn should_rebuild_shared_index(index: &Index, cfg: &ConfigSet) -> bool {
    let max_split = max_percent_split_change(cfg);
    let max_split = match max_split {
        -1 => default_max_percent(),
        0 => return true,
        100 => return false,
        n => n,
    };
    let mut not_shared = 0u64;
    for e in &index.entries {
        if e.base_index_pos == 0 {
            not_shared += 1;
        }
    }
    let total = index.entries.len() as u64;
    if total == 0 {
        return false;
    }
    total * (max_split as u64) < not_shared * 100
}

pub(crate) fn git_test_split_index_env() -> bool {
    crate::environment::Environment::empty()
        .var("GIT_TEST_SPLIT_INDEX")
        .map(|v| {
            let t = v.trim();
            t == "1" || t.eq_ignore_ascii_case("true") || t.eq_ignore_ascii_case("yes")
        })
        .unwrap_or(false)
}

/// Whether cache-tree verification should run on index write.
///
/// Upstream's `write_locked_index` gates this on `git_env_bool("GIT_TEST_CHECK_CACHE_TREE", 0)`, but
/// the upstream test harness (`test-lib.sh`) exports the variable as `true` by default — so in
/// practice the check is *on* unless a test explicitly sets it to a falsy value. Grit mirrors that
/// effective default: verification runs unless `GIT_TEST_CHECK_CACHE_TREE` is explicitly falsy
/// (`0`/`false`/`no`/empty). This only ever rejects a genuinely corrupt cache-tree (e.g. one primed
/// from a tree with duplicate path entries — `t4058-diff-duplicates`); well-formed trees always
/// verify cleanly.
pub(crate) fn git_test_check_cache_tree() -> bool {
    match crate::environment::Environment::empty().var("GIT_TEST_CHECK_CACHE_TREE") {
        Some(v) => {
            let t = v.trim();
            !(t.is_empty()
                || t == "0"
                || t.eq_ignore_ascii_case("false")
                || t.eq_ignore_ascii_case("no"))
        }
        None => true,
    }
}

pub(crate) fn git_test_split_index_force_reorder(base_oid: &ObjectId) -> bool {
    git_test_split_index_env() && (base_oid.as_bytes()[0] & 15) < 6
}

pub(crate) fn shared_index_expire_threshold(cfg: &ConfigSet) -> u64 {
    let raw = cfg
        .get("splitIndex.sharedIndexExpire")
        .map(|s| s.trim().to_owned());
    let spec = raw
        .as_deref()
        .filter(|s| !s.is_empty())
        .unwrap_or("2.weeks.ago");
    if spec.eq_ignore_ascii_case("never") {
        return 0;
    }
    let mut err = 0;
    approxidate_careful(spec, Some(&mut err))
}

fn should_delete_shared_index(path: &Path, expiration: u64) -> bool {
    if expiration == 0 {
        return false;
    }
    let Ok(meta) = fs::metadata(path) else {
        return false;
    };
    #[cfg(unix)]
    {
        use std::os::unix::fs::MetadataExt;
        meta.mtime() as u64 <= expiration
    }
    #[cfg(not(unix))]
    {
        let _ = meta;
        false
    }
}

pub(crate) fn clean_stale_shared_index_files(git_dir: &Path, current_hex: &str, cfg: &ConfigSet) {
    let expiration = shared_index_expire_threshold(cfg);
    let Ok(read_dir) = fs::read_dir(git_dir) else {
        return;
    };
    for ent in read_dir.flatten() {
        let name = ent.file_name();
        let Some(name) = name.to_str() else {
            continue;
        };
        let Some(hex) = name.strip_prefix("sharedindex.") else {
            continue;
        };
        if hex == current_hex {
            continue;
        }
        let path = ent.path();
        if should_delete_shared_index(&path, expiration) {
            let _ = fs::remove_file(&path);
        }
    }
}

pub(crate) fn freshen_shared_index(path: &Path) {
    let _ = filetime_set_to_now(path);
}

#[cfg(unix)]
fn filetime_set_to_now(path: &Path) -> io::Result<()> {
    use std::time::{Duration, UNIX_EPOCH};
    let t = UNIX_EPOCH + Duration::from_secs(crate::git_date::tm::process_wall_clock_sec() as u64);
    let ft = filetime::FileTime::from_system_time(t);
    filetime::set_file_mtime(path, ft)
}

#[cfg(not(unix))]
fn filetime_set_to_now(_path: &Path) -> io::Result<()> {
    Ok(())
}

/// Request from `update-index` for the next index write.
#[derive(Debug, Clone, Copy, Default)]
pub struct WriteSplitIndexRequest {
    /// `Some(true)` / `Some(false)` for `--[no-]split-index`; `None` uses config / test env only.
    pub explicit: Option<bool>,
}

impl WriteSplitIndexRequest {
    /// Whether the next write should use split-index format.
    ///
    /// Matches Git: `--split-index` still enables split index when `core.splitIndex` is false,
    /// but emits a warning (see `builtin/update-index.c`).
    ///
    /// When `explicit` is `None`, an index that was already split (`split_link` set after load)
    /// stays split until `--no-split-index` (Git keeps `istate->split_index` across commands).
    pub fn want_write_split(self, cfg: &ConfigSet, index: &Index) -> bool {
        match self.explicit {
            Some(false) => {
                let _ = matches!(split_index_config(cfg), SplitIndexConfig::Enabled);
                false
            }
            Some(true) => {
                let _ = matches!(split_index_config(cfg), SplitIndexConfig::Disabled);
                true
            }
            None => {
                if matches!(split_index_config(cfg), SplitIndexConfig::Disabled) {
                    return false;
                }
                index.split_link.is_some()
                    || matches!(split_index_config(cfg), SplitIndexConfig::Enabled)
                    || git_test_split_index_env()
            }
        }
    }
}

fn find_entry_pos_sorted(entries: &[IndexEntry], path: &[u8], stage: u8) -> Option<usize> {
    entries
        .binary_search_by(|e| {
            e.path
                .as_slice()
                .cmp(path)
                .then_with(|| e.stage().cmp(&stage))
        })
        .ok()
}

fn load_shared_entries(
    git_dir: &Path,
    index_path: &Path,
    base_oid: &ObjectId,
) -> Result<Vec<IndexEntry>> {
    let p = resolve_shared_index_file(git_dir, index_path, base_oid);
    let data = fs::read(&p).map_err(Error::Io)?;
    let mut shared = Index::parse(&data)?;
    for (i, e) in shared.entries.iter_mut().enumerate() {
        e.base_index_pos = (i + 1) as u32;
    }
    Ok(shared.entries)
}

/// Write split index to `path` under `git_dir`, updating `index` base positions and `split_link`.
///
/// With `existing_lock`, the file at `path` is written through that already-held lock instead of
/// acquiring a new one; it must be the lock for `path`. When `commit_lock` is true the lock is
/// committed as part of the write; when false the caller must commit via [`IndexLock::commit_replace_index`].
#[allow(clippy::too_many_arguments)]
fn write_index_through_lock(
    index: &mut Index,
    path: &Path,
    skip_hash: bool,
    cfg: &ConfigSet,
    existing_lock: Option<&mut crate::index::IndexLock>,
    commit_lock: bool,
    thread_policy: crate::parallel::ThreadPolicy,
) -> Result<()> {
    index.write_to_path_with_config_and_lock_mode_policy(
        path,
        skip_hash,
        Some(cfg),
        existing_lock,
        commit_lock,
        thread_policy,
    )
}

#[allow(clippy::too_many_arguments)]
pub(crate) fn write_index_file_split(
    path: &Path,
    git_dir: &Path,
    index: &mut Index,
    cfg: &ConfigSet,
    request: WriteSplitIndexRequest,
    skip_hash: bool,
    thread_policy: crate::parallel::ThreadPolicy,
    existing_lock: Option<&mut crate::index::IndexLock>,
    commit_lock: bool,
) -> Result<()> {
    // Mirror upstream `write_locked_index`: under GIT_TEST_CHECK_CACHE_TREE, verify the cache-tree
    // against the index before persisting. A duplicate-entry tree (t4058) produces a cache-tree
    // whose entry counts exceed the deduplicated index, which must abort the write with the
    // canonical "corrupted cache-tree" error rather than silently writing a broken index.
    if git_test_check_cache_tree() {
        crate::write_tree::verify_cache_tree(index)?;
    }

    let want_split = request.want_write_split(cfg, index);

    let shared_repo = parse_shared_repository_perm(cfg.get("core.sharedRepository").as_deref());

    if !want_split {
        index.split_link = None;
        for e in &mut index.entries {
            e.base_index_pos = 0;
        }
        let perm_lock = staged_lock_path_buf_for_perm(existing_lock.as_deref(), commit_lock);
        write_index_through_lock(
            index,
            path,
            skip_hash,
            cfg,
            existing_lock,
            commit_lock,
            thread_policy,
        )?;
        adjust_shared_perm_written_index(path, perm_lock.as_deref(), shared_repo)?;
        return Ok(());
    }

    // Git `alternate_index_output`: split index is only written to the repository's primary index
    // file (`$GIT_DIR/index`). `GIT_INDEX_FILE` pointing elsewhere gets a unified index (t1700 #25).
    let default_index = git_dir.join("index");
    let is_primary_index = path == default_index
        || path
            .canonicalize_simplified()
            .ok()
            .zip(default_index.canonicalize_simplified().ok())
            .is_some_and(|(a, b)| a == b);
    if !is_primary_index {
        // Alternate index paths (GIT_INDEX_FILE, commit hook `next-index-*`) must be written
        // unified, but the caller's in-memory split metadata must survive for the primary write.
        let saved_link = index.split_link.clone();
        let saved_base_pos: Vec<u32> = index.entries.iter().map(|e| e.base_index_pos).collect();
        index.split_link = None;
        for e in &mut index.entries {
            e.base_index_pos = 0;
        }
        let perm_lock = staged_lock_path_buf_for_perm(existing_lock.as_deref(), commit_lock);
        let write_result = write_index_through_lock(
            index,
            path,
            skip_hash,
            cfg,
            existing_lock,
            commit_lock,
            thread_policy,
        );
        index.split_link = saved_link;
        for (e, pos) in index.entries.iter_mut().zip(saved_base_pos) {
            e.base_index_pos = pos;
        }
        write_result?;
        adjust_shared_perm_written_index(path, perm_lock.as_deref(), shared_repo)?;
        return Ok(());
    }

    if index.sparse_directories {
        return Err(Error::IndexError(
            "cannot write split index for a sparse index".to_owned(),
        ));
    }

    let prev_base = index
        .split_link
        .as_ref()
        .map(|l| l.base_oid)
        .unwrap_or(ObjectId::zero());

    // A zero base oid is what Git leaves after writing the shared index under `index.skipHash`;
    // readers treat it as unsplit, so there is no usable shared index to reuse.
    let mut rebuild = prev_base.is_zero()
        || should_rebuild_shared_index(index, cfg)
        || git_test_split_index_force_reorder(&prev_base);

    if git_test_split_index_env() && index.split_link.is_none() {
        rebuild = true;
    }

    let base_snapshot: Vec<IndexEntry> = if rebuild {
        let mut v: Vec<IndexEntry> = index.entries.to_vec();
        v.sort_by(|a, b| a.path.cmp(&b.path).then_with(|| a.stage().cmp(&b.stage())));
        for (i, e) in v.iter_mut().enumerate() {
            e.base_index_pos = (i + 1) as u32;
        }
        v
    } else {
        let link = index.split_link.as_ref().ok_or_else(|| {
            Error::IndexError("split index missing base link during reuse".to_owned())
        })?;
        load_shared_entries(git_dir, path, &link.base_oid)?
    };

    // After a shared-index rebuild, `base_snapshot` matches the merged index exactly; align indices
    // (e.g. `--no-split-index` then `--split-index`). When reusing an on-disk shared file, do not
    // remap by path — deleted paths can still exist in the shared index until expiry/rebuild, and
    // re-adding the same path must stay split-only (`base_index_pos` 0) like Git.
    if rebuild {
        for e in &mut index.entries {
            e.base_index_pos = find_entry_pos_sorted(&base_snapshot, &e.path, e.stage())
                .map_or(0, |i| (i + 1) as u32);
        }
    }

    let base_oid = if rebuild {
        let mut shared_index = Index {
            version: index.version,
            entries: base_snapshot.clone(),
            entries_sorted: true,
            sparse_directories: false,
            untracked_cache: None,
            fsmonitor_last_update: None,
            fsmonitor_dirty: None,
            fsmonitor_raw_extension: None,
            resolve_undo: None,
            split_link: None,
            cache_tree_root: None,
            cache_tree: None,
            hash_algo: index.hash_algo,
            source_mtime: None,
            source_checksum: None,
            source_file_len: None,
            defer_untracked_cache_invalidation: false,
            skip_racy_smudge_on_write: false,
            content_verified: std::collections::HashMap::new(),
            fsmonitor_refresh_ran: false,
            suppress_pre_write_index_housekeeping: false,
            entry_modes_repaired_on_load: false,
        };
        let tmp = match tempfile::NamedTempFile::new_in(git_dir) {
            Ok(t) => t,
            Err(e) if e.kind() == io::ErrorKind::PermissionDenied => {
                // Git: mks_tempfile_sm failure falls back to a unified index (no `link` extension).
                index.split_link = None;
                for e in &mut index.entries {
                    e.base_index_pos = 0;
                }
                let perm_lock =
                    staged_lock_path_buf_for_perm(existing_lock.as_deref(), commit_lock);
                write_index_through_lock(
                    index,
                    path,
                    skip_hash,
                    cfg,
                    existing_lock,
                    commit_lock,
                    thread_policy,
                )?;
                adjust_shared_perm_written_index(path, perm_lock.as_deref(), shared_repo)?;
                return Ok(());
            }
            Err(e) => return Err(Error::Io(e)),
        };
        let tmp_path = tmp.path().to_path_buf();
        // The shared index always carries a real checksum, even under `index.skipHash`: readers
        // match the link's base oid against the shared file's trailer, and a zero base oid means
        // "not split", so a skipped trailer would leave the index unreadable.
        shared_index.write_to_path_with_config_and_policy(
            &tmp_path,
            false,
            Some(cfg),
            thread_policy,
        )?;
        adjust_shared_perm_file(&tmp_path, shared_repo).map_err(Error::Io)?;
        let oid = read_index_trailer(&tmp_path, index.hash_algo)?;
        let dest = git_dir.join(format!("sharedindex.{}", oid.to_hex()));
        if let Err(e) = fs::rename(&tmp_path, &dest) {
            if e.kind() == io::ErrorKind::PermissionDenied {
                let _ = fs::remove_file(&tmp_path);
                index.split_link = None;
                for ent in &mut index.entries {
                    ent.base_index_pos = 0;
                }
                let perm_lock =
                    staged_lock_path_buf_for_perm(existing_lock.as_deref(), commit_lock);
                write_index_through_lock(
                    index,
                    path,
                    skip_hash,
                    cfg,
                    existing_lock,
                    commit_lock,
                    thread_policy,
                )?;
                adjust_shared_perm_written_index(path, perm_lock.as_deref(), shared_repo)?;
                return Ok(());
            }
            return Err(Error::Io(e));
        }
        clean_stale_shared_index_files(git_dir, &oid.to_hex(), cfg);
        oid
    } else {
        let oid = index
            .split_link
            .as_ref()
            .ok_or_else(|| {
                Error::IndexError("split index missing base link during reuse".to_owned())
            })?
            .base_oid;
        freshen_shared_index(&resolve_shared_index_file(git_dir, path, &oid));
        oid
    };

    // Map each shared-index row to the merged entry that claims it (`ce->index`), like Git
    // `prepare_to_write_split_index` (path must still match that row).
    let mut merged_by_pos: Vec<Option<usize>> = vec![None; base_snapshot.len()];
    for (p, e) in index.entries.iter().enumerate() {
        if e.base_index_pos == 0 {
            continue;
        }
        let i = e.base_index_pos.saturating_sub(1) as usize;
        if i < base_snapshot.len()
            && base_snapshot[i].path == e.path
            && base_snapshot[i].stage() == e.stage()
        {
            merged_by_pos[i] = Some(p);
        }
    }

    let mut delete_bm = EwahBitmap::new();
    let mut replace_bm = EwahBitmap::new();
    let mut main_entries: Vec<IndexEntry> = Vec::new();

    for i in 0..base_snapshot.len() {
        let b = &base_snapshot[i];
        if let Some(p) = merged_by_pos[i] {
            let c = &index.entries[p];
            if entries_equal_for_split(b, c) {
                continue;
            }
            replace_bm.set_bit_extend(i);
            let mut stub = c.clone();
            stub.path.clear();
            stub.base_index_pos = 0;
            main_entries.push(stub);
        } else {
            delete_bm.set_bit_extend(i);
        }
    }

    for e in &index.entries {
        if e.base_index_pos == 0 {
            let mut c = e.clone();
            c.base_index_pos = 0;
            main_entries.push(c);
            continue;
        }
        let i = e.base_index_pos.saturating_sub(1) as usize;
        if i >= base_snapshot.len()
            || base_snapshot[i].path != e.path
            || base_snapshot[i].stage() != e.stage()
        {
            let mut c = e.clone();
            c.base_index_pos = 0;
            main_entries.push(c);
            continue;
        }
        if entries_equal_for_split(&base_snapshot[i], e) {
            continue;
        }
        // Replacement: stub already pushed above.
    }

    main_entries.sort_by(|a, b| a.path.cmp(&b.path).then_with(|| a.stage().cmp(&b.stage())));

    let link = SplitIndexLink {
        base_oid,
        delete_bitmap: Some(delete_bm),
        replace_bitmap: Some(replace_bm),
    };

    let mut out_index = Index {
        version: index.version,
        entries: main_entries,
        entries_sorted: true,
        sparse_directories: false,
        untracked_cache: index.untracked_cache.clone(),
        fsmonitor_last_update: index.fsmonitor_last_update.clone(),
        fsmonitor_dirty: index.fsmonitor_dirty.clone(),
        fsmonitor_raw_extension: index.fsmonitor_raw_extension.clone(),
        resolve_undo: None,
        split_link: Some(link),
        cache_tree_root: index.cache_tree_root,
        cache_tree: index.cache_tree.clone(),
        hash_algo: index.hash_algo,
        source_mtime: index.source_mtime,
        source_checksum: index.source_checksum.clone(),
        source_file_len: index.source_file_len,
        defer_untracked_cache_invalidation: false,
        skip_racy_smudge_on_write: false,
        content_verified: std::collections::HashMap::new(),
        fsmonitor_refresh_ran: index.fsmonitor_refresh_ran,
        suppress_pre_write_index_housekeeping: index.suppress_pre_write_index_housekeeping,
        entry_modes_repaired_on_load: index.entry_modes_repaired_on_load,
    };

    let perm_lock = staged_lock_path_buf_for_perm(existing_lock.as_deref(), commit_lock);
    write_index_through_lock(
        &mut out_index,
        path,
        skip_hash,
        cfg,
        existing_lock,
        commit_lock,
        thread_policy,
    )?;
    adjust_shared_perm_written_index(path, perm_lock.as_deref(), shared_repo)?;

    for e in &mut index.entries {
        if let Some(pos) = find_entry_pos_sorted(&base_snapshot, &e.path, e.stage()) {
            if entries_equal_for_split(&base_snapshot[pos], e) {
                e.base_index_pos = (pos + 1) as u32;
                continue;
            }
        }
        e.base_index_pos = 0;
    }

    index.split_link = Some(SplitIndexLink {
        base_oid,
        delete_bitmap: None,
        replace_bitmap: None,
    });

    Ok(())
}

/// Human-readable split-index dump for `test-tool dump-split-index`.
/// If `index` has a split `link` extension, load the shared index and merge entries.
pub fn resolve_split_index_if_needed(
    index: &mut Index,
    git_dir: &Path,
    index_path: &Path,
) -> Result<()> {
    let Some(link) = index.split_link.clone() else {
        return Ok(());
    };
    if link.base_oid.is_zero() {
        return Ok(());
    }
    let base_oid = link.base_oid;
    let shared_path = resolve_shared_index_file(git_dir, index_path, &base_oid);
    let data = fs::read(&shared_path).map_err(|e| {
        Error::IndexError(format!(
            "split index: cannot read shared index {}: {e}",
            shared_path.display()
        ))
    })?;
    let hash_len = index.hash_algo.len();
    if data.len() < hash_len {
        return Err(Error::IndexError(
            "split index: shared index too short".to_owned(),
        ));
    }
    let (body, trailer) = data.split_at(data.len() - hash_len);
    // The link names the shared file's trailer, which must also match its body.
    let trailer = ObjectId::from_bytes(trailer)?;
    let got = if trailer == base_oid {
        hash_index_body(body, index.hash_algo)
    } else {
        trailer
    };
    if got != base_oid {
        return Err(Error::IndexError(format!(
            "broken index, expect {} in {}, got {}",
            base_oid.to_hex(),
            shared_path.display(),
            got.to_hex()
        )));
    }
    freshen_shared_index(&shared_path);
    let base_entries = Index::parse_with_algo(&data, index.hash_algo)?.entries;
    merge_split_into_index(index, link, base_entries)?;
    index.split_link = Some(SplitIndexLink {
        base_oid,
        delete_bitmap: None,
        replace_bitmap: None,
    });
    Ok(())
}

/// Format output for `test-tool dump-split-index` (Git reads the index with `do_read_index` only,
/// without merging the shared base — stubs and EWAH bitmaps stay intact).
pub fn format_dump_split_index_file(data: &[u8], index: &Index) -> Result<String> {
    use std::fmt::Write;
    let hash_len = index.hash_algo.len();
    if data.len() < hash_len {
        return Err(Error::IndexError("index too short".to_owned()));
    }
    let body = &data[..data.len() - hash_len];
    let trail = &data[data.len() - hash_len..];
    let own = if trail.iter().all(|&b| b == 0) {
        hash_index_body(body, index.hash_algo)
    } else {
        ObjectId::from_bytes(trail)?
    };

    let mut s = String::new();
    writeln!(s, "own {}", own.to_hex()).map_err(|e| Error::IndexError(e.to_string()))?;
    let Some(link) = &index.split_link else {
        writeln!(s, "not a split index").map_err(|e| Error::IndexError(e.to_string()))?;
        return Ok(s);
    };
    writeln!(s, "base {}", link.base_oid.to_hex()).map_err(|e| Error::IndexError(e.to_string()))?;
    for e in &index.entries {
        // Split-index replacement stubs use `CE_STRIP_NAME`: zero-length path on disk (Git still prints the line).
        let path_disp = String::from_utf8_lossy(&e.path);
        writeln!(
            s,
            "{:06o} {} {}\t{}",
            e.mode,
            e.oid.to_hex(),
            e.stage(),
            path_disp
        )
        .map_err(|e| Error::IndexError(e.to_string()))?;
    }
    write!(s, "replacements:").map_err(|e| Error::IndexError(e.to_string()))?;
    if let Some(bm) = &link.replace_bitmap {
        bm.each_set_bit(|pos| {
            write!(s, " {}", pos).ok();
        });
    }
    writeln!(s).map_err(|e| Error::IndexError(e.to_string()))?;
    write!(s, "deletions:").map_err(|e| Error::IndexError(e.to_string()))?;
    if let Some(bm) = &link.delete_bitmap {
        bm.each_set_bit(|pos| {
            write!(s, " {}", pos).ok();
        });
    }
    writeln!(s).map_err(|e| Error::IndexError(e.to_string()))?;
    Ok(s)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::ConfigSet;
    use crate::environment::Environment;
    use crate::index::{Index, IndexEntry, MODE_REGULAR};
    use crate::objects::{HashAlgo, ObjectKind};
    use std::fs;

    fn sample_entry(path: &str, ino: u32) -> IndexEntry {
        IndexEntry {
            ctime_sec: 1,
            ctime_nsec: 0,
            mtime_sec: 2,
            mtime_nsec: 0,
            dev: 1,
            ino,
            mode: MODE_REGULAR,
            uid: 1,
            gid: 1,
            size: 3,
            oid: HashAlgo::Sha1
                .hash_object(ObjectKind::Blob, b"abc")
                .expect("hash"),
            flags: path.len().min(0xFFF) as u16,
            flags_extended: None,
            path: path.as_bytes().to_vec(),
            base_index_pos: 0,
        }
    }

    #[test]
    fn write_split_index_request_keeps_existing_split_without_config() {
        let cfg = ConfigSet::new();
        let mut idx = Index::empty(2);
        idx.split_link = Some(SplitIndexLink {
            base_oid: HashAlgo::Sha1
                .hash_object(ObjectKind::Blob, b"base")
                .expect("hash"),
            delete_bitmap: None,
            replace_bitmap: None,
        });
        assert!(WriteSplitIndexRequest { explicit: None }.want_write_split(&cfg, &idx));
    }

    #[test]
    fn entries_equal_for_split_ignores_path_and_namehash() {
        let mut a = sample_entry("a.txt", 1);
        let mut b = sample_entry("b.txt", 1);
        assert!(entries_equal_for_split(&a, &b));
        b.mtime_sec = 3;
        assert!(!entries_equal_for_split(&a, &b));
        a.flags |= 0x2000;
        b = a.clone();
        b.path = b"b.txt".into();
        assert!(entries_equal_for_split(&a, &b));
    }

    #[test]
    fn parse_link_extension_round_trip_and_corrupt() {
        let base = HashAlgo::Sha1
            .hash_object(ObjectKind::Blob, b"base")
            .expect("hash");
        let mut del = EwahBitmap::new();
        del.set_bit_extend(1);
        let mut rep = EwahBitmap::new();
        rep.set_bit_extend(3);
        let payload = serialize_link_extension_payload(&base, &del, &rep);
        let link = parse_link_extension(&payload, HashAlgo::Sha1).expect("parse");
        assert_eq!(link.base_oid, base);
        assert!(link.delete_bitmap.is_some());
        assert!(link.replace_bitmap.is_some());

        assert!(parse_link_extension(&[], HashAlgo::Sha1).is_err());
        let mut garbage = payload.clone();
        garbage.push(1);
        assert!(parse_link_extension(&garbage, HashAlgo::Sha1).is_err());
    }

    #[test]
    fn should_rebuild_shared_index_respects_max_percent_change() {
        let mut idx = Index::empty(2);
        for i in 0..10 {
            idx.add_or_replace(sample_entry(&format!("f{i}.txt"), i));
        }
        for e in &mut idx.entries {
            e.base_index_pos = (1) as u32;
        }
        idx.entries[0].base_index_pos = 0;
        idx.entries[1].base_index_pos = 0;
        idx.entries[2].base_index_pos = 0;
        let dir = tempfile::tempdir().expect("tempdir");
        fs::write(
            dir.path().join("config"),
            "[splitIndex]\n\tmaxPercentChange = 20\n",
        )
        .expect("write config");
        let cfg = ConfigSet::load(&Environment::empty(), Some(dir.path()), true).expect("load");
        assert!(should_rebuild_shared_index(&idx, &cfg));
        fs::write(
            dir.path().join("config"),
            "[splitIndex]\n\tmaxPercentChange = 100\n",
        )
        .expect("write config");
        let cfg = ConfigSet::load(&Environment::empty(), Some(dir.path()), true).expect("load");
        assert!(!should_rebuild_shared_index(&idx, &cfg));
    }

    #[cfg(unix)]
    #[test]
    fn shared_perm_adjustment_targets_lock_file_on_uncommitted_flush() {
        use std::os::unix::fs::PermissionsExt;

        let dir = tempfile::tempdir().expect("tempdir");
        let index_path = dir.path().join("index");
        fs::write(&index_path, b"live").expect("write index");
        fs::set_permissions(&index_path, fs::Permissions::from_mode(0o644)).expect("index mode");

        let lock = crate::index::IndexLock::acquire(&index_path, None).expect("lock");
        fs::write(&lock.lock_path, b"staged").expect("write lock");
        fs::set_permissions(&lock.lock_path, fs::Permissions::from_mode(0o644)).expect("lock mode");

        super::adjust_shared_perm_written_index(&index_path, Some(lock.lock_path.as_path()), 0o660)
            .expect("adjust perm");

        assert_eq!(
            fs::metadata(&index_path)
                .expect("index meta")
                .permissions()
                .mode()
                & 0o777,
            0o644,
            "live index mode must stay unchanged before commit_replace_index"
        );
        assert_eq!(
            fs::metadata(&lock.lock_path)
                .expect("lock meta")
                .permissions()
                .mode()
                & 0o777,
            0o664,
            "sharedRepository perm applies to staged lock bytes"
        );
        drop(lock);
    }

    #[test]
    fn split_index_config_and_shared_repository_perm() {
        let dir = tempfile::tempdir().expect("tempdir");
        fs::write(
            dir.path().join("config"),
            "[core]\n\tsplitIndex = true\n\tsharedRepository = group\n",
        )
        .expect("write");
        let cfg = ConfigSet::load(&Environment::empty(), Some(dir.path()), true).expect("load");
        assert!(matches!(
            split_index_config(&cfg),
            SplitIndexConfig::Enabled
        ));
        assert_eq!(
            parse_shared_repository_perm(cfg.get("core.sharedRepository").as_deref()),
            0o660
        );
        let _ = max_percent_split_change(&cfg);
    }

    #[test]
    fn write_split_index_request_explicit_overrides_config() {
        let cfg = ConfigSet::new();
        let idx = Index::empty(2);
        assert!(WriteSplitIndexRequest {
            explicit: Some(true),
        }
        .want_write_split(&cfg, &idx));
        assert!(!WriteSplitIndexRequest {
            explicit: Some(false),
        }
        .want_write_split(&cfg, &idx));
    }

    #[test]
    fn hash_index_body_matches_entry_checksum() {
        let mut idx = Index::empty(2);
        idx.add_or_replace(sample_entry("a.txt", 1));
        let dir = tempfile::tempdir().expect("tempdir");
        let path = dir.path().join("index");
        idx.write(&path).expect("write index");
        let buf = fs::read(&path).expect("read index");
        let body = &buf[..buf.len().saturating_sub(20)];
        let oid = hash_index_body(body, HashAlgo::Sha1);
        assert_ne!(oid, ObjectId::zero());
    }

    #[test]
    fn shared_repository_perm_parses_git_variants() {
        assert_eq!(parse_shared_repository_perm(Some("umask")), 0);
        assert_eq!(parse_shared_repository_perm(Some("group")), 0o660);
        assert_eq!(parse_shared_repository_perm(Some("all")), 0o664);
        assert_eq!(parse_shared_repository_perm(Some("true")), 0o660);
        assert_eq!(parse_shared_repository_perm(Some("world")), 0o664);
        assert_eq!(parse_shared_repository_perm(None), 0);
        assert_eq!(parse_shared_repository_perm(Some("664")), -0o664);
        assert_eq!(parse_shared_repository_perm(Some("600")), -384);
    }

    #[test]
    fn shared_index_expire_never_and_now() {
        let dir = tempfile::tempdir().expect("tempdir");
        fs::write(
            dir.path().join("config"),
            "[splitIndex]\n\tsharedIndexExpire = never\n",
        )
        .expect("write");
        let cfg = ConfigSet::load(&Environment::empty(), Some(dir.path()), true).expect("load");
        assert_eq!(shared_index_expire_threshold(&cfg), 0);

        fs::write(
            dir.path().join("config"),
            "[splitIndex]\n\tsharedIndexExpire = now\n",
        )
        .expect("write");
        let cfg = ConfigSet::load(&Environment::empty(), Some(dir.path()), true).expect("load");
        assert!(shared_index_expire_threshold(&cfg) > 0);
    }

    #[test]
    fn format_dump_split_index_short_index_errors() {
        let idx = Index::empty(2);
        let err = format_dump_split_index_file(&[1, 2, 3], &idx).expect_err("too short");
        assert!(err.to_string().contains("too short"));
    }

    #[test]
    fn resolve_split_index_missing_shared_file() {
        let tmp = tempfile::tempdir().expect("tempdir");
        let git_dir = tmp.path().join(".git");
        fs::create_dir_all(&git_dir).expect("mkdir");
        let mut idx = Index::empty(2);
        idx.split_link = Some(SplitIndexLink {
            base_oid: HashAlgo::Sha1
                .hash_object(ObjectKind::Blob, b"missing")
                .expect("hash"),
            delete_bitmap: None,
            replace_bitmap: None,
        });
        let index_path = git_dir.join("index");
        fs::write(&index_path, b"x").expect("write");
        let err = resolve_split_index_if_needed(&mut idx, &git_dir, &index_path).expect_err("read");
        assert!(err.to_string().contains("shared index"));
    }

    fn system_git(root: &Path, args: &[&str]) -> String {
        let out = std::process::Command::new("git")
            .env("GIT_CONFIG_NOSYSTEM", "1")
            .env("GIT_CONFIG_GLOBAL", "/dev/null")
            .env("GIT_AUTHOR_NAME", "Test")
            .env("GIT_AUTHOR_EMAIL", "test@example.com")
            .env("GIT_COMMITTER_NAME", "Test")
            .env("GIT_COMMITTER_EMAIL", "test@example.com")
            .current_dir(root)
            .args(args)
            .output()
            .expect("run git");
        assert!(
            out.status.success(),
            "git {args:?} failed: {}",
            String::from_utf8_lossy(&out.stderr)
        );
        String::from_utf8(out.stdout).expect("utf8")
    }

    fn open_repo(root: &Path) -> crate::repo::Repository {
        crate::repo::Repository::discover(
            Some(root),
            &crate::environment::RepositoryOptions::empty(),
        )
        .expect("open")
    }

    fn shared_index_names(git_dir: &Path) -> Vec<String> {
        let mut names: Vec<String> = fs::read_dir(git_dir)
            .expect("read git dir")
            .flatten()
            .filter_map(|e| e.file_name().to_str().map(str::to_owned))
            .filter(|n| n.starts_with("sharedindex."))
            .collect();
        names.sort();
        names
    }

    /// A split index whose shared file was written by Git before `index.skipHash` was turned on.
    fn git_split_index_repo(root: &Path, skip_hash_key: &str) {
        system_git(root, &["init", "-q", "-b", "main"]);
        for name in ["a.txt", "b.txt"] {
            fs::write(root.join(name), b"1\n").expect("write");
        }
        system_git(root, &["add", "."]);
        system_git(root, &["commit", "-qm", "init"]);
        system_git(root, &["config", "core.splitIndex", "true"]);
        system_git(root, &["update-index", "--split-index"]);
        system_git(root, &["config", skip_hash_key, "true"]);
        system_git(root, &["status", "--porcelain"]);
    }

    fn assert_git_reads_index(root: &Path, expected_paths: &str) {
        assert_eq!(system_git(root, &["ls-files"]), expected_paths);
        system_git(root, &["status", "--porcelain"]);
        system_git(root, &["fsck", "--strict", "--no-progress"]);
    }

    #[cfg_attr(
        not(feature = "full-tests"),
        ignore = "starts system git or is heavy; run with --features full-tests"
    )]
    #[test]
    fn rebuilt_shared_index_under_skip_hash_is_readable_by_git() {
        for key in ["index.skipHash", "feature.manyFiles"] {
            let tmp = tempfile::tempdir().expect("tempdir");
            let root = tmp.path();
            git_split_index_repo(root, key);
            system_git(root, &["config", "splitIndex.maxPercentChange", "0"]);
            let before = shared_index_names(&root.join(".git"));

            let repo = open_repo(root);
            let mut index = repo.load_index().expect("load");
            assert!(index.remove(b"b.txt"));
            repo.write_index(&mut index).expect("write");

            let git_dir = repo.git_dir();
            let main = fs::read(git_dir.join("index")).expect("read index");
            assert!(
                main[main.len() - 20..].iter().all(|&b| b == 0),
                "{key}: the main index keeps honoring skipHash"
            );
            let reread = Index::parse(&main).expect("parse");
            let link = reread.split_link.expect("index stays split");
            assert!(!link.base_oid.is_zero());
            let shared_name = format!("sharedindex.{}", link.base_oid.to_hex());
            assert_ne!(shared_index_names(git_dir), before, "{key}: rebuilt");
            let shared = fs::read(git_dir.join(&shared_name)).expect("shared index named by link");
            assert_eq!(
                &shared[shared.len() - 20..],
                link.base_oid.as_bytes(),
                "{key}: shared index trailer must match its name"
            );

            // Git itself would rebuild the shared index on its next write, which under skipHash
            // leaves an index it cannot read; keep it on the shared index grit wrote.
            system_git(root, &["config", "splitIndex.maxPercentChange", "100"]);
            assert_git_reads_index(root, "a.txt\n");
            assert_eq!(repo.load_index().expect("grit reload").entries.len(), 1);
        }
    }

    #[cfg_attr(
        not(feature = "full-tests"),
        ignore = "starts system git or is heavy; run with --features full-tests"
    )]
    #[test]
    fn reused_shared_index_under_skip_hash_is_readable_by_git() {
        let tmp = tempfile::tempdir().expect("tempdir");
        let root = tmp.path();
        git_split_index_repo(root, "index.skipHash");
        system_git(root, &["config", "splitIndex.maxPercentChange", "100"]);
        let before = shared_index_names(&root.join(".git"));

        let repo = open_repo(root);
        let mut index = repo.load_index().expect("load");
        assert!(index.remove(b"b.txt"));
        repo.write_index(&mut index).expect("write");

        assert_eq!(
            shared_index_names(repo.git_dir()),
            before,
            "shared index reused"
        );
        assert_git_reads_index(root, "a.txt\n");
    }

    #[cfg_attr(
        not(feature = "full-tests"),
        ignore = "starts system git or is heavy; run with --features full-tests"
    )]
    #[test]
    fn null_split_link_rebuilds_a_real_shared_index() {
        let tmp = tempfile::tempdir().expect("tempdir");
        let root = tmp.path();
        git_split_index_repo(root, "index.skipHash");
        system_git(root, &["config", "splitIndex.maxPercentChange", "100"]);

        let repo = open_repo(root);
        let mut index = repo.load_index().expect("load");
        index.split_link = Some(SplitIndexLink {
            base_oid: ObjectId::zero(),
            delete_bitmap: None,
            replace_bitmap: None,
        });
        repo.write_index(&mut index).expect("write");

        let link = repo
            .load_index()
            .expect("reload")
            .split_link
            .expect("split");
        assert!(!link.base_oid.is_zero());
        assert_git_reads_index(root, "a.txt\nb.txt\n");
    }

    #[test]
    fn resolve_split_index_rejects_link_not_matching_shared_trailer() {
        let tmp = tempfile::tempdir().expect("tempdir");
        let git_dir = tmp.path().join(".git");
        fs::create_dir_all(&git_dir).expect("mkdir");
        let mut shared = Index::empty(2);
        shared.entries.push(sample_entry("a.txt", 1));
        let staged = git_dir.join("staged");
        shared.write_to_path(&staged, true).expect("write shared");
        let data = fs::read(&staged).expect("read");
        let body_oid = hash_index_body(&data[..data.len() - 20], HashAlgo::Sha1);
        let shared_path = git_dir.join(format!("sharedindex.{}", body_oid.to_hex()));
        fs::rename(&staged, &shared_path).expect("rename");

        let mut idx = Index::empty(2);
        idx.split_link = Some(SplitIndexLink {
            base_oid: body_oid,
            delete_bitmap: None,
            replace_bitmap: None,
        });
        let index_path = git_dir.join("index");
        let err = resolve_split_index_if_needed(&mut idx, &git_dir, &index_path)
            .expect_err("zero trailer does not match the link");
        assert!(err.to_string().contains("broken index"), "{err}");
    }

    #[test]
    fn clean_stale_shared_index_files_honors_expire() {
        let dir = tempfile::tempdir().expect("tempdir");
        let git_dir = dir.path().join(".git");
        fs::create_dir_all(&git_dir).expect("mkdir");
        fs::write(
            dir.path().join("config"),
            "[splitIndex]\n\tsharedIndexExpire = now\n",
        )
        .expect("write config");
        let cfg = ConfigSet::load(&Environment::empty(), Some(dir.path()), true).expect("load");
        let stale = git_dir.join("sharedindex.deadbeefdeadbeefdeadbeefdeadbeefdeadbeef");
        fs::write(&stale, b"stale").expect("write stale");
        #[cfg(unix)]
        {
            use std::os::unix::fs::MetadataExt;
            let past = filetime::FileTime::from_unix_time(1_000_000, 0);
            filetime::set_file_mtime(&stale, past).expect("backdate");
            let _ = stale.metadata().expect("meta").mtime();
        }
        clean_stale_shared_index_files(&git_dir, "cccccccccccccccccccccccccccccccccccccccc", &cfg);
        assert!(!stale.exists(), "expired sharedindex must be removed");
    }

    #[test]
    fn merge_split_into_index_delete_only() {
        let base_entries = vec![sample_entry("a.txt", 1), sample_entry("b.txt", 2)];
        let mut del = EwahBitmap::new();
        del.set_bit_extend(0);
        let link = SplitIndexLink {
            base_oid: HashAlgo::Sha1
                .hash_object(ObjectKind::Blob, b"shared")
                .expect("hash"),
            delete_bitmap: Some(del),
            replace_bitmap: None,
        };
        let mut index = Index::empty(2);
        merge_split_into_index(&mut index, link, base_entries).expect("merge");
        assert_eq!(index.entries().len(), 1);
        assert_eq!(String::from_utf8_lossy(&index.entries()[0].path), "b.txt");
    }

    #[test]
    fn merge_split_into_index_applies_delete_and_replace() {
        let base_entries = vec![
            sample_entry("a.txt", 1),
            sample_entry("b.txt", 2),
            sample_entry("c.txt", 3),
        ];
        let mut del = EwahBitmap::new();
        del.set_bit_extend(1);
        let mut rep = EwahBitmap::new();
        rep.set_bit_extend(2);
        let link = SplitIndexLink {
            base_oid: HashAlgo::Sha1
                .hash_object(ObjectKind::Blob, b"shared")
                .expect("hash"),
            delete_bitmap: Some(del),
            replace_bitmap: Some(rep),
        };
        let mut rep_entry = sample_entry("", 99);
        rep_entry.oid = HashAlgo::Sha1
            .hash_object(ObjectKind::Blob, b"newc")
            .expect("hash");
        let mut index = Index::empty(2);
        index.add_or_replace(rep_entry);
        merge_split_into_index(&mut index, link, base_entries).expect("merge");
        let paths: Vec<_> = index
            .entries()
            .iter()
            .map(|e| String::from_utf8_lossy(&e.path).into_owned())
            .collect();
        assert_eq!(paths, vec!["a.txt".to_owned(), "c.txt".to_owned()]);
    }
}