From 12733e9dd39411be4cd6a9a437faa7d86df159c2 Mon Sep 17 00:00:00 2001 From: Stefan Beller Date: Wed, 18 Jan 2017 19:18:51 -0800 Subject: [PATCH 1/4] cache.h: document index_name_pos Signed-off-by: Stefan Beller Signed-off-by: Junio C Hamano --- cache.h | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/cache.h b/cache.h index a50a61a197..83c8c260ce 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 */ From 3bd72adff1f4435898508f5c74227aaa2561c182 Mon Sep 17 00:00:00 2001 From: Stefan Beller Date: Wed, 18 Jan 2017 19:18:52 -0800 Subject: [PATCH 2/4] 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 --- cache.h | 3 +++ read-cache.c | 1 - 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/cache.h b/cache.h index 83c8c260ce..c8b881a908 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 db5d910642..585ff02dc3 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]; From 20cf41d02158cbb838faec70ad1d989172fc592f Mon Sep 17 00:00:00 2001 From: Stefan Beller Date: Wed, 18 Jan 2017 19:18:53 -0800 Subject: [PATCH 3/4] cache.h: document add_[file_]to_index Helped-by: Junio C Hamano Signed-off-by: Stefan Beller Signed-off-by: Junio C Hamano --- cache.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/cache.h b/cache.h index c8b881a908..b36b4fa31b 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); From 830c912a0ed5d0771e9043cd51b87322230c8b6f Mon Sep 17 00:00:00 2001 From: Stefan Beller Date: Wed, 18 Jan 2017 19:18:54 -0800 Subject: [PATCH 4/4] 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 --- Documentation/technical/api-in-core-index.txt | 21 ------------------- 1 file changed, 21 deletions(-) delete mode 100644 Documentation/technical/api-in-core-index.txt diff --git a/Documentation/technical/api-in-core-index.txt b/Documentation/technical/api-in-core-index.txt deleted file mode 100644 index adbdbf5d75..0000000000 --- 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)