Struct Index

Source

pub struct Index {
    pub version: u32,
    pub entries: Vec<IndexEntry>,
    pub sparse_directories: bool,
}

Expand description

The in-memory representation of the Git index file.

Fields§

§version: u32

Index format version (2 or 3).

§entries: Vec<IndexEntry>

Index entries, sorted by (path, stage).

§sparse_directories: bool

When true, the on-disk index includes the sdir extension (sparse index).

Implementations§

Source §

impl Index

Source

pub fn new() -> Self

Create a new, empty index.

Respects GIT_INDEX_VERSION if set, otherwise defaults to version 2.

Source

pub fn new_with_config( config_index_version: Option<&str>, config_many_files: Option<&str>, ) -> Self

Create a new empty index, respecting config values for version.

Priority matches Git’s prepare_repo_settings: GIT_INDEX_VERSION env, then feature.manyFiles (implies version 4), then index.version (overrides version).

Source

pub fn new_from_config(config: &ConfigSet) -> Self

New empty index using a loaded ConfigSet (includes -c / GIT_CONFIG_PARAMETERS).

Same precedence as Self::new_with_config, but reads feature.manyFiles and index.version from config.

Source

pub fn load(path: &Path) -> Result<Self>

Load an index from the given file path without expanding sparse-directory placeholders.

Returns an empty index if the file does not exist.

§Errors

Returns Error::IndexError if the file is present but corrupt.

Source

pub fn load_expand_sparse(path: &Path, odb: &Odb) -> Result<Self>

Load an index and expand sparse-directory placeholders using the object database.

After a successful return, Index::sparse_directories is cleared and every placeholder is replaced by the blob entries from the referenced tree.

Source

pub fn load_expand_sparse_optional(path: &Path, odb: &Odb) -> Result<Self>

Like Index::load_expand_sparse, but treats a missing index or Git’s "file too short" placeholder as an empty index.

Source

pub fn has_sparse_directory_placeholders(&self) -> bool

Returns true if the index contains sparse-index tree placeholders (MODE_TREE + skip-worktree).

Source

pub fn expand_sparse_directory_placeholders(&mut self, odb: &Odb) -> Result<()>

Replace sparse-directory placeholder entries with all blob paths from their trees.

Each placeholder must reference a tree object. New entries are marked skip-worktree like Git’s expanded index, except we keep sparse_directories false in memory after expansion.

Source

pub fn try_collapse_sparse_directories( &mut self, odb: &Odb, head_tree: &ObjectId, patterns: &[String], cone_mode: bool, enable_sparse_index: bool, ) -> Result<()>

Collapse consecutive skip-worktree subtrees into sparse-directory placeholders when cone_mode is true and each directory is outside the sparse cone.

head_tree is the tree OID at HEAD. When enable_sparse_index is false, clears Index::sparse_directories and returns without collapsing.

Source

pub fn parse(data: &[u8]) -> Result<Self>

Parse index bytes (the whole file including trailing SHA-1).

§Errors

Returns Error::IndexError on structural problems.

Source

pub fn write(&self, path: &Path) -> Result<()>

Write the index to a file, computing and appending the trailing SHA-1.

§Errors

Returns Error::Io on filesystem errors.

Source

pub fn add_or_replace(&mut self, entry: IndexEntry)

Add or replace an entry (matched by path + stage).

Source

pub fn stage_file(&mut self, entry: IndexEntry)

Stage a file at stage 0, removing any conflict stage entries (1, 2, 3) for the same path. This is the correct behavior for git add on a conflicted file during merge/cherry-pick resolution.

Source

pub fn remove(&mut self, path: &[u8]) -> bool

Remove all entries matching the given path (all stages).

Returns true if at least one entry was removed.

Source

pub fn remove_descendants_under_path(&mut self, path: &str)

Remove every index entry whose path lies strictly under path (all stages).

Used when staging a file at path that replaces a former directory: Git removes tracked paths like path/child from the index so they do not remain alongside the new blob entry.

Source

pub fn sort(&mut self)

Sort entries in Git’s canonical order: by path, then by stage.

Source

pub fn get(&self, path: &[u8], stage: u8) -> Option<&IndexEntry>

Find an entry by path and stage (0 for normal entries).

Source

pub fn get_mut(&mut self, path: &[u8], stage: u8) -> Option<&mut IndexEntry>

Find a mutable entry by path and stage.

Source

pub fn overlay_tree_on_index( &mut self, repo: &Repository, treeish: &str, prefix: &[u8], ) -> Result<()>

Merge tree contents from treeish into this index as virtual stage-1 entries, matching Git’s overlay_tree_on_index used by git ls-files --with-tree.

Existing unmerged entries (stages 1–3) are shifted to stage 3 so stage 1 is free for the overlay. Stage-1 paths that already exist at stage 0 are marked so ls-files can skip them (Git’s CE_UPDATE on the stage-1 entry).

§Parameters

repo — repository whose object database is used to read the tree.
treeish — revision or tree OID string (HEAD, HEAD~1, full SHA, etc.).
prefix — optional path prefix (bytes, no trailing slash except empty); only paths under this prefix are considered from the tree. Pass empty slice for the full tree.