Thegit.index.util.post_clear_cache decorator has this note in its docstring:

This decorator is applied to themerge_tree,move, andremove methods ofgit.index.IndexFile (and nowhere else).

As such, that note in the decorator's docstring suggests an intended design direction for theIndexFile implementation in GitPython: that, if performance considerations permit, it should eventually make little to no use ofgit commands, unlike GitPython as a whole.

By now, my guess is that the intended direction is known, and my (somewhat less certain) guess is that this goal may have been abandoned, becuase:

• GitPython is considered to be in maintenance mode (perthe README).
• In a review comment, if I understood correctly, you have expressed the hope thatIndexFile is not heavily used, due to not having reached some of its original design goals.

However, there is also now a longer-term vision for GitPython, beyond maintaining the current feature set, articulated inGitoxideLabs/gitoxide#1074 under "GitPython…".

If in the future theIndexFile implementation will be rewritten to use gitoxide's (future) Python bindings, then this docstring note is actually ofgreater relevance than before. But then it should still be updated to no longer characterize the aspiration to implement all ofIndexFile without git subprocess calls as infeasible for performance reasons. And possibly even to mention gitoxide?

Because of that, I'm unsure if this note should be removed or updated (if, if updated, then how), or simply left as-is for the time being.