index.h in rugged-0.21.0

- old
+ new

@@ -54,16 +54,16 @@
 	unsigned int mode;
 	unsigned int uid;
 	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;
 
 /**
  * Bitmasks for on-disk fields of `git_index_entry`'s `flags`
  *
@@ -71,61 +71,69 @@
  * value both in memory and on disk.  You can use them to interpret the
  * data in the `flags`.
  */
 #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`
  *
  * In memory, the `flags_extended` fields are divided into two parts: the
  * fields that are read from and written to disk, and other fields that
  * 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 = 1,
 	GIT_INDEXCAP_NO_FILEMODE = 2,
 	GIT_INDEXCAP_NO_SYMLINKS = 4,
-	GIT_INDEXCAP_FROM_OWNER  = ~0u
+	GIT_INDEXCAP_FROM_OWNER  = -1,
 } git_indexcap_t;
 
 /** Callback for APIs that add/remove/update files matching pathspec */
 typedef int (*git_index_matched_path_cb)(
 	const char *path, const char *matched_pathspec, void *payload);
@@ -136,10 +144,18 @@
 	GIT_INDEX_ADD_FORCE = (1u << 0),
 	GIT_INDEX_ADD_DISABLE_PATHSPEC_MATCH = (1u << 1),
 	GIT_INDEX_ADD_CHECK_PATHSPEC = (1u << 2),
 } git_index_add_option_t;
 
+/**
+ * Match any index stage.
+ *
+ * Some index APIs take a stage to match; pass this value to match
+ * any entry matching the path regardless of stage.
+ */
+#define GIT_INDEX_STAGE_ANY -1
+
 /** @name Index File Functions
  *
  * These functions work on the index file itself.
  */
 /**@{*/
@@ -148,12 +164,12 @@
  * 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. 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.
  *
  * The index must be freed once it's no longer in use.
@@ -196,11 +212,11 @@
  * Read index capabilities flags.
  *
  * @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.
  *
  * If you pass `GIT_INDEXCAP_FROM_OWNER` for the caps, then the
@@ -209,20 +225,30 @@
  *
  * @param index An existing index object
  * @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 from the hard disk.
+ * 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.
+ *
  * @param index an existing index object
+ * @param force if true, always reload, vs. only read if file has changed
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_index_read(git_index *index);
+GIT_EXTERN(int) git_index_read(git_index *index, int force);
 
 /**
  * Write an existing index object from memory back to disk
  * using an atomic file lock.
  *
@@ -230,10 +256,18 @@
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_index_write(git_index *index);
 
 /**
+ * Get the full path to the index file on disk.
+ *
+ * @param index an existing index object
+ * @return path to index file or NULL for in-memory index
+ */
+GIT_EXTERN(const char *) git_index_path(const git_index *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
@@ -299,16 +333,18 @@
  */
 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
  *
  * The entry is not modifiable and should not be freed.  Because the
@@ -377,14 +413,14 @@
 /**
  * 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
+ *    (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);
 
 /**@}*/
 
@@ -465,20 +501,20 @@
  *
  * 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 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
  * @param flags combination of git_index_add_option_t flags
  * @param callback notification callback for each added/updated path (also
  *                 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,
 	const git_strarray *pathspec,
 	unsigned int flags,
@@ -496,11 +532,11 @@
  * @param pathspec array of path patterns
  * @param callback notification callback for each removed path (also
  *                 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,
 	const git_strarray *pathspec,
 	git_index_matched_path_cb callback,
@@ -525,11 +561,11 @@
  * @param pathspec array of path patterns
  * @param callback notification callback for each updated path (also
  *                 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,
 	const git_strarray *pathspec,
 	git_index_matched_path_cb callback,
@@ -540,12 +576,11 @@
  * path in the Git index.
  *
  * @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);
 
 /**@}*/
 
@@ -585,10 +620,11 @@
  * @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 path path to search
+ * @return 0 or an error code
  */
 GIT_EXTERN(int) git_index_conflict_get(
 	const git_index_entry **ancestor_out,
 	const git_index_entry **our_out,
 	const git_index_entry **their_out,
@@ -597,31 +633,36 @@
 
 /**
  * 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.
  *
  * @return 1 if at least one conflict is found, 0 otherwise.
  */
 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(
 	git_index_conflict_iterator **iterator_out,
 	git_index *index);