Struct git2::Index

pub struct Index { /* private fields */ }

A structure to represent a git index

Implementations

impl Index

pub fn new() -> Result<Index, Error>

Creates a new in-memory index.

This index object cannot be read/written to the filesystem, but may be used to perform in-memory index operations.

pub fn open(index_path: &Path) -> Result<Index, Error>

Create a new bare Git index object as a memory representation of the Git index file in ‘index_path’, without a repository to back it.

Since there is no ODB or working directory behind this index, any Index methods which rely on these (e.g. add_path) will fail.

If you need an index attached to a repository, use the index() method on Repository.

pub fn version(&self) -> u32

Get index on-disk version.

Valid return values are 2, 3, or 4. If 3 is returned, an index with version 2 may be written instead, if the extension data in version 3 is not necessary.

pub fn set_version(&mut self, version: u32) -> Result<(), Error>

Set index on-disk version.

Valid values are 2, 3, or 4. If 2 is given, git_index_write may write an index with version 3 instead, if necessary to accurately represent the index.

pub fn add(&mut self, entry: &IndexEntry) -> Result<(), Error>

Add or update an index entry from an in-memory struct

If a previous index entry exists that has the same path and stage as the given ‘source_entry’, it will be replaced. Otherwise, the ‘source_entry’ will be added.

pub fn add_frombuffer(
    &mut self,
    entry: &IndexEntry,
    data: &[u8]
) -> Result<(), Error>

Add or update an index entry from a buffer in memory

This method will create a blob in the repository that owns the index and then add the index entry to the index. The path of the entry represents the position of the blob relative to the repository’s root folder.

If a previous index entry exists that has the same path as the given ‘entry’, it will be replaced. Otherwise, the ‘entry’ will be added. The id and the file_size of the ‘entry’ are updated with the real value of the blob.

This forces the file to be added to the index, not looking at gitignore rules.

If this file currently is the result of a merge conflict, this file will no longer be marked as conflicting. The data about the conflict will be moved to the “resolve undo” (REUC) section.

pub fn add_path(&mut self, path: &Path) -> Result<(), Error>

Add or update an index entry from a file on disk

The file path must be relative to the repository’s working folder and must be readable.

This method will fail in bare index instances.

This forces the file to be added to the index, not looking at gitignore rules.

If this file currently is the result of a merge conflict, this file will no longer be marked as conflicting. The data about the conflict will be moved to the “resolve undo” (REUC) section.

pub fn add_all<T, I>(
    &mut self,
    pathspecs: I,
    flag: IndexAddOption,
    cb: Option<&mut IndexMatchedPath<'_>>
) -> Result<(), Error> where
    T: IntoCString,
    I: IntoIterator<Item = T>, 

Add or update index entries matching files in the working directory.

This method will fail in bare index instances.

The pathspecs are a list of file names or shell glob patterns that will matched against files in the repository’s working directory. Each file that matches will be added to the index (either updating an existing entry or adding a new entry). You can disable glob expansion and force exact matching with the AddDisablePathspecMatch flag.

Files that are ignored will be skipped (unlike add_path). If a file is already tracked in the index, then it will be updated even if it is ignored. Pass the AddForce flag to skip the checking of ignore rules.

To emulate git add -A and generate an error if the pathspec contains the exact path of an ignored file (when not using AddForce), add the AddCheckPathspec flag. This checks that each entry in pathspecs that is an exact match to a filename on disk is either not ignored or already in the index. If this check fails, the function will return an error.

To emulate git add -A with the “dry-run” option, just use a callback function that always returns a positive value. See below for details.

If any files are currently the result of a merge conflict, those files will no longer be marked as conflicting. The data about the conflicts will be moved to the “resolve undo” (REUC) section.

If you provide a callback function, it will be invoked on each matching item in the working directory immediately before it is added to / updated in the index. Returning zero will add the item to the index, greater than zero will skip the item, and less than zero will abort the scan an return an error to the caller.

Example

Emulate git add *:

use git2::{Index, IndexAddOption, Repository};

let repo = Repository::open("/path/to/a/repo").expect("failed to open");
let mut index = repo.index().expect("cannot get the Index file");
index.add_all(["*"].iter(), IndexAddOption::DEFAULT, None);
index.write();

pub fn clear(&mut self) -> Result<(), Error>

Clear the contents (all the entries) of an index object.

This clears the index object in memory; changes must be explicitly written to disk for them to take effect persistently via write_*.

pub fn len(&self) -> usize

Get the count of entries currently in the index

pub fn is_empty(&self) -> bool

Return true is there is no entry in the index

pub fn get(&self, n: usize) -> Option<IndexEntry>

Get one of the entries in the index by its position.

pub fn iter(&self) -> IndexEntries<'_>

Get an iterator over the entries in this index.

pub fn conflicts(&self) -> Result<IndexConflicts<'_>, Error>

Get an iterator over the index entries that have conflicts

pub fn get_path(&self, path: &Path, stage: i32) -> Option<IndexEntry>

Get one of the entries in the index by its path.

pub fn has_conflicts(&self) -> bool

Does this index have conflicts?

Returns true if the index contains conflicts, false if it does not.

pub fn path(&self) -> Option<&Path>

Get the full path to the index file on disk.

Returns None if this is an in-memory index.

pub fn read(&mut self, force: bool) -> Result<(), Error>

Update the contents of an existing index object in memory by reading from the hard disk.

If force is true, this performs a “hard” read that discards in-memory changes and always reloads the on-disk index data. If there is no on-disk version, the index will be cleared.

If force is false, this does a “soft” read that reloads the index data from disk only if it has changed since the last time it was loaded. Purely in-memory index data will be untouched. Be aware: if there are changes on disk, unwritten in-memory changes are discarded.

pub fn read_tree(&mut self, tree: &Tree<'_>) -> Result<(), Error>

Read a tree into the index file with stats

The current index contents will be replaced by the specified tree.

pub fn remove(&mut self, path: &Path, stage: i32) -> Result<(), Error>

Remove an entry from the index

pub fn remove_path(&mut self, path: &Path) -> Result<(), Error>

Remove an index entry corresponding to a file on disk.

The file path must be relative to the repository’s working folder. It may exist.

If this file currently is the result of a merge conflict, this file will no longer be marked as conflicting. The data about the conflict will be moved to the “resolve undo” (REUC) section.

pub fn remove_dir(&mut self, path: &Path, stage: i32) -> Result<(), Error>

Remove all entries from the index under a given directory.

pub fn remove_all<T, I>(
    &mut self,
    pathspecs: I,
    cb: Option<&mut IndexMatchedPath<'_>>
) -> Result<(), Error> where
    T: IntoCString,
    I: IntoIterator<Item = T>, 

Remove all matching index entries.

If you provide a callback function, it will be invoked on each matching item in the index immediately before it is removed. Return 0 to remove the item, > 0 to skip the item, and < 0 to abort the scan.

pub fn update_all<T, I>(
    &mut self,
    pathspecs: I,
    cb: Option<&mut IndexMatchedPath<'_>>
) -> Result<(), Error> where
    T: IntoCString,
    I: IntoIterator<Item = T>, 

Update all index entries to match the working directory

This method will fail in bare index instances.

This scans the existing index entries and synchronizes them with the working directory, deleting them if the corresponding working directory file no longer exists otherwise updating the information (including adding the latest version of file to the ODB if needed).

If you provide a callback function, it will be invoked on each matching item in the index immediately before it is updated (either refreshed or removed depending on working directory state). Return 0 to proceed with updating the item, > 0 to skip the item, and < 0 to abort the scan.

pub fn write(&mut self) -> Result<(), Error>

Write an existing index object from memory back to disk using an atomic file lock.

pub fn write_tree(&mut self) -> Result<Oid, Error>

Write the index as a tree.

This method will scan the index and write a representation of its current state back to disk; it recursively creates tree objects for each of the subtrees stored in the index, but only returns the OID of the root tree. This is the OID that can be used e.g. to create a commit.

The index instance cannot be bare, and needs to be associated to an existing repository.

The index must not contain any file in conflict.

pub fn write_tree_to(&mut self, repo: &Repository) -> Result<Oid, Error>

Write the index as a tree to the given repository

This is the same as write_tree except that the destination repository can be chosen.

Trait Implementations

impl Drop for Index

fn drop(&mut self)

Executes the destructor for this type.