Commit 487884a9306e744eaebe659a7d0edb1c0c6c7ba7
2013-05-13T16:07:29
Improve docs for git_index_entry flag masks The constants for extracting data from git_index_entry flags and flags_extended are not named in a way that makes it easy to know where to use each one. This improves the docs for the flags (and slightly reorganizes them), so it should be more obvious.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
diff --git a/include/git2/index.h b/include/git2/index.h
index bde38a9..42cc4d6 100644
--- a/include/git2/index.h
+++ b/include/git2/index.h
@@ -21,18 +21,44 @@
*/
GIT_BEGIN_DECL
+/**
+ * Bitmasks for on-disk fields of `git_index_entry` `flags`
+ *
+ * These bitmasks match the four fields in the `git_index_entry` `flags`
+ * 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
-/*
- * Flags are divided into two parts: in-memory flags and
- * on-disk ones. Flags in GIT_IDXENTRY_EXTENDED_FLAGS
- * will get saved on-disk.
+/**
+ * Bitmasks for on-disk fields of `git_index_entry` `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`.
+ */
+#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)
+
+#define GIT_IDXENTRY_EXTENDED_FLAGS (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE)
+
+/**
+ * Bitmasks for in-memory only fields of `git_index_entry` `flags_extended`
*
- * In-memory only flags:
+ * 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)
@@ -47,15 +73,6 @@ GIT_BEGIN_DECL
#define GIT_IDXENTRY_UNPACKED (1 << 8)
#define GIT_IDXENTRY_NEW_SKIP_WORKTREE (1 << 9)
-/*
- * Extended on-disk flags:
- */
-#define GIT_IDXENTRY_INTENT_TO_ADD (1 << 13)
-#define GIT_IDXENTRY_SKIP_WORKTREE (1 << 14)
-/* GIT_IDXENTRY_EXTENDED2 is for future extension */
-#define GIT_IDXENTRY_EXTENDED2 (1 << 15)
-
-#define GIT_IDXENTRY_EXTENDED_FLAGS (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE)
#define GIT_IDXENTRY_STAGE(E) (((E)->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT)
@@ -87,12 +104,12 @@ typedef struct git_index_entry {
} git_index_entry;
/** Capabilities of system that affect index actions. */
-enum {
+typedef enum {
GIT_INDEXCAP_IGNORE_CASE = 1,
GIT_INDEXCAP_NO_FILEMODE = 2,
GIT_INDEXCAP_NO_SYMLINKS = 4,
GIT_INDEXCAP_FROM_OWNER = ~0u
-};
+} git_indexcap_t;
/** @name Index File Functions
*
@@ -429,7 +446,7 @@ GIT_EXTERN(int) git_index_find(size_t *at_pos, git_index *index, const char *pat
* @return 0 or an error code
*/
GIT_EXTERN(int) git_index_conflict_add(
- git_index *index,
+ git_index *index,
const git_index_entry *ancestor_entry,
const git_index_entry *our_entry,
const git_index_entry *their_entry);
@@ -447,7 +464,12 @@ GIT_EXTERN(int) git_index_conflict_add(
* @param index an existing index object
* @param path path to search
*/
-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);
+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);
/**
* Removes the index entries that represent a conflict of a single file.