Struct git2::Index

source · []
pub struct Index { /* private fields */ }
Expand description

A structure to represent a git index

Implementations

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.

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.

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.

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.

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.

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.

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.

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();

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_*.

Get the count of entries currently in the index

Return true is there is no entry in the index

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

Get an iterator over the entries in this index.

Get an iterator over the index entries that have conflicts

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

Does this index have conflicts?

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

Get the full path to the index file on disk.

Returns None if this is an in-memory index.

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.

Read a tree into the index file with stats

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

Remove an entry from the index

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.

Remove all entries from the index under a given directory.

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.

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.

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

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.

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

Executes the destructor for this type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.