status: document `GIT_STATUS_OPT_INCLUDE_UNREADABLE` Document `GIT_STATUS_OPT_INCLUDE_UNREADABLE`, and some minor cleanups.
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 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185
diff --git a/include/git2/blame.h b/include/git2/blame.h
index 566d4db..d193ce1 100644
--- a/include/git2/blame.h
+++ b/include/git2/blame.h
@@ -26,27 +26,52 @@ GIT_BEGIN_DECL
typedef enum {
/** Normal blame, the default */
GIT_BLAME_NORMAL = 0,
- /** Track lines that have moved within a file (like `git blame -M`).
- * NOT IMPLEMENTED. */
+
+ /**
+ * Track lines that have moved within a file (like `git blame -M`).
+ *
+ * This is not yet implemented and reserved for future use.
+ */
GIT_BLAME_TRACK_COPIES_SAME_FILE = (1<<0),
- /** Track lines that have moved across files in the same commit (like `git blame -C`).
- * NOT IMPLEMENTED. */
+
+ /**
+ * Track lines that have moved across files in the same commit
+ * (like `git blame -C`).
+ *
+ * This is not yet implemented and reserved for future use.
+ */
GIT_BLAME_TRACK_COPIES_SAME_COMMIT_MOVES = (1<<1),
- /** Track lines that have been copied from another file that exists in the
- * same commit (like `git blame -CC`). Implies SAME_FILE.
- * NOT IMPLEMENTED. */
+
+ /**
+ * Track lines that have been copied from another file that exists
+ * in the same commit (like `git blame -CC`). Implies SAME_FILE.
+ *
+ * This is not yet implemented and reserved for future use.
+ */
GIT_BLAME_TRACK_COPIES_SAME_COMMIT_COPIES = (1<<2),
- /** Track lines that have been copied from another file that exists in *any*
- * commit (like `git blame -CCC`). Implies SAME_COMMIT_COPIES.
- * NOT IMPLEMENTED. */
+
+ /**
+ * Track lines that have been copied from another file that exists in
+ * *any* commit (like `git blame -CCC`). Implies SAME_COMMIT_COPIES.
+ *
+ * This is not yet implemented and reserved for future use.
+ */
GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES = (1<<3),
- /** Restrict the search of commits to those reachable following only the
- * first parents. */
+
+ /**
+ * Restrict the search of commits to those reachable following only
+ * the first parents.
+ */
GIT_BLAME_FIRST_PARENT = (1<<4),
- /** Use mailmap file to map author and committer names and email addresses
- * to canonical real names and email addresses. The mailmap will be read
- * from the working directory, or HEAD in a bare repository. */
+
+ /**
+ * Use mailmap file to map author and committer names and email
+ * addresses to canonical real names and email addresses. The
+ * mailmap will be read from the working directory, or HEAD in a
+ * bare repository.
+ */
GIT_BLAME_USE_MAILMAP = (1<<5),
+
/** Ignore whitespace differences */
GIT_BLAME_IGNORE_WHITESPACE = (1<<6),
} git_blame_flag_t;
@@ -63,25 +88,33 @@ typedef struct git_blame_options {
/** A combination of `git_blame_flag_t` */
uint32_t flags;
- /** The lower bound on the number of alphanumeric
- * characters that must be detected as moving/copying within a file for it to
- * associate those lines with the parent commit. The default value is 20.
- * This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*`
- * flags are specified.
+
+ /**
+ * The lower bound on the number of alphanumeric characters that
+ * must be detected as moving/copying within a file for it to
+ * associate those lines with the parent commit. The default value
+ * is 20.
+ *
+ * This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*`
+ * flags are specified.
*/
uint16_t min_match_characters;
+
/** The id of the newest commit to consider. The default is HEAD. */
git_oid newest_commit;
+
/**
* The id of the oldest commit to consider.
* The default is the first commit encountered with a NULL parent.
*/
git_oid oldest_commit;
+
/**
* The first line in the file to blame.
* The default is 1 (line numbers start with 1).
*/
size_t min_line;
+
/**
* The last line in the file to blame.
* The default is the last line of the file.
@@ -158,8 +191,8 @@ typedef struct git_blame_hunk {
git_signature *orig_signature;
/**
- * The 1 iff the hunk has been tracked to a boundary commit (the root, or
- * the commit specified in git_blame_options.oldest_commit)
+ * The 1 iff the hunk has been tracked to a boundary commit (the root,
+ * or the commit specified in git_blame_options.oldest_commit)
*/
char boundary;
} git_blame_hunk;
diff --git a/include/git2/status.h b/include/git2/status.h
index ed9856a..543e3fa 100644
--- a/include/git2/status.h
+++ b/include/git2/status.h
@@ -193,8 +193,17 @@ typedef enum {
*/
GIT_STATUS_OPT_UPDATE_INDEX = (1u << 13),
+ /**
+ * Normally files that cannot be opened or read are ignored as
+ * these are often transient files; this option will return
+ * unreadable files as `GIT_STATUS_WT_UNREADABLE`.
+ */
GIT_STATUS_OPT_INCLUDE_UNREADABLE = (1u << 14),
+ /**
+ * Unreadable files will be detected and given the status
+ * untracked instead of unreadable.
+ */
GIT_STATUS_OPT_INCLUDE_UNREADABLE_AS_UNTRACKED = (1u << 15),
} git_status_opt_t;
@@ -211,7 +220,10 @@ typedef enum {
*
*/
typedef struct {
- unsigned int version; /**< The version */
+ /**
+ * The struct version; pass `GIT_STATUS_OPTIONS_VERSION`.
+ */
+ unsigned int version;
/**
* The `show` value is one of the `git_status_show_t` constants that
@@ -220,21 +232,22 @@ typedef struct {
git_status_show_t show;
/**
- * The `flags` value is an OR'ed combination of the `git_status_opt_t`
- * values above.
+ * The `flags` value is an OR'ed combination of the
+ * `git_status_opt_t` values above.
*/
unsigned int flags;
/**
* The `pathspec` is an array of path patterns to match (using
- * fnmatch-style matching), or just an array of paths to match exactly if
- * `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified in the flags.
+ * fnmatch-style matching), or just an array of paths to match
+ * exactly if `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified
+ * in the flags.
*/
git_strarray pathspec;
/**
- * The `baseline` is the tree to be used for comparison to the working directory
- * and index; defaults to HEAD.
+ * The `baseline` is the tree to be used for comparison to the
+ * working directory and index; defaults to HEAD.
*/
git_tree *baseline;
} git_status_options;