diff options
Diffstat (limited to 'include/git2/index.h')
| -rw-r--r-- | include/git2/index.h | 125 |
1 files changed, 70 insertions, 55 deletions
diff --git a/include/git2/index.h b/include/git2/index.h index a60db370a..0b4476b4e 100644 --- a/include/git2/index.h +++ b/include/git2/index.h @@ -56,12 +56,12 @@ typedef struct git_index_entry { unsigned int gid; git_off_t file_size; - git_oid oid; + git_oid id; unsigned short flags; unsigned short flags_extended; - char *path; + const char *path; } git_index_entry; /** @@ -73,11 +73,19 @@ typedef struct git_index_entry { */ #define GIT_IDXENTRY_NAMEMASK (0x0fff) #define GIT_IDXENTRY_STAGEMASK (0x3000) -#define GIT_IDXENTRY_EXTENDED (0x4000) -#define GIT_IDXENTRY_VALID (0x8000) #define GIT_IDXENTRY_STAGESHIFT 12 -#define GIT_IDXENTRY_STAGE(E) (((E)->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT) +typedef enum { + GIT_IDXENTRY_EXTENDED = (0x4000), + GIT_IDXENTRY_VALID = (0x8000), +} git_indxentry_flag_t; + +#define GIT_IDXENTRY_STAGE(E) \ + (((E)->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT) + +#define GIT_IDXENTRY_STAGE_SET(E,S) do { \ + (E)->flags = ((E)->flags & ~GIT_IDXENTRY_STAGEMASK) | \ + (((S) & 0x03) << GIT_IDXENTRY_STAGESHIFT); } while (0) /** * Bitmasks for on-disk fields of `git_index_entry`'s `flags_extended` @@ -87,43 +95,43 @@ typedef struct git_index_entry { * in-memory only and used by libgit2. Only the flags in * `GIT_IDXENTRY_EXTENDED_FLAGS` will get saved on-disk. * - * These bitmasks match the three fields in the `git_index_entry` - * `flags_extended` value that belong on disk. You can use them to - * interpret the data in the `flags_extended`. + * Thee first three bitmasks match the three fields in the + * `git_index_entry` `flags_extended` value that belong on disk. You + * can use them to interpret the data in the `flags_extended`. + * + * The rest of the bitmasks match the other fields in the `git_index_entry` + * `flags_extended` value that are only used in-memory by libgit2. + * You can use them to interpret the data in the `flags_extended`. + * */ -#define GIT_IDXENTRY_INTENT_TO_ADD (1 << 13) -#define GIT_IDXENTRY_SKIP_WORKTREE (1 << 14) -/* GIT_IDXENTRY_EXTENDED2 is reserved for future extension */ -#define GIT_IDXENTRY_EXTENDED2 (1 << 15) +typedef enum { -#define GIT_IDXENTRY_EXTENDED_FLAGS (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE) + GIT_IDXENTRY_INTENT_TO_ADD = (1 << 13), + GIT_IDXENTRY_SKIP_WORKTREE = (1 << 14), + /** Reserved for future extension */ + GIT_IDXENTRY_EXTENDED2 = (1 << 15), -/** - * Bitmasks for in-memory only fields of `git_index_entry`'s `flags_extended` - * - * These bitmasks match the other fields in the `git_index_entry` - * `flags_extended` value that are only used in-memory by libgit2. You - * can use them to interpret the data in the `flags_extended`. - */ -#define GIT_IDXENTRY_UPDATE (1 << 0) -#define GIT_IDXENTRY_REMOVE (1 << 1) -#define GIT_IDXENTRY_UPTODATE (1 << 2) -#define GIT_IDXENTRY_ADDED (1 << 3) + GIT_IDXENTRY_EXTENDED_FLAGS = (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE), + GIT_IDXENTRY_UPDATE = (1 << 0), + GIT_IDXENTRY_REMOVE = (1 << 1), + GIT_IDXENTRY_UPTODATE = (1 << 2), + GIT_IDXENTRY_ADDED = (1 << 3), -#define GIT_IDXENTRY_HASHED (1 << 4) -#define GIT_IDXENTRY_UNHASHED (1 << 5) -#define GIT_IDXENTRY_WT_REMOVE (1 << 6) /* remove in work directory */ -#define GIT_IDXENTRY_CONFLICTED (1 << 7) + GIT_IDXENTRY_HASHED = (1 << 4), + GIT_IDXENTRY_UNHASHED = (1 << 5), + GIT_IDXENTRY_WT_REMOVE = (1 << 6), /**< remove in work directory */ + GIT_IDXENTRY_CONFLICTED = (1 << 7), -#define GIT_IDXENTRY_UNPACKED (1 << 8) -#define GIT_IDXENTRY_NEW_SKIP_WORKTREE (1 << 9) + GIT_IDXENTRY_UNPACKED = (1 << 8), + GIT_IDXENTRY_NEW_SKIP_WORKTREE = (1 << 9), +} git_idxentry_extended_flag_t; /** Capabilities of system that affect index actions. */ typedef enum { - GIT_INDEXCAP_IGNORE_CASE = 1u, - GIT_INDEXCAP_NO_FILEMODE = 2u, - GIT_INDEXCAP_NO_SYMLINKS = 4u, - GIT_INDEXCAP_FROM_OWNER = ~0u + GIT_INDEXCAP_IGNORE_CASE = 1, + GIT_INDEXCAP_NO_FILEMODE = 2, + GIT_INDEXCAP_NO_SYMLINKS = 4, + GIT_INDEXCAP_FROM_OWNER = -1, } git_indexcap_t; /** Callback for APIs that add/remove/update files matching pathspec */ @@ -158,8 +166,8 @@ typedef enum { * to back it. * * Since there is no ODB or working directory behind this index, - * any Index methods which rely on these (e.g. index_add) will - * fail with the GIT_EBAREINDEX error code. + * any Index methods which rely on these (e.g. index_add_bypath) + * will fail with the GIT_ERROR error code. * * If you need to access the index of an actual repository, * use the `git_repository_index` wrapper. @@ -206,7 +214,7 @@ GIT_EXTERN(git_repository *) git_index_owner(const git_index *index); * @param index An existing index object * @return A combination of GIT_INDEXCAP values */ -GIT_EXTERN(unsigned int) git_index_caps(const git_index *index); +GIT_EXTERN(int) git_index_caps(const git_index *index); /** * Set index capabilities flags. @@ -219,7 +227,7 @@ GIT_EXTERN(unsigned int) git_index_caps(const git_index *index); * @param caps A combination of GIT_INDEXCAP values * @return 0 on success, -1 on failure */ -GIT_EXTERN(int) git_index_set_caps(git_index *index, unsigned int caps); +GIT_EXTERN(int) git_index_set_caps(git_index *index, int caps); /** * Update the contents of an existing index object in memory by reading @@ -255,7 +263,7 @@ GIT_EXTERN(int) git_index_write(git_index *index); * @param index an existing index object * @return path to index file or NULL for in-memory index */ -GIT_EXTERN(const char *) git_index_path(git_index *index); +GIT_EXTERN(const char *) git_index_path(const git_index *index); /** * Read a tree into the index file with stats @@ -327,12 +335,14 @@ GIT_EXTERN(size_t) git_index_entrycount(const git_index *index); /** * 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. + * + * This clears the index object in memory; changes must be explicitly + * written to disk for them to take effect persistently. * * @param index an existing index object + * @return 0 on success, error code < 0 on failure */ -GIT_EXTERN(void) git_index_clear(git_index *index); +GIT_EXTERN(int) git_index_clear(git_index *index); /** * Get a pointer to one of the entries in the index @@ -405,10 +415,10 @@ GIT_EXTERN(int) git_index_add(git_index *index, const git_index_entry *source_en * * This entry is calculated from the entry's flag attribute like this: * - * (entry->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT + * (entry->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT * * @param entry The entry - * @returns the stage number + * @return the stage number */ GIT_EXTERN(int) git_index_entry_stage(const git_index_entry *entry); @@ -493,7 +503,7 @@ GIT_EXTERN(int) git_index_remove_bypath(git_index *index, const char *path); * 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 and cause GIT_EUSER to be returned. + * scan and return that value to the caller. * * @param index an existing index object * @param pathspec array of path patterns @@ -502,7 +512,7 @@ GIT_EXTERN(int) git_index_remove_bypath(git_index *index, const char *path); * gets index of matching pathspec entry); can be NULL; * return 0 to add, >0 to skip, <0 to abort scan. * @param payload payload passed through to callback function - * @return 0 or an error code + * @return 0 on success, negative callback return value, or error code */ GIT_EXTERN(int) git_index_add_all( git_index *index, @@ -524,7 +534,7 @@ GIT_EXTERN(int) git_index_add_all( * gets index of matching pathspec entry); can be NULL; * return 0 to add, >0 to skip, <0 to abort scan. * @param payload payload passed through to callback function - * @return 0 or an error code + * @return 0 on success, negative callback return value, or error code */ GIT_EXTERN(int) git_index_remove_all( git_index *index, @@ -553,7 +563,7 @@ GIT_EXTERN(int) git_index_remove_all( * gets index of matching pathspec entry); can be NULL; * return 0 to add, >0 to skip, <0 to abort scan. * @param payload payload passed through to callback function - * @return 0 or an error code + * @return 0 on success, negative callback return value, or error code */ GIT_EXTERN(int) git_index_update_all( git_index *index, @@ -568,8 +578,7 @@ GIT_EXTERN(int) git_index_update_all( * @param at_pos the address to which the position of the index entry is written (optional) * @param index an existing index object * @param path path to search - * @return a zero-based position in the index if found; - * GIT_ENOTFOUND otherwise + * @return a zero-based position in the index if found; GIT_ENOTFOUND otherwise */ GIT_EXTERN(int) git_index_find(size_t *at_pos, git_index *index, const char *path); @@ -613,6 +622,7 @@ GIT_EXTERN(int) git_index_conflict_add( * @param their_out Pointer to store the their entry * @param index an existing index object * @param path path to search + * @return 0 or an error code */ GIT_EXTERN(int) git_index_conflict_get( const git_index_entry **ancestor_out, @@ -625,16 +635,18 @@ GIT_EXTERN(int) git_index_conflict_get( * Removes the index entries that represent a conflict of a single file. * * @param index an existing index object - * @param path to search + * @param path path to remove conflicts for + * @return 0 or an error code */ 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.) + * Remove all conflicts in the index (entries with a stage greater than 0). * * @param index an existing index object + * @return 0 or an error code */ -GIT_EXTERN(void) git_index_conflict_cleanup(git_index *index); +GIT_EXTERN(int) git_index_conflict_cleanup(git_index *index); /** * Determine if the index contains entries representing file conflicts. @@ -644,9 +656,12 @@ GIT_EXTERN(void) git_index_conflict_cleanup(git_index *index); GIT_EXTERN(int) git_index_has_conflicts(const git_index *index); /** - * Create an iterator for the conflicts in the index. You may not modify the - * index while iterating, the results are undefined. + * Create an iterator for the conflicts in the index. + * + * The index must not be modified while iterating; the results are undefined. * + * @param iterator_out The newly created conflict iterator + * @param index The index to scan * @return 0 or an error code */ GIT_EXTERN(int) git_index_conflict_iterator_new( |