Stefan Beller <sbeller@xxxxxxxxxx> writes: > Signed-off-by: Stefan Beller <sbeller@xxxxxxxxxx> > --- > >> These placeholders are meant to encourage those people who dove into >> the code to update it, so from that point of view, I think removing >> it is backwards. > > Yes, I am currently understanding and writing up documentation for > index_name_pos. If I recall the latest discussion where we want to have > documentation, I think a quorum favored documentation in the header itself, > c.f. strbuf.h, string-list.h for the most desired state. (Although we do have > Documentation/technical/api-string-list.txt as well ...) > > So maybe starting like this? That is very good. Let's drop that file from Documentation/technical and do it like this (meaning, take both patches from you). Thanks. > > Thanks, > Stefan > > cache.h | 13 +++++++++++++ > 1 file changed, 13 insertions(+) > > diff --git a/cache.h b/cache.h > index 1b67f078dd..e168e4e073 100644 > --- a/cache.h > +++ b/cache.h > @@ -575,7 +575,20 @@ extern int verify_path(const char *path); > extern int index_dir_exists(struct index_state *istate, const char *name, int namelen); > extern void adjust_dirname_case(struct index_state *istate, char *name); > extern struct cache_entry *index_file_exists(struct index_state *istate, const char *name, int namelen, int igncase); > + > +/* > + * Searches for an entry defined by name and namelen in the given index. > + * If the return value is positive (including 0) it is the position of an > + * exact match. If the return value is negative, the negated value minus 1 is the > + * position where the entry would be inserted. > + * Example: In the current index we have the files a,c,d: > + * index_name_pos(&index, "a", 1) -> 0 > + * index_name_pos(&index, "b", 1) -> -1 > + * index_name_pos(&index, "c", 1) -> 1 > + * index_name_pos(&index, "d", 1) -> 2 > + */ > extern int index_name_pos(const struct index_state *, const char *name, int namelen); > + > #define ADD_CACHE_OK_TO_ADD 1 /* Ok to add */ > #define ADD_CACHE_OK_TO_REPLACE 2 /* Ok to replace file/directory */ > #define ADD_CACHE_SKIP_DFCHECK 4 /* Ok to skip DF conflict checks */