In libgit2, what do the git_index_entry->flags_extended mean (and when are they set)?

Question

I am attempting to manage a repository's index vs. its HEAD tree using libgit2 (via Objective-Git, but I'm increasingly finding myself heading down the vanilla libgit2 rabbit hole), and am wondering what exactly the flags_extended field's bitmasks on git_index_entry struct actually mean. Additionally, when are these flags set? I've been digging through the libgit2 source, but cannot seem to find where flags_extended comes into play.

The reason I ask:

I have a simple test repository with one commit containing some simple test files. The working copy has one tracked file with a minor change and one untracked file, both of which have been staged externally (git add . on the commandline). In my application, I need to "unstage" the files, so I fetch their respective git_index_entry structs. I was expecting the flags_extended to have GIT_IDXENTRY_UPDATED set for the modified file and GIT_IDXENTRY_ADDED set for the previously untracked file, but in fact both flags_extended fields are empty, which is what prompted this question (the only thing set is the GIT_IDX_ENTRY_NAMEMASK in the flags field).

I can certainly fetch the HEAD tree and compare the entries with the entries in the index, but I was hoping that libgit2 was already providing that info via the flags_extended.

Answer 1

I was expecting the flags_extended to have GIT_IDXENTRY_UPDATED set for the modified file and GIT_IDXENTRY_ADDED set for the previously untracked file.

No, these flags are fundamentally internal to libgit2. They are used to maintain the information about index entries in-memory after loading the index from disk. They are to prevent and/or detect internal data races, they are not for determining the status of your repository.

If you want to compare the HEAD to the index, load the HEAD tree and then use git_diff_tree_to_index.