@@ -69,89 +69,132 @@ typedef int GIT_CALLBACK(git_status_cb)(
6969 * With `git_status_foreach_ext`, this will control which changes get
7070 * callbacks. With `git_status_list_new`, these will control which
7171 * changes are included in the list.
72- *
73- * - GIT_STATUS_SHOW_INDEX_AND_WORKDIR is the default. This roughly
74- * matches `git status --porcelain` regarding which files are
75- * included and in what order.
76- * - GIT_STATUS_SHOW_INDEX_ONLY only gives status based on HEAD to index
77- * comparison, not looking at working directory changes.
78- * - GIT_STATUS_SHOW_WORKDIR_ONLY only gives status based on index to
79- * working directory comparison, not comparing the index to the HEAD.
8072 */
8173typedef enum {
74+ /**
75+ * The default. This roughly matches `git status --porcelain` regarding
76+ * which files are included and in what order.
77+ */
8278 GIT_STATUS_SHOW_INDEX_AND_WORKDIR = 0 ,
79+
80+ /**
81+ * Only gives status based on HEAD to index comparison, not looking at
82+ * working directory changes.
83+ */
8384 GIT_STATUS_SHOW_INDEX_ONLY = 1 ,
85+
86+ /**
87+ * Only gives status based on index to working directory comparison,
88+ * not comparing the index to the HEAD.
89+ */
8490 GIT_STATUS_SHOW_WORKDIR_ONLY = 2 ,
8591} git_status_show_t ;
8692
8793/**
8894 * Flags to control status callbacks
8995 *
90- * - GIT_STATUS_OPT_INCLUDE_UNTRACKED says that callbacks should be made
91- * on untracked files. These will only be made if the workdir files are
92- * included in the status "show" option.
93- * - GIT_STATUS_OPT_INCLUDE_IGNORED says that ignored files get callbacks.
94- * Again, these callbacks will only be made if the workdir files are
95- * included in the status "show" option.
96- * - GIT_STATUS_OPT_INCLUDE_UNMODIFIED indicates that callback should be
97- * made even on unmodified files.
98- * - GIT_STATUS_OPT_EXCLUDE_SUBMODULES indicates that submodules should be
99- * skipped. This only applies if there are no pending typechanges to
100- * the submodule (either from or to another type).
101- * - GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS indicates that all files in
102- * untracked directories should be included. Normally if an entire
103- * directory is new, then just the top-level directory is included (with
104- * a trailing slash on the entry name). This flag says to include all
105- * of the individual files in the directory instead.
106- * - GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH indicates that the given path
107- * should be treated as a literal path, and not as a pathspec pattern.
108- * - GIT_STATUS_OPT_RECURSE_IGNORED_DIRS indicates that the contents of
109- * ignored directories should be included in the status. This is like
110- * doing `git ls-files -o -i --exclude-standard` with core git.
111- * - GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX indicates that rename detection
112- * should be processed between the head and the index and enables
113- * the GIT_STATUS_INDEX_RENAMED as a possible status flag.
114- * - GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR indicates that rename
115- * detection should be run between the index and the working directory
116- * and enabled GIT_STATUS_WT_RENAMED as a possible status flag.
117- * - GIT_STATUS_OPT_SORT_CASE_SENSITIVELY overrides the native case
118- * sensitivity for the file system and forces the output to be in
119- * case-sensitive order
120- * - GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY overrides the native case
121- * sensitivity for the file system and forces the output to be in
122- * case-insensitive order
123- * - GIT_STATUS_OPT_RENAMES_FROM_REWRITES indicates that rename detection
124- * should include rewritten files
125- * - GIT_STATUS_OPT_NO_REFRESH bypasses the default status behavior of
126- * doing a "soft" index reload (i.e. reloading the index data if the
127- * file on disk has been modified outside libgit2).
128- * - GIT_STATUS_OPT_UPDATE_INDEX tells libgit2 to refresh the stat cache
129- * in the index for files that are unchanged but have out of date stat
130- * information in the index. It will result in less work being done on
131- * subsequent calls to get status. This is mutually exclusive with the
132- * NO_REFRESH option.
133- *
13496 * Calling `git_status_foreach()` is like calling the extended version
13597 * with: GIT_STATUS_OPT_INCLUDE_IGNORED, GIT_STATUS_OPT_INCLUDE_UNTRACKED,
13698 * and GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS. Those options are bundled
13799 * together as `GIT_STATUS_OPT_DEFAULTS` if you want them as a baseline.
138100 */
139101typedef enum {
102+ /**
103+ * Says that callbacks should be made on untracked files.
104+ * These will only be made if the workdir files are included in the status
105+ * "show" option.
106+ */
140107 GIT_STATUS_OPT_INCLUDE_UNTRACKED = (1u << 0 ),
108+
109+ /**
110+ * Says that ignored files get callbacks.
111+ * Again, these callbacks will only be made if the workdir files are
112+ * included in the status "show" option.
113+ */
141114 GIT_STATUS_OPT_INCLUDE_IGNORED = (1u << 1 ),
115+
116+ /**
117+ * Indicates that callback should be made even on unmodified files.
118+ */
142119 GIT_STATUS_OPT_INCLUDE_UNMODIFIED = (1u << 2 ),
120+
121+ /**
122+ * Indicates that submodules should be skipped.
123+ * This only applies if there are no pending typechanges to the submodule
124+ * (either from or to another type).
125+ */
143126 GIT_STATUS_OPT_EXCLUDE_SUBMODULES = (1u << 3 ),
127+
128+ /**
129+ * Indicates that all files in untracked directories should be included.
130+ * Normally if an entire directory is new, then just the top-level
131+ * directory is included (with a trailing slash on the entry name).
132+ * This flag says to include all of the individual files in the directory
133+ * instead.
134+ */
144135 GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS = (1u << 4 ),
136+
137+ /**
138+ * Indicates that the given path should be treated as a literal path,
139+ * and not as a pathspec pattern.
140+ */
145141 GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH = (1u << 5 ),
142+
143+ /**
144+ * Indicates that the contents of ignored directories should be included
145+ * in the status. This is like doing `git ls-files -o -i --exclude-standard`
146+ * with core git.
147+ */
146148 GIT_STATUS_OPT_RECURSE_IGNORED_DIRS = (1u << 6 ),
149+
150+ /**
151+ * Indicates that rename detection should be processed between the head and
152+ * the index and enables the GIT_STATUS_INDEX_RENAMED as a possible status
153+ * flag.
154+ */
147155 GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX = (1u << 7 ),
156+
157+ /**
158+ * Indicates that rename detection should be run between the index and the
159+ * working directory and enabled GIT_STATUS_WT_RENAMED as a possible status
160+ * flag.
161+ */
148162 GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR = (1u << 8 ),
163+
164+ /**
165+ * Overrides the native case sensitivity for the file system and forces
166+ * the output to be in case-sensitive order.
167+ */
149168 GIT_STATUS_OPT_SORT_CASE_SENSITIVELY = (1u << 9 ),
169+
170+ /**
171+ * Overrides the native case sensitivity for the file system and forces
172+ * the output to be in case-insensitive order.
173+ */
150174 GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY = (1u << 10 ),
175+
176+ /**
177+ * Iindicates that rename detection should include rewritten files.
178+ */
151179 GIT_STATUS_OPT_RENAMES_FROM_REWRITES = (1u << 11 ),
180+
181+ /**
182+ * Bypasses the default status behavior of doing a "soft" index reload
183+ * (i.e. reloading the index data if the file on disk has been modified
184+ * outside libgit2).
185+ */
152186 GIT_STATUS_OPT_NO_REFRESH = (1u << 12 ),
187+
188+ /**
189+ * Tells libgit2 to refresh the stat cache in the index for files that are
190+ * unchanged but have out of date stat einformation in the index.
191+ * It will result in less work being done on subsequent calls to get status.
192+ * This is mutually exclusive with the NO_REFRESH option.
193+ */
153194 GIT_STATUS_OPT_UPDATE_INDEX = (1u << 13 ),
195+
154196 GIT_STATUS_OPT_INCLUDE_UNREADABLE = (1u << 14 ),
197+
155198 GIT_STATUS_OPT_INCLUDE_UNREADABLE_AS_UNTRACKED = (1u << 15 ),
156199} git_status_opt_t ;
157200
0 commit comments