From 12733e9dd39411be4cd6a9a437faa7d86df159c2 Mon Sep 17 00:00:00 2001 From: Stefan Beller Date: Wed, 18 Jan 2017 19:18:51 -0800 Subject: cache.h: document index_name_pos Signed-off-by: Stefan Beller Signed-off-by: Junio C Hamano diff --git a/cache.h b/cache.h index a50a61a..83c8c26 100644 --- a/cache.h +++ b/cache.h @@ -575,7 +575,26 @@ 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: The current index consists of these files and its stages: + * + * b#0, d#0, f#1, f#3 + * + * index_name_pos(&index, "a", 1) -> -1 + * index_name_pos(&index, "b", 1) -> 0 + * index_name_pos(&index, "c", 1) -> -2 + * index_name_pos(&index, "d", 1) -> 1 + * index_name_pos(&index, "e", 1) -> -3 + * index_name_pos(&index, "f", 1) -> -3 + * index_name_pos(&index, "g", 1) -> -5 + */ 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 */ -- cgit v0.10.2-6-g49f6 From 3bd72adff1f4435898508f5c74227aaa2561c182 Mon Sep 17 00:00:00 2001 From: Stefan Beller Date: Wed, 18 Jan 2017 19:18:52 -0800 Subject: cache.h: document remove_index_entry_at Do this by moving the existing documentation from read-cache.c to cache.h. Signed-off-by: Stefan Beller Signed-off-by: Junio C Hamano diff --git a/cache.h b/cache.h index 83c8c26..c8b881a 100644 --- a/cache.h +++ b/cache.h @@ -603,7 +603,10 @@ extern int index_name_pos(const struct index_state *, const char *name, int name #define ADD_CACHE_KEEP_CACHE_TREE 32 /* Do not invalidate cache-tree */ extern int add_index_entry(struct index_state *, struct cache_entry *ce, int option); extern void rename_index_entry_at(struct index_state *, int pos, const char *new_name); + +/* Remove entry, return true if there are more entries to go. */ extern int remove_index_entry_at(struct index_state *, int pos); + extern void remove_marked_cache_entries(struct index_state *istate); extern int remove_file_from_index(struct index_state *, const char *path); #define ADD_CACHE_VERBOSE 1 diff --git a/read-cache.c b/read-cache.c index db5d910..585ff02 100644 --- a/read-cache.c +++ b/read-cache.c @@ -510,7 +510,6 @@ int index_name_pos(const struct index_state *istate, const char *name, int namel return index_name_stage_pos(istate, name, namelen, 0); } -/* Remove entry, return true if there are more entries to go.. */ int remove_index_entry_at(struct index_state *istate, int pos) { struct cache_entry *ce = istate->cache[pos]; -- cgit v0.10.2-6-g49f6 From 20cf41d02158cbb838faec70ad1d989172fc592f Mon Sep 17 00:00:00 2001 From: Stefan Beller Date: Wed, 18 Jan 2017 19:18:53 -0800 Subject: cache.h: document add_[file_]to_index Helped-by: Junio C Hamano Signed-off-by: Stefan Beller Signed-off-by: Junio C Hamano diff --git a/cache.h b/cache.h index c8b881a..b36b4fa 100644 --- a/cache.h +++ b/cache.h @@ -614,8 +614,18 @@ extern int remove_file_from_index(struct index_state *, const char *path); #define ADD_CACHE_IGNORE_ERRORS 4 #define ADD_CACHE_IGNORE_REMOVAL 8 #define ADD_CACHE_INTENT 16 +/* + * These two are used to add the contents of the file at path + * to the index, marking the working tree up-to-date by storing + * the cached stat info in the resulting cache entry. A caller + * that has already run lstat(2) on the path can call + * add_to_index(), and all others can call add_file_to_index(); + * the latter will do necessary lstat(2) internally before + * calling the former. + */ extern int add_to_index(struct index_state *, const char *path, struct stat *, int flags); extern int add_file_to_index(struct index_state *, const char *path, int flags); + extern struct cache_entry *make_cache_entry(unsigned int mode, const unsigned char *sha1, const char *path, int stage, unsigned int refresh_options); extern int chmod_index_entry(struct index_state *, struct cache_entry *ce, char flip); extern int ce_same_name(const struct cache_entry *a, const struct cache_entry *b); -- cgit v0.10.2-6-g49f6 From 830c912a0ed5d0771e9043cd51b87322230c8b6f Mon Sep 17 00:00:00 2001 From: Stefan Beller Date: Wed, 18 Jan 2017 19:18:54 -0800 Subject: documentation: retire unfinished documentation When looking for documentation for a specific function, you may be tempted to run git -C Documentation grep index_name_pos only to find the file technical/api-in-core-index.txt, which doesn't help for understanding the given function. It would be better to not find these functions in the documentation, such that people directly dive into the code instead. In the previous patches we have documented * index_name_pos() * remove_index_entry_at() * add_[file_]to_index() in cache.h We already have documentation for: * add_index_entry() * read_index() Which leaves us with a TODO for: * cache -> the_index macros * refresh_index() * discard_index() * ie_match_stat() and ie_modified(); how they are different and when to use which. * write_index() that was renamed to write_locked_index * cache_tree_invalidate_path() * cache_tree_update() Signed-off-by: Stefan Beller Signed-off-by: Junio C Hamano diff --git a/Documentation/technical/api-in-core-index.txt b/Documentation/technical/api-in-core-index.txt deleted file mode 100644 index adbdbf5..0000000 --- a/Documentation/technical/api-in-core-index.txt +++ /dev/null @@ -1,21 +0,0 @@ -in-core index API -================= - -Talk about and , things like: - -* cache -> the_index macros -* read_index() -* write_index() -* ie_match_stat() and ie_modified(); how they are different and when to - use which. -* index_name_pos() -* remove_index_entry_at() -* remove_file_from_index() -* add_file_to_index() -* add_index_entry() -* refresh_index() -* discard_index() -* cache_tree_invalidate_path() -* cache_tree_update() - -(JC, Linus) -- cgit v0.10.2-6-g49f6