diff options
Diffstat (limited to 'include/git2/index.h')
| -rw-r--r-- | include/git2/index.h | 296 |
1 files changed, 208 insertions, 88 deletions
diff --git a/include/git2/index.h b/include/git2/index.h index e8af3620d..1d91663d8 100644 --- a/include/git2/index.h +++ b/include/git2/index.h @@ -84,12 +84,12 @@ typedef struct git_index_entry { char *path; } git_index_entry; -/** Representation of an unmerged file entry in the index. */ -typedef struct git_index_entry_unmerged { +/** Representation of a resolve undo entry in the index. */ +typedef struct git_index_reuc_entry { unsigned int mode[3]; git_oid oid[3]; char *path; -} git_index_entry_unmerged; +} git_index_reuc_entry; /** Capabilities of system that affect index actions. */ enum { @@ -99,6 +99,12 @@ enum { GIT_INDEXCAP_FROM_OWNER = ~0u }; +/** @name Index File Functions + * + * These functions work on the index file itself. + */ +/**@{*/ + /** * Create a new bare Git index object as a memory representation * of the Git index file in 'index_path', without a repository @@ -120,20 +126,19 @@ enum { GIT_EXTERN(int) git_index_open(git_index **index, const char *index_path); /** - * Clear the contents (all the entries) of an index object. - * This clears the index object in memory; changes must be manually - * written to disk for them to take effect. + * Free an existing index object. * * @param index an existing index object */ -GIT_EXTERN(void) git_index_clear(git_index *index); +GIT_EXTERN(void) git_index_free(git_index *index); /** - * Free an existing index object. + * Get the repository this index relates to * - * @param index an existing index object + * @param index The index + * @return A pointer to the repository */ -GIT_EXTERN(void) git_index_free(git_index *index); +GIT_EXTERN(git_repository *) git_index_owner(const git_index *index); /** * Read index capabilities flags. @@ -175,44 +180,92 @@ GIT_EXTERN(int) git_index_read(git_index *index); GIT_EXTERN(int) git_index_write(git_index *index); /** - * Find the first index of any entries which point to given - * path in the Git index. + * Read a tree into the index file with stats + * + * The current index contents will be replaced by the specified tree. * * @param index an existing index object - * @param path path to search - * @return an index >= 0 if found, -1 otherwise + * @param tree tree to read + * @return 0 or an error code */ -GIT_EXTERN(int) git_index_find(git_index *index, const char *path); +GIT_EXTERN(int) git_index_read_tree(git_index *index, git_tree *tree); + +/**@}*/ + +/** @name Raw Index Entry Functions + * + * These functions work on index entries, and allow for raw manipulation + * of the entries. + */ +/**@{*/ + +/* Index entry manipulation */ /** - * Remove all entries with equal path except last added + * Get the count of entries currently in the index * * @param index an existing index object + * @return integer of count of current entries */ -GIT_EXTERN(void) git_index_uniq(git_index *index); +GIT_EXTERN(unsigned int) git_index_entrycount(git_index *index); /** - * Add or update an index entry from a file in disk + * Clear the contents (all the entries) of an index object. + * This clears the index object in memory; changes must be manually + * written to disk for them to take effect. * - * The file `path` must be relative to the repository's - * working folder and must be readable. + * @param index an existing index object + */ +GIT_EXTERN(void) git_index_clear(git_index *index); + +/** + * Get a pointer to one of the entries in the index * - * This method will fail in bare index instances. + * The values of this entry can be modified (except the path) + * and the changes will be written back to disk on the next + * write() call. * - * This forces the file to be added to the index, not looking - * at gitignore rules. Those rules can be evaluated through - * the git_status APIs (in status.h) before calling this. + * The entry should not be freed by the caller. * * @param index an existing index object - * @param path filename to add - * @param stage stage for the entry + * @param n the position of the entry + * @return a pointer to the entry; NULL if out of bounds + */ +GIT_EXTERN(git_index_entry *) git_index_get_byindex(git_index *index, size_t n); + +/** + * Get a pointer to one of the entries in the index + * + * The values of this entry can be modified (except the path) + * and the changes will be written back to disk on the next + * write() call. + * + * The entry should not be freed by the caller. + * + * @param index an existing index object + * @param path path to search + * @param stage stage to search + * @return a pointer to the entry; NULL if it was not found + */ +GIT_EXTERN(git_index_entry *) git_index_get_bypath(git_index *index, const char *path, int stage); + +/** + * Remove an entry from the index + * + * @param index an existing index object + * @param path path to search + * @param stage stage to search * @return 0 or an error code */ -GIT_EXTERN(int) git_index_add(git_index *index, const char *path, int stage); +GIT_EXTERN(int) git_index_remove(git_index *index, const char *path, int stage); /** * 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. + * * A full copy (including the 'path' string) of the given * 'source_entry' will be inserted on the index. * @@ -220,140 +273,207 @@ GIT_EXTERN(int) git_index_add(git_index *index, const char *path, int stage); * @param source_entry new entry object * @return 0 or an error code */ -GIT_EXTERN(int) git_index_add2(git_index *index, const git_index_entry *source_entry); +GIT_EXTERN(int) git_index_add(git_index *index, const git_index_entry *source_entry); /** - * Add (append) an index entry from a file in disk + * Return the stage number from a git index entry + * + * This entry is calculated from the entry's flag + * attribute like this: + * + * (entry->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT * - * A new entry will always be inserted into the index; - * if the index already contains an entry for such - * path, the old entry will **not** be replaced. + * @param entry The entry + * @returns the stage number + */ +GIT_EXTERN(int) git_index_entry_stage(const git_index_entry *entry); + +/**@}*/ + +/** @name Workdir Index Entry Functions + * + * These functions work on index entries specifically in the working + * directory (ie, stage 0). + */ +/**@{*/ + +/** + * Add or update an index entry from a file in 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. Those rules can be evaluated through + * the git_status APIs (in status.h) before calling this. + * + * 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. + * * @param index an existing index object * @param path filename to add - * @param stage stage for the entry * @return 0 or an error code */ -GIT_EXTERN(int) git_index_append(git_index *index, const char *path, int stage); +GIT_EXTERN(int) git_index_add_from_workdir(git_index *index, const char *path); /** - * Add (append) an index entry from an in-memory struct + * Find the first index of any entries which point to given + * path in the Git index. * - * A new entry will always be inserted into the index; - * if the index already contains an entry for the path - * in the `entry` struct, the old entry will **not** be - * replaced. + * @param index an existing index object + * @param path path to search + * @return an index >= 0 if found, -1 otherwise + */ +GIT_EXTERN(int) git_index_find(git_index *index, const char *path); + +/**@}*/ + +/** @name Conflict Index Entry Functions * - * A full copy (including the 'path' string) of the given - * 'source_entry' will be inserted on the index. + * These functions work on conflict index entries specifically (ie, stages 1-3) + */ +/**@{*/ + +/** + * Add or update index entries to represent a conflict + * + * The entries are the entries from the tree included in the merge. Any + * entry may be null to indicate that that file was not present in the + * trees during the merge. For example, ancestor_entry may be NULL to + * indicate that a file was added in both branches and must be resolved. * * @param index an existing index object - * @param source_entry new entry object + * @param ancestor_entry the entry data for the ancestor of the conflict + * @param our_entry the entry data for our side of the merge conflict + * @param their_entry the entry data for their side of the merge conflict * @return 0 or an error code */ -GIT_EXTERN(int) git_index_append2(git_index *index, const git_index_entry *source_entry); +GIT_EXTERN(int) git_index_conflict_add(git_index *index, + const git_index_entry *ancestor_entry, + const git_index_entry *our_entry, + const git_index_entry *their_entry); /** - * Remove an entry from the index + * Get the index entries that represent a conflict of a single file. * + * The values of this entry can be modified (except the paths) + * and the changes will be written back to disk on the next + * write() call. + * + * @param ancestor_out Pointer to store the ancestor entry + * @param our_out Pointer to store the our entry + * @param their_out Pointer to store the their entry * @param index an existing index object - * @param position position of the entry to remove - * @return 0 or an error code + * @param path path to search */ -GIT_EXTERN(int) git_index_remove(git_index *index, int position); - +GIT_EXTERN(int) git_index_conflict_get(git_index_entry **ancestor_out, git_index_entry **our_out, git_index_entry **their_out, git_index *index, const char *path); /** - * Get a pointer to one of the entries in the index - * - * This entry can be modified, and the changes will be written - * back to disk on the next write() call. + * Removes the index entries that represent a conflict of a single file. * - * The entry should not be freed by the caller. + * @param index an existing index object + * @param path to search + */ +GIT_EXTERN(int) git_index_conflict_remove(git_index *index, const char *path); + +/** + * Remove all conflicts in the index (entries with a stage greater than 0.) * * @param index an existing index object - * @param n the position of the entry - * @return a pointer to the entry; NULL if out of bounds */ -GIT_EXTERN(git_index_entry *) git_index_get(git_index *index, size_t n); +GIT_EXTERN(void) git_index_conflict_cleanup(git_index *index); + +/**@}*/ + +/** @name Resolve Undo (REUC) index entry manipulation. + * + * These functions work on the Resolve Undo index extension and contains + * data about the original files that led to a merge conflict. + */ +/**@{*/ /** - * Get the count of entries currently in the index + * Get the count of resolve undo entries currently in the index. * * @param index an existing index object - * @return integer of count of current entries + * @return integer of count of current resolve undo entries */ -GIT_EXTERN(unsigned int) git_index_entrycount(git_index *index); +GIT_EXTERN(unsigned int) git_index_reuc_entrycount(git_index *index); /** - * Get the count of unmerged entries currently in the index + * Finds the resolve undo entry that points to the given path in the Git + * index. * * @param index an existing index object - * @return integer of count of current unmerged entries + * @param path path to search + * @return an index >= 0 if found, -1 otherwise */ -GIT_EXTERN(unsigned int) git_index_entrycount_unmerged(git_index *index); +GIT_EXTERN(int) git_index_reuc_find(git_index *index, const char *path); /** - * Get an unmerged entry from the index. + * Get a resolve undo entry from the index. * * The returned entry is read-only and should not be modified * of freed by the caller. * * @param index an existing index object * @param path path to search - * @return the unmerged entry; NULL if not found + * @return the resolve undo entry; NULL if not found */ -GIT_EXTERN(const git_index_entry_unmerged *) git_index_get_unmerged_bypath(git_index *index, const char *path); +GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_bypath(git_index *index, const char *path); /** - * Get an unmerged entry from the index. + * Get a resolve undo entry from the index. * * The returned entry is read-only and should not be modified * of freed by the caller. * * @param index an existing index object * @param n the position of the entry - * @return a pointer to the unmerged entry; NULL if out of bounds + * @return a pointer to the resolve undo entry; NULL if out of bounds */ -GIT_EXTERN(const git_index_entry_unmerged *) git_index_get_unmerged_byindex(git_index *index, size_t n); +GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_byindex(git_index *index, size_t n); /** - * Return the stage number from a git index entry + * Adds an resolve undo entry for a file based on the given parameters. * - * This entry is calculated from the entry's flag - * attribute like this: + * The resolve undo entry contains the OIDs of files that were involved + * in a merge conflict after the conflict has been resolved. This allows + * conflicts to be re-resolved later. * - * (entry->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT + * If there exists a resolve undo entry for the given path in the index, + * it will be removed. * - * @param entry The entry - * @returns the stage number - */ -GIT_EXTERN(int) git_index_entry_stage(const git_index_entry *entry); - -/** - * Read a tree into the index file with stats - * - * The current index contents will be replaced by the specified tree. The total - * node count is collected in stats. + * This method will fail in bare index instances. * * @param index an existing index object - * @param tree tree to read + * @param path filename to add + * @param ancestor_mode mode of the ancestor file + * @param ancestor_oid oid of the ancestor file + * @param our_mode mode of our file + * @param our_oid oid of our file + * @param their_mode mode of their file + * @param their_oid oid of their file * @return 0 or an error code */ -GIT_EXTERN(int) git_index_read_tree(git_index *index, git_tree *tree); +GIT_EXTERN(int) git_index_reuc_add(git_index *index, const char *path, + int ancestor_mode, git_oid *ancestor_oid, + int our_mode, git_oid *our_oid, + int their_mode, git_oid *their_oid); /** - * Get the repository this index relates to + * Remove an resolve undo entry from the index * - * @param index The index - * @return A pointer to the repository + * @param index an existing index object + * @param position position of the resolve undo entry to remove + * @return 0 or an error code */ -GIT_EXTERN(git_repository *) git_index_owner(const git_index *index); +GIT_EXTERN(int) git_index_reuc_remove(git_index *index, int position); + +/**@}*/ /** @} */ GIT_END_DECL |