{"thread":{"id":"44902","subject":"[PATCH 0/4] start documenting core functions","startedAt":"2017-01-17T23:35:17Z","lastAt":"2017-01-19T20:22:03Z","messageCount":25,"participants":["Stefan Beller","Junio C Hamano","Brandon Williams"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"309576","messageId":"20170117233503.27137-1-sbeller@google.com","threadId":"44902","inReplyTo":null,"subject":"[PATCH 0/4] start documenting core functions","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-17T23:34:59Z","receivedAt":"2017-01-17T23:35:17Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"The two single patches[1] are turned into a series here.\n\n[1] https://public-inbox.org/git/20170117200147.25425-1-sbeller@google.com/\n\nThanks,\nStefan\n\nStefan Beller (4):\n document index_name_pos\n remove_index_entry_at: move documentation to cache.h\n document add_[file_]to_index\n documentation: retire unfinished documentation\n\n Documentation/technical/api-in-core-index.txt | 21 ----------------\n cache.h | 35 +++++++++++++++++++++++----\n read-cache.c | 1 -\n 3 files changed, 30 insertions(+), 27 deletions(-)\n delete mode 100644 Documentation/technical/api-in-core-index.txt\n\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309577","messageId":"20170117233503.27137-3-sbeller@google.com","threadId":"44902","inReplyTo":"20170117233503.27137-1-sbeller@google.com","subject":"[PATCH 2/4] remove_index_entry_at: move documentation to cache.h","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-17T23:35:01Z","receivedAt":"2017-01-17T23:35:20Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Signed-off-by: Stefan Beller \n---\n cache.h | 3 +++\n read-cache.c | 1 -\n 2 files changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/cache.h b/cache.h\nindex 270a0d0ea7..26632065a5 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -599,7 +599,10 @@ extern int index_name_pos(const struct index_state *, const char *name, int name\n #define ADD_CACHE_KEEP_CACHE_TREE 32\t/* Do not invalidate cache-tree */\n extern int add_index_entry(struct index_state *, struct cache_entry *ce, int option);\n extern void rename_index_entry_at(struct index_state *, int pos, const char *new_name);\n+\n+/* Remove entry, return 1 if there are more entries after pos. */\n extern int remove_index_entry_at(struct index_state *, int pos);\n+\n extern void remove_marked_cache_entries(struct index_state *istate);\n extern int remove_file_from_index(struct index_state *, const char *path);\n #define ADD_CACHE_VERBOSE 1\ndiff --git a/read-cache.c b/read-cache.c\nindex 2eca639cce..63a414cdb5 100644\n--- a/read-cache.c\n+++ b/read-cache.c\n@@ -503,7 +503,6 @@ int index_name_pos(const struct index_state *istate, const char *name, int namel\n \treturn index_name_stage_pos(istate, name, namelen, 0);\n }\n \n-/* Remove entry, return true if there are more entries to go.. */\n int remove_index_entry_at(struct index_state *istate, int pos)\n {\n \tstruct cache_entry *ce = istate->cache[pos];\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309578","messageId":"20170117233503.27137-2-sbeller@google.com","threadId":"44902","inReplyTo":"20170117233503.27137-1-sbeller@google.com","subject":"[PATCH 1/4] document index_name_pos","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-17T23:35:00Z","receivedAt":"2017-01-17T23:35:22Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Signed-off-by: Stefan Beller \n---\n cache.h | 15 +++++++++++++++\n 1 file changed, 15 insertions(+)\n\ndiff --git a/cache.h b/cache.h\nindex 1b67f078dd..270a0d0ea7 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -575,7 +575,22 @@ extern int verify_path(const char *path);\n extern int index_dir_exists(struct index_state *istate, const char *name, int namelen);\n extern void adjust_dirname_case(struct index_state *istate, char *name);\n extern struct cache_entry *index_file_exists(struct index_state *istate, const char *name, int namelen, int igncase);\n+\n+/*\n+ * Searches for an entry defined by name and namelen in the given index.\n+ * If the return value is positive (including 0) it is the position of an\n+ * exact match. If the return value is negative, the negated value minus 1 is the\n+ * position where the entry would be inserted.\n+ * Example: In the current index we have the files b,d,e:\n+ * index_name_pos(&index, \"a\", 1) -> -1\n+ * index_name_pos(&index, \"b\", 1) -> 0\n+ * index_name_pos(&index, \"c\", 1) -> -2\n+ * index_name_pos(&index, \"d\", 1) -> 1\n+ * index_name_pos(&index, \"e\", 1) -> 2\n+ * index_name_pos(&index, \"f\", 1) -> -3\n+ */\n extern int index_name_pos(const struct index_state *, const char *name, int namelen);\n+\n #define ADD_CACHE_OK_TO_ADD 1\t\t/* Ok to add */\n #define ADD_CACHE_OK_TO_REPLACE 2\t/* Ok to replace file/directory */\n #define ADD_CACHE_SKIP_DFCHECK 4\t/* Ok to skip DF conflict checks */\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309579","messageId":"20170117233503.27137-4-sbeller@google.com","threadId":"44902","inReplyTo":"20170117233503.27137-1-sbeller@google.com","subject":"[PATCH 3/4] document add_[file_]to_index","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-17T23:35:02Z","receivedAt":"2017-01-17T23:35:25Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Signed-off-by: Stefan Beller \n---\n cache.h | 17 ++++++++++++-----\n 1 file changed, 12 insertions(+), 5 deletions(-)\n\ndiff --git a/cache.h b/cache.h\nindex 26632065a5..acc639d6e0 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -605,13 +605,20 @@ extern int remove_index_entry_at(struct index_state *, int pos);\n \n extern void remove_marked_cache_entries(struct index_state *istate);\n extern int remove_file_from_index(struct index_state *, const char *path);\n-#define ADD_CACHE_VERBOSE 1\n-#define ADD_CACHE_PRETEND 2\n-#define ADD_CACHE_IGNORE_ERRORS\t4\n-#define ADD_CACHE_IGNORE_REMOVAL 8\n-#define ADD_CACHE_INTENT 16\n+\n+#define ADD_CACHE_VERBOSE 1\t\t/* verbose */\n+#define ADD_CACHE_PRETEND 2 \t\t/* dry run */\n+#define ADD_CACHE_IGNORE_ERRORS 4\t/* ignore errors */\n+#define ADD_CACHE_IGNORE_REMOVAL 8\t/* do not remove files from index */\n+#define ADD_CACHE_INTENT 16\t\t/* intend to add later; stage empty file */\n+/*\n+ * Adds the given path the index, respecting the repsitory configuration, e.g.\n+ * in case insensitive file systems, the path is normalized.\n+ */\n extern int add_to_index(struct index_state *, const char *path, struct stat *, int flags);\n+/* stat the file then call add_to_index */\n extern int add_file_to_index(struct index_state *, const char *path, int flags);\n+\n extern struct cache_entry *make_cache_entry(unsigned int mode, const unsigned char *sha1, const char *path, int stage, unsigned int refresh_options);\n extern int chmod_index_entry(struct index_state *, struct cache_entry *ce, char flip);\n extern int ce_same_name(const struct cache_entry *a, const struct cache_entry *b);\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309607","messageId":"20170117233503.27137-5-sbeller@google.com","threadId":"44902","inReplyTo":"20170117233503.27137-1-sbeller@google.com","subject":"[PATCH 4/4] documentation: retire unfinished documentation","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-17T23:35:03Z","receivedAt":"2017-01-18T00:31:33Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"When looking for documentation for a specific function, you may be tempted\nto run\n\n git -C Documentation grep index_name_pos\n\nonly to find the file technical/api-in-core-index.txt, which doesn't\nhelp for understanding the given function. It would be better to not find\nthese functions in the documentation, such that people directly dive into\nthe code instead.\n\nIn the previous patches we have documented\n* index_name_pos()\n* remove_index_entry_at()\n* add_[file_]to_index()\nin cache.h\n\nWe already have documentation for:\n* add_index_entry()\n* read_index()\n\nWhich leaves us with a TODO for:\n* cache -> the_index macros\n* refresh_index()\n* discard_index()\n* ie_match_stat() and ie_modified(); how they are different and when to\n use which.\n* write_index() that was renamed to write_locked_index\n* cache_tree_invalidate_path()\n* cache_tree_update()\n\nSigned-off-by: Stefan Beller \n---\n Documentation/technical/api-in-core-index.txt | 21 ---------------------\n 1 file changed, 21 deletions(-)\n delete mode 100644 Documentation/technical/api-in-core-index.txt\n\ndiff --git a/Documentation/technical/api-in-core-index.txt b/Documentation/technical/api-in-core-index.txt\ndeleted file mode 100644\nindex adbdbf5d75..0000000000\n--- a/Documentation/technical/api-in-core-index.txt\n+++ /dev/null\n@@ -1,21 +0,0 @@\n-in-core index API\n-=================\n-\n-Talk about and , things like:\n-\n-* cache -> the_index macros\n-* read_index()\n-* write_index()\n-* ie_match_stat() and ie_modified(); how they are different and when to\n- use which.\n-* index_name_pos()\n-* remove_index_entry_at()\n-* remove_file_from_index()\n-* add_file_to_index()\n-* add_index_entry()\n-* refresh_index()\n-* discard_index()\n-* cache_tree_invalidate_path()\n-* cache_tree_update()\n-\n-(JC, Linus)\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309669","messageId":"xmqqk29s3wg0.fsf@gitster.mtv.corp.google.com","threadId":"44902","inReplyTo":"20170117233503.27137-2-sbeller@google.com","subject":"Re: [PATCH 1/4] document index_name_pos","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-18T21:11:27Z","receivedAt":"2017-01-18T21:11:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> Signed-off-by: Stefan Beller \n> ---\n> cache.h | 15 +++++++++++++++\n> 1 file changed, 15 insertions(+)\n>\n> diff --git a/cache.h b/cache.h\n> index 1b67f078dd..270a0d0ea7 100644\n> --- a/cache.h\n> +++ b/cache.h\n> @@ -575,7 +575,22 @@ extern int verify_path(const char *path);\n> extern int index_dir_exists(struct index_state *istate, const char *name, int namelen);\n> extern void adjust_dirname_case(struct index_state *istate, char *name);\n> extern struct cache_entry *index_file_exists(struct index_state *istate, const char *name, int namelen, int igncase);\n> +\n> +/*\n> + * Searches for an entry defined by name and namelen in the given index.\n> + * If the return value is positive (including 0) it is the position of an\n> + * exact match. If the return value is negative, the negated value minus 1 is the\n> + * position where the entry would be inserted.\n> + * Example: In the current index we have the files b,d,e:\n> + * index_name_pos(&index, \"a\", 1) -> -1\n> + * index_name_pos(&index, \"b\", 1) -> 0\n> + * index_name_pos(&index, \"c\", 1) -> -2\n> + * index_name_pos(&index, \"d\", 1) -> 1\n> + * index_name_pos(&index, \"e\", 1) -> 2\n\nThe above may not be wrong per-se, but it misses one important case.\nA conflicted entry in the index with the same name is considered to\nsort after the name this asks. If there are stage #1 and stage #3\nentries for path \"g\" in addition to the above, i.e.\n\n\t[0] [1] [2] [3] [4]\n\tb#0 d#0 e#0 g#1 g#3\n\nthen \n\n\tindex_name_pos(&index, \"g\", 1) -> -3 - 1 = -4\n index_name_pos(&index, \"h\", 1) -> -5 - 1 = -6\n\n> + * index_name_pos(&index, \"f\", 1) -> -3\n> + */\n\nShouldn't this be -4? We originally have [0], [1], and [2] in the\nindex, and \"f\" needs to go to [3], so -3 - 1 = -4, no?\n\n> extern int index_name_pos(const struct index_state *, const char *name, int namelen);\n> +\n> #define ADD_CACHE_OK_TO_ADD 1\t\t/* Ok to add */\n> #define ADD_CACHE_OK_TO_REPLACE 2\t/* Ok to replace file/directory */\n> #define ADD_CACHE_SKIP_DFCHECK 4\t/* Ok to skip DF conflict checks */\n"},{"id":"309672","messageId":"xmqqfukg3w7t.fsf@gitster.mtv.corp.google.com","threadId":"44902","inReplyTo":"20170117233503.27137-3-sbeller@google.com","subject":"Re: [PATCH 2/4] remove_index_entry_at: move documentation to cache.h","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-18T21:16:22Z","receivedAt":"2017-01-18T21:16:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> Signed-off-by: Stefan Beller \n> ---\n> cache.h | 3 +++\n> read-cache.c | 1 -\n> 2 files changed, 3 insertions(+), 1 deletion(-)\n>\n> diff --git a/cache.h b/cache.h\n> index 270a0d0ea7..26632065a5 100644\n> --- a/cache.h\n> +++ b/cache.h\n> @@ -599,7 +599,10 @@ extern int index_name_pos(const struct index_state *, const char *name, int name\n> #define ADD_CACHE_KEEP_CACHE_TREE 32\t/* Do not invalidate cache-tree */\n> extern int add_index_entry(struct index_state *, struct cache_entry *ce, int option);\n> extern void rename_index_entry_at(struct index_state *, int pos, const char *new_name);\n> +\n> +/* Remove entry, return 1 if there are more entries after pos. */\n> extern int remove_index_entry_at(struct index_state *, int pos);\n\nWhat is the reason why this now promise to return 1, as opposed to\nthe original that were allowed to return anything that is \"true\"?\nIs it because you are adding other return values that mean different\nthings? \n\nIf that is the case it may be fine (it depends on what these other\nvalues mean and what use case it supports), but please do that in a\nseparate patch.\n\n> +\n> extern void remove_marked_cache_entries(struct index_state *istate);\n> extern int remove_file_from_index(struct index_state *, const char *path);\n> #define ADD_CACHE_VERBOSE 1\n> diff --git a/read-cache.c b/read-cache.c\n> index 2eca639cce..63a414cdb5 100644\n> --- a/read-cache.c\n> +++ b/read-cache.c\n> @@ -503,7 +503,6 @@ int index_name_pos(const struct index_state *istate, const char *name, int namel\n> \treturn index_name_stage_pos(istate, name, namelen, 0);\n> }\n> \n> -/* Remove entry, return true if there are more entries to go.. */\n> int remove_index_entry_at(struct index_state *istate, int pos)\n> {\n> \tstruct cache_entry *ce = istate->cache[pos];\n"},{"id":"309675","messageId":"xmqqbmv43vx9.fsf@gitster.mtv.corp.google.com","threadId":"44902","inReplyTo":"20170117233503.27137-4-sbeller@google.com","subject":"Re: [PATCH 3/4] document add_[file_]to_index","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-18T21:22:42Z","receivedAt":"2017-01-18T21:23:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> Signed-off-by: Stefan Beller \n> ---\n> cache.h | 17 ++++++++++++-----\n> 1 file changed, 12 insertions(+), 5 deletions(-)\n>\n> diff --git a/cache.h b/cache.h\n> index 26632065a5..acc639d6e0 100644\n> --- a/cache.h\n> +++ b/cache.h\n> @@ -605,13 +605,20 @@ extern int remove_index_entry_at(struct index_state *, int pos);\n> \n> extern void remove_marked_cache_entries(struct index_state *istate);\n> extern int remove_file_from_index(struct index_state *, const char *path);\n> -#define ADD_CACHE_VERBOSE 1\n> -#define ADD_CACHE_PRETEND 2\n> -#define ADD_CACHE_IGNORE_ERRORS\t4\n> -#define ADD_CACHE_IGNORE_REMOVAL 8\n> -#define ADD_CACHE_INTENT 16\n> +\n> +#define ADD_CACHE_VERBOSE 1\t\t/* verbose */\n> +#define ADD_CACHE_PRETEND 2 \t\t/* dry run */\n> +#define ADD_CACHE_IGNORE_ERRORS 4\t/* ignore errors */\n> +#define ADD_CACHE_IGNORE_REMOVAL 8\t/* do not remove files from index */\n> +#define ADD_CACHE_INTENT 16\t\t/* intend to add later; stage empty file */\n\nThese repeat pretty much the same thing, which is an indication that\nthe macro names are chosen well not to require extraneous comments\nlike these, no?\n\n> +/*\n> + * Adds the given path the index, respecting the repsitory configuration, e.g.\n> + * in case insensitive file systems, the path is normalized.\n> + */\n> extern int add_to_index(struct index_state *, const char *path, struct stat *, int flags);\n\ns/repsitory/repository/;\n\n> +/* stat the file then call add_to_index */\n> extern int add_file_to_index(struct index_state *, const char *path, int flags);\n> +\n\nAs you do not say \"use the provided stat info to mark the cache\nentry up-to-date\" in the add_to_index(), I am not sure if mentioning\n\"stat the file then\" has much value. Besides, you are supposed to\nlstat(2) the file, not \"stat\", no?\n\nI'd cover these two under the same heading and comment if I were\ndoing this.\n\n\tThese two are used to add the contents of the file at path\n\tto the index, marking the working tree up-to-date by storing\n\tthe cached stat info in the resulting cache entry. A caller\n\tthat has already run lstat(2) on the path can call\n\tadd_to_index(), and all others can call add_file_to_index();\n\tthe latter will do necessary lstat(2) internally before\n\tcalling the former.\n\nor something along that line.\n\n> extern struct cache_entry *make_cache_entry(unsigned int mode, const unsigned char *sha1, const char *path, int stage, unsigned int refresh_options);\n> extern int chmod_index_entry(struct index_state *, struct cache_entry *ce, char flip);\n> extern int ce_same_name(const struct cache_entry *a, const struct cache_entry *b);\n"},{"id":"309676","messageId":"xmqq7f5s3vw8.fsf@gitster.mtv.corp.google.com","threadId":"44902","inReplyTo":"20170117233503.27137-5-sbeller@google.com","subject":"Re: [PATCH 4/4] documentation: retire unfinished documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-18T21:23:19Z","receivedAt":"2017-01-18T21:23:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> When looking for documentation for a specific function, you may be tempted\n> to run\n>\n> git -C Documentation grep index_name_pos\n>\n> only to find the file technical/api-in-core-index.txt, which doesn't\n> help for understanding the given function. It would be better to not find\n> these functions in the documentation, such that people directly dive into\n> the code instead.\n>\n> In the previous patches we have documented\n> * index_name_pos()\n> * remove_index_entry_at()\n> * add_[file_]to_index()\n> in cache.h\n>\n> We already have documentation for:\n> * add_index_entry()\n> * read_index()\n>\n> Which leaves us with a TODO for:\n> * cache -> the_index macros\n> * refresh_index()\n> * discard_index()\n> * ie_match_stat() and ie_modified(); how they are different and when to\n> use which.\n> * write_index() that was renamed to write_locked_index\n> * cache_tree_invalidate_path()\n> * cache_tree_update()\n\nThanks.\n"},{"id":"309683","messageId":"CAGZ79kbOEk9o=CsHcF876D+u1J+vYa64aEYWs_NdLSJmy-7TOQ@mail.gmail.com","threadId":"44902","inReplyTo":"xmqqk29s3wg0.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 1/4] document index_name_pos","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-18T22:02:15Z","receivedAt":"2017-01-18T22:02:28Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Wed, Jan 18, 2017 at 1:11 PM, Junio C Hamano wrote:\n> Stefan Beller writes:\n>\n>> Signed-off-by: Stefan Beller \n>> ---\n>> cache.h | 15 +++++++++++++++\n>> 1 file changed, 15 insertions(+)\n>>\n>> diff --git a/cache.h b/cache.h\n>> index 1b67f078dd..270a0d0ea7 100644\n>> --- a/cache.h\n>> +++ b/cache.h\n>> @@ -575,7 +575,22 @@ extern int verify_path(const char *path);\n>> extern int index_dir_exists(struct index_state *istate, const char *name, int namelen);\n>> extern void adjust_dirname_case(struct index_state *istate, char *name);\n>> extern struct cache_entry *index_file_exists(struct index_state *istate, const char *name, int namelen, int igncase);\n>> +\n>> +/*\n>> + * Searches for an entry defined by name and namelen in the given index.\n>> + * If the return value is positive (including 0) it is the position of an\n>> + * exact match. If the return value is negative, the negated value minus 1 is the\n>> + * position where the entry would be inserted.\n>> + * Example: In the current index we have the files b,d,e:\n>> + * index_name_pos(&index, \"a\", 1) -> -1\n>> + * index_name_pos(&index, \"b\", 1) -> 0\n>> + * index_name_pos(&index, \"c\", 1) -> -2\n>> + * index_name_pos(&index, \"d\", 1) -> 1\n>> + * index_name_pos(&index, \"e\", 1) -> 2\n>\n> The above may not be wrong per-se, but it misses one important case.\n> A conflicted entry in the index with the same name is considered to\n> sort after the name this asks. If there are stage #1 and stage #3\n> entries for path \"g\" in addition to the above, i.e.\n>\n> [0] [1] [2] [3] [4]\n> b#0 d#0 e#0 g#1 g#3\n>\n> then\n>\n> index_name_pos(&index, \"g\", 1) -> -3 - 1 = -4\n> index_name_pos(&index, \"h\", 1) -> -5 - 1 = -6\n>\n>> + * index_name_pos(&index, \"f\", 1) -> -3\n>> + */\n\nOh, I see. With this property in mind, we know that\nwhen using index_name_pos for sorting, the stages for a\ngiven path are ordered correctly (in ascending order,\n0 comes before 1, which comes before 3).\n\n>\n> Shouldn't this be -4? We originally have [0], [1], and [2] in the\n> index, and \"f\" needs to go to [3], so -3 - 1 = -4, no?\n\nyes, it should be -4.\n"},{"id":"309684","messageId":"CAGZ79kYoZOWDHewA4f9VjVkEZBXWaG5Uq8nU=M30mE535zVa2Q@mail.gmail.com","threadId":"44902","inReplyTo":"xmqqfukg3w7t.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 2/4] remove_index_entry_at: move documentation to cache.h","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-18T22:06:44Z","receivedAt":"2017-01-18T22:07:54Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Wed, Jan 18, 2017 at 1:16 PM, Junio C Hamano wrote:\n> Stefan Beller writes:\n>\n>> Signed-off-by: Stefan Beller \n>> ---\n>> cache.h | 3 +++\n>> read-cache.c | 1 -\n>> 2 files changed, 3 insertions(+), 1 deletion(-)\n>>\n>> diff --git a/cache.h b/cache.h\n>> index 270a0d0ea7..26632065a5 100644\n>> --- a/cache.h\n>> +++ b/cache.h\n>> @@ -599,7 +599,10 @@ extern int index_name_pos(const struct index_state *, const char *name, int name\n>> #define ADD_CACHE_KEEP_CACHE_TREE 32 /* Do not invalidate cache-tree */\n>> extern int add_index_entry(struct index_state *, struct cache_entry *ce, int option);\n>> extern void rename_index_entry_at(struct index_state *, int pos, const char *new_name);\n>> +\n>> +/* Remove entry, return 1 if there are more entries after pos. */\n>> extern int remove_index_entry_at(struct index_state *, int pos);\n>\n> What is the reason why this now promise to return 1, as opposed to\n> the original that were allowed to return anything that is \"true\"?\n> Is it because you are adding other return values that mean different\n> things?\n>\n> If that is the case it may be fine (it depends on what these other\n> values mean and what use case it supports), but please do that in a\n> separate patch.\n>\n\nActually my line of thinking was to improve the correctness by being more\nspecific.\n\nIn a reroll I move the comment verbatim.\n"},{"id":"309685","messageId":"CAGZ79kZ_j8YbLTtAH=3u8vZ5y+uJQ=cYJ_VbdT8_Mvhk=FMLoQ@mail.gmail.com","threadId":"44902","inReplyTo":"xmqqbmv43vx9.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 3/4] document add_[file_]to_index","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-18T22:09:13Z","receivedAt":"2017-01-18T22:09:44Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Wed, Jan 18, 2017 at 1:22 PM, Junio C Hamano wrote:\n> Stefan Beller writes:\n>\n>> Signed-off-by: Stefan Beller \n>> ---\n>> cache.h | 17 ++++++++++++-----\n>> 1 file changed, 12 insertions(+), 5 deletions(-)\n>>\n>> diff --git a/cache.h b/cache.h\n>> index 26632065a5..acc639d6e0 100644\n>> --- a/cache.h\n>> +++ b/cache.h\n>> @@ -605,13 +605,20 @@ extern int remove_index_entry_at(struct index_state *, int pos);\n>>\n>> extern void remove_marked_cache_entries(struct index_state *istate);\n>> extern int remove_file_from_index(struct index_state *, const char *path);\n>> -#define ADD_CACHE_VERBOSE 1\n>> -#define ADD_CACHE_PRETEND 2\n>> -#define ADD_CACHE_IGNORE_ERRORS 4\n>> -#define ADD_CACHE_IGNORE_REMOVAL 8\n>> -#define ADD_CACHE_INTENT 16\n>> +\n>> +#define ADD_CACHE_VERBOSE 1 /* verbose */\n>> +#define ADD_CACHE_PRETEND 2 /* dry run */\n>> +#define ADD_CACHE_IGNORE_ERRORS 4 /* ignore errors */\n>> +#define ADD_CACHE_IGNORE_REMOVAL 8 /* do not remove files from index */\n>> +#define ADD_CACHE_INTENT 16 /* intend to add later; stage empty file */\n>\n> These repeat pretty much the same thing, which is an indication that\n> the macro names are chosen well not to require extraneous comments\n> like these, no?\n\nWell I got confused for pretend and intent, so I researched them;\nI did not want to comment only half the constants.\n\n\n>\n>> +/*\n>> + * Adds the given path the index, respecting the repsitory configuration, e.g.\n>> + * in case insensitive file systems, the path is normalized.\n>> + */\n>> extern int add_to_index(struct index_state *, const char *path, struct stat *, int flags);\n>\n> s/repsitory/repository/;\n>\n>> +/* stat the file then call add_to_index */\n>> extern int add_file_to_index(struct index_state *, const char *path, int flags);\n>> +\n>\n> As you do not say \"use the provided stat info to mark the cache\n> entry up-to-date\" in the add_to_index(), I am not sure if mentioning\n> \"stat the file then\" has much value. Besides, you are supposed to\n> lstat(2) the file, not \"stat\", no?\n>\n> I'd cover these two under the same heading and comment if I were\n> doing this.\n>\n> These two are used to add the contents of the file at path\n> to the index, marking the working tree up-to-date by storing\n> the cached stat info in the resulting cache entry. A caller\n> that has already run lstat(2) on the path can call\n> add_to_index(), and all others can call add_file_to_index();\n> the latter will do necessary lstat(2) internally before\n> calling the former.\n>\n> or something along that line.\n\nThat sounds better than what I had.\n\nThanks,\nStefan\n\n>\n>> extern struct cache_entry *make_cache_entry(unsigned int mode, const unsigned char *sha1, const char *path, int stage, unsigned int refresh_options);\n>> extern int chmod_index_entry(struct index_state *, struct cache_entry *ce, char flip);\n>> extern int ce_same_name(const struct cache_entry *a, const struct cache_entry *b);\n"},{"id":"309697","messageId":"20170118232145.31606-3-sbeller@google.com","threadId":"44902","inReplyTo":"20170118232145.31606-1-sbeller@google.com","subject":"[PATCHv2 2/4] cache.h: document remove_index_entry_at","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-18T23:21:43Z","receivedAt":"2017-01-18T23:30:23Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Do this by moving the existing documentation from\nread-cache.c to cache.h.\n\nSigned-off-by: Stefan Beller \n---\n cache.h | 3 +++\n read-cache.c | 1 -\n 2 files changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/cache.h b/cache.h\nindex 3dbba69aec..87eccdb211 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -603,7 +603,10 @@ extern int index_name_pos(const struct index_state *, const char *name, int name\n #define ADD_CACHE_KEEP_CACHE_TREE 32\t/* Do not invalidate cache-tree */\n extern int add_index_entry(struct index_state *, struct cache_entry *ce, int option);\n extern void rename_index_entry_at(struct index_state *, int pos, const char *new_name);\n+\n+/* Remove entry, return true if there are more entries to go. */\n extern int remove_index_entry_at(struct index_state *, int pos);\n+\n extern void remove_marked_cache_entries(struct index_state *istate);\n extern int remove_file_from_index(struct index_state *, const char *path);\n #define ADD_CACHE_VERBOSE 1\ndiff --git a/read-cache.c b/read-cache.c\nindex 2eca639cce..63a414cdb5 100644\n--- a/read-cache.c\n+++ b/read-cache.c\n@@ -503,7 +503,6 @@ int index_name_pos(const struct index_state *istate, const char *name, int namel\n \treturn index_name_stage_pos(istate, name, namelen, 0);\n }\n \n-/* Remove entry, return true if there are more entries to go.. */\n int remove_index_entry_at(struct index_state *istate, int pos)\n {\n \tstruct cache_entry *ce = istate->cache[pos];\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309698","messageId":"20170118232145.31606-1-sbeller@google.com","threadId":"44902","inReplyTo":"20170117233503.27137-1-sbeller@google.com","subject":"[PATCHv2 0/4] start documenting core functions","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-18T23:21:41Z","receivedAt":"2017-01-18T23:30:42Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"v2:\nincluded all suggestions from Junio\n\nv1:\nThe two single patches[1] are turned into a series here.\n\n[1] https://public-inbox.org/git/20170117200147.25425-1-sbeller@google.com/\n\nThanks,\nStefan\n\nStefan Beller (4):\n cache.h: document index_name_pos\n cache.h: document remove_index_entry_at\n cache.h: document add_[file_]to_index\n documentation: retire unfinished documentation\n\n Documentation/technical/api-in-core-index.txt | 21 -------------\n cache.h | 43 +++++++++++++++++++++++----\n read-cache.c | 1 -\n 3 files changed, 38 insertions(+), 27 deletions(-)\n delete mode 100644 Documentation/technical/api-in-core-index.txt\n\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309699","messageId":"20170118232145.31606-4-sbeller@google.com","threadId":"44902","inReplyTo":"20170118232145.31606-1-sbeller@google.com","subject":"[PATCHv2 3/4] cache.h: document add_[file_]to_index","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-18T23:21:44Z","receivedAt":"2017-01-18T23:30:51Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Signed-off-by: Stefan Beller \n---\n cache.h | 21 ++++++++++++++++-----\n 1 file changed, 16 insertions(+), 5 deletions(-)\n\ndiff --git a/cache.h b/cache.h\nindex 87eccdb211..03c46b9b99 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -609,13 +609,24 @@ extern int remove_index_entry_at(struct index_state *, int pos);\n \n extern void remove_marked_cache_entries(struct index_state *istate);\n extern int remove_file_from_index(struct index_state *, const char *path);\n-#define ADD_CACHE_VERBOSE 1\n-#define ADD_CACHE_PRETEND 2\n-#define ADD_CACHE_IGNORE_ERRORS\t4\n-#define ADD_CACHE_IGNORE_REMOVAL 8\n-#define ADD_CACHE_INTENT 16\n+\n+#define ADD_CACHE_VERBOSE 1\t\t/* verbose */\n+#define ADD_CACHE_PRETEND 2 \t\t/* dry run */\n+#define ADD_CACHE_IGNORE_ERRORS 4\t/* ignore errors */\n+#define ADD_CACHE_IGNORE_REMOVAL 8\t/* do not remove files from index */\n+#define ADD_CACHE_INTENT 16\t\t/* intend to add later; stage empty file */\n+/*\n+ * These two are used to add the contents of the file at path\n+ * to the index, marking the working tree up-to-date by storing\n+ * the cached stat info in the resulting cache entry. A caller\n+ * that has already run lstat(2) on the path can call\n+ * add_to_index(), and all others can call add_file_to_index();\n+ * the latter will do necessary lstat(2) internally before\n+ * calling the former.\n+ */\n extern int add_to_index(struct index_state *, const char *path, struct stat *, int flags);\n extern int add_file_to_index(struct index_state *, const char *path, int flags);\n+\n extern struct cache_entry *make_cache_entry(unsigned int mode, const unsigned char *sha1, const char *path, int stage, unsigned int refresh_options);\n extern int chmod_index_entry(struct index_state *, struct cache_entry *ce, char flip);\n extern int ce_same_name(const struct cache_entry *a, const struct cache_entry *b);\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309700","messageId":"20170118232145.31606-2-sbeller@google.com","threadId":"44902","inReplyTo":"20170118232145.31606-1-sbeller@google.com","subject":"[PATCHv2 1/4] cache.h: document index_name_pos","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-18T23:21:42Z","receivedAt":"2017-01-18T23:31:22Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Signed-off-by: Stefan Beller \n---\n cache.h | 19 +++++++++++++++++++\n 1 file changed, 19 insertions(+)\n\ndiff --git a/cache.h b/cache.h\nindex 1b67f078dd..3dbba69aec 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -575,7 +575,26 @@ extern int verify_path(const char *path);\n extern int index_dir_exists(struct index_state *istate, const char *name, int namelen);\n extern void adjust_dirname_case(struct index_state *istate, char *name);\n extern struct cache_entry *index_file_exists(struct index_state *istate, const char *name, int namelen, int igncase);\n+\n+/*\n+ * Searches for an entry defined by name and namelen in the given index.\n+ * If the return value is positive (including 0) it is the position of an\n+ * exact match. If the return value is negative, the negated value minus 1\n+ * is the position where the entry would be inserted.\n+ * Example: The current index consists of these files and its stages:\n+ *\n+ * b#0, d#0, f#1, f#3\n+ *\n+ * index_name_pos(&index, \"a\", 1) -> -1\n+ * index_name_pos(&index, \"b\", 1) -> 0\n+ * index_name_pos(&index, \"c\", 1) -> -2\n+ * index_name_pos(&index, \"d\", 1) -> 1\n+ * index_name_pos(&index, \"e\", 1) -> -3\n+ * index_name_pos(&index, \"f\", 1) -> 2\n+ * index_name_pos(&index, \"g\", 1) -> -5\n+ */\n extern int index_name_pos(const struct index_state *, const char *name, int namelen);\n+\n #define ADD_CACHE_OK_TO_ADD 1\t\t/* Ok to add */\n #define ADD_CACHE_OK_TO_REPLACE 2\t/* Ok to replace file/directory */\n #define ADD_CACHE_SKIP_DFCHECK 4\t/* Ok to skip DF conflict checks */\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309701","messageId":"20170118232145.31606-5-sbeller@google.com","threadId":"44902","inReplyTo":"20170118232145.31606-1-sbeller@google.com","subject":"[PATCHv2 4/4] documentation: retire unfinished documentation","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-18T23:21:45Z","receivedAt":"2017-01-18T23:31:39Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"When looking for documentation for a specific function, you may be tempted\nto run\n\n git -C Documentation grep index_name_pos\n\nonly to find the file technical/api-in-core-index.txt, which doesn't\nhelp for understanding the given function. It would be better to not find\nthese functions in the documentation, such that people directly dive into\nthe code instead.\n\nIn the previous patches we have documented\n* index_name_pos()\n* remove_index_entry_at()\n* add_[file_]to_index()\nin cache.h\n\nWe already have documentation for:\n* add_index_entry()\n* read_index()\n\nWhich leaves us with a TODO for:\n* cache -> the_index macros\n* refresh_index()\n* discard_index()\n* ie_match_stat() and ie_modified(); how they are different and when to\n use which.\n* write_index() that was renamed to write_locked_index\n* cache_tree_invalidate_path()\n* cache_tree_update()\n\nSigned-off-by: Stefan Beller \n---\n Documentation/technical/api-in-core-index.txt | 21 ---------------------\n 1 file changed, 21 deletions(-)\n delete mode 100644 Documentation/technical/api-in-core-index.txt\n\ndiff --git a/Documentation/technical/api-in-core-index.txt b/Documentation/technical/api-in-core-index.txt\ndeleted file mode 100644\nindex adbdbf5d75..0000000000\n--- a/Documentation/technical/api-in-core-index.txt\n+++ /dev/null\n@@ -1,21 +0,0 @@\n-in-core index API\n-=================\n-\n-Talk about and , things like:\n-\n-* cache -> the_index macros\n-* read_index()\n-* write_index()\n-* ie_match_stat() and ie_modified(); how they are different and when to\n- use which.\n-* index_name_pos()\n-* remove_index_entry_at()\n-* remove_file_from_index()\n-* add_file_to_index()\n-* add_index_entry()\n-* refresh_index()\n-* discard_index()\n-* cache_tree_invalidate_path()\n-* cache_tree_update()\n-\n-(JC, Linus)\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309703","messageId":"20170119000037.GF10641@google.com","threadId":"44902","inReplyTo":"20170118232145.31606-4-sbeller@google.com","subject":"Re: [PATCHv2 3/4] cache.h: document add_[file_]to_index","fromName":"Brandon Williams","fromEmail":"bmwill@google.com","sentAt":"2017-01-19T00:00:37Z","receivedAt":"2017-01-19T00:01:05Z","isPatch":false,"sender":{"key":"bwilliams.eng@gmail.com","avatar":null},"body":"On 01/18, Stefan Beller wrote:\n> Signed-off-by: Stefan Beller \n> ---\n> cache.h | 21 ++++++++++++++++-----\n> 1 file changed, 16 insertions(+), 5 deletions(-)\n> \n> diff --git a/cache.h b/cache.h\n> index 87eccdb211..03c46b9b99 100644\n> --- a/cache.h\n> +++ b/cache.h\n> @@ -609,13 +609,24 @@ extern int remove_index_entry_at(struct index_state *, int pos);\n> \n> extern void remove_marked_cache_entries(struct index_state *istate);\n> extern int remove_file_from_index(struct index_state *, const char *path);\n> -#define ADD_CACHE_VERBOSE 1\n> -#define ADD_CACHE_PRETEND 2\n> -#define ADD_CACHE_IGNORE_ERRORS\t4\n> -#define ADD_CACHE_IGNORE_REMOVAL 8\n> -#define ADD_CACHE_INTENT 16\n> +\n> +#define ADD_CACHE_VERBOSE 1\t\t/* verbose */\n> +#define ADD_CACHE_PRETEND 2 \t\t/* dry run */\n> +#define ADD_CACHE_IGNORE_ERRORS 4\t/* ignore errors */\n> +#define ADD_CACHE_IGNORE_REMOVAL 8\t/* do not remove files from index */\n> +#define ADD_CACHE_INTENT 16\t\t/* intend to add later; stage empty file */\n\nI usually prefer having defines like these use shift operators to set\nthe desired bit '(1<<2)' instead of '4', etc. Is there a preference for\ngit as a whole? I know this is just a documentation change so maybe\nthis isn't even the place to discuss this.\n\n-- \nBrandon Williams\n"},{"id":"309704","messageId":"CAGZ79kY_nbHuThnSDAyLhEwnRWYEQBmMLS4RtGPKOzYt_9Bgsg@mail.gmail.com","threadId":"44902","inReplyTo":"20170119000037.GF10641@google.com","subject":"Re: [PATCHv2 3/4] cache.h: document add_[file_]to_index","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-19T00:08:22Z","receivedAt":"2017-01-19T00:16:26Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Wed, Jan 18, 2017 at 4:00 PM, Brandon Williams wrote:\n> On 01/18, Stefan Beller wrote:\n>> Signed-off-by: Stefan Beller \n>> ---\n>> cache.h | 21 ++++++++++++++++-----\n>> 1 file changed, 16 insertions(+), 5 deletions(-)\n>>\n>> diff --git a/cache.h b/cache.h\n>> index 87eccdb211..03c46b9b99 100644\n>> --- a/cache.h\n>> +++ b/cache.h\n>> @@ -609,13 +609,24 @@ extern int remove_index_entry_at(struct index_state *, int pos);\n>>\n>> extern void remove_marked_cache_entries(struct index_state *istate);\n>> extern int remove_file_from_index(struct index_state *, const char *path);\n>> -#define ADD_CACHE_VERBOSE 1\n>> -#define ADD_CACHE_PRETEND 2\n>> -#define ADD_CACHE_IGNORE_ERRORS 4\n>> -#define ADD_CACHE_IGNORE_REMOVAL 8\n>> -#define ADD_CACHE_INTENT 16\n>> +\n>> +#define ADD_CACHE_VERBOSE 1 /* verbose */\n>> +#define ADD_CACHE_PRETEND 2 /* dry run */\n>> +#define ADD_CACHE_IGNORE_ERRORS 4 /* ignore errors */\n>> +#define ADD_CACHE_IGNORE_REMOVAL 8 /* do not remove files from index */\n>> +#define ADD_CACHE_INTENT 16 /* intend to add later; stage empty file */\n>\n> I usually prefer having defines like these use shift operators to set\n> the desired bit '(1<<2)' instead of '4', etc. Is there a preference for\n> git as a whole? I know this is just a documentation change so maybe\n> this isn't even the place to discuss this.\n\neh, and I forgot to remove the comments that Junio thought of as redundant.\nI agree that (1<\n> --\n> Brandon Williams\n"},{"id":"309707","messageId":"20170119031854.4570-1-sbeller@google.com","threadId":"44902","inReplyTo":"20170118232145.31606-2-sbeller@google.com","subject":"[PATCHv3 0/4] start documenting core functions","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-19T03:18:50Z","receivedAt":"2017-01-19T03:19:06Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"v3:\n* dropped commets on constants as they were not helpful\n* fixed one result in the example for index_name_pos(&index, \"f\", 1) (which\n is -3 now)\n\nv2:\nincluded all suggestions from Junio\n\nv1:\nThe two single patches[1] are turned into a series here.\n\n[1] https://public-inbox.org/git/20170117200147.25425-1-sbeller@google.com/\n\nThanks,\nStefan\n\nStefan Beller (4):\n cache.h: document index_name_pos\n cache.h: document remove_index_entry_at\n cache.h: document add_[file_]to_index\n documentation: retire unfinished documentation\n\n Documentation/technical/api-in-core-index.txt | 21 -------------\n cache.h | 43 +++++++++++++++++++++++----\n read-cache.c | 1 -\n 3 files changed, 38 insertions(+), 27 deletions(-)\n delete mode 100644 Documentation/technical/api-in-core-index.txt\n\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309708","messageId":"20170119031854.4570-2-sbeller@google.com","threadId":"44902","inReplyTo":"20170119031854.4570-1-sbeller@google.com","subject":"[PATCHv3 1/4] cache.h: document index_name_pos","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-19T03:18:51Z","receivedAt":"2017-01-19T03:19:10Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Signed-off-by: Stefan Beller \n---\n cache.h | 19 +++++++++++++++++++\n 1 file changed, 19 insertions(+)\n\ndiff --git a/cache.h b/cache.h\nindex 1b67f078dd..1469ddeafe 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -575,7 +575,26 @@ extern int verify_path(const char *path);\n extern int index_dir_exists(struct index_state *istate, const char *name, int namelen);\n extern void adjust_dirname_case(struct index_state *istate, char *name);\n extern struct cache_entry *index_file_exists(struct index_state *istate, const char *name, int namelen, int igncase);\n+\n+/*\n+ * Searches for an entry defined by name and namelen in the given index.\n+ * If the return value is positive (including 0) it is the position of an\n+ * exact match. If the return value is negative, the negated value minus 1\n+ * is the position where the entry would be inserted.\n+ * Example: The current index consists of these files and its stages:\n+ *\n+ * b#0, d#0, f#1, f#3\n+ *\n+ * index_name_pos(&index, \"a\", 1) -> -1\n+ * index_name_pos(&index, \"b\", 1) -> 0\n+ * index_name_pos(&index, \"c\", 1) -> -2\n+ * index_name_pos(&index, \"d\", 1) -> 1\n+ * index_name_pos(&index, \"e\", 1) -> -3\n+ * index_name_pos(&index, \"f\", 1) -> -3\n+ * index_name_pos(&index, \"g\", 1) -> -5\n+ */\n extern int index_name_pos(const struct index_state *, const char *name, int namelen);\n+\n #define ADD_CACHE_OK_TO_ADD 1\t\t/* Ok to add */\n #define ADD_CACHE_OK_TO_REPLACE 2\t/* Ok to replace file/directory */\n #define ADD_CACHE_SKIP_DFCHECK 4\t/* Ok to skip DF conflict checks */\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309709","messageId":"20170119031854.4570-3-sbeller@google.com","threadId":"44902","inReplyTo":"20170119031854.4570-1-sbeller@google.com","subject":"[PATCHv3 2/4] cache.h: document remove_index_entry_at","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-19T03:18:52Z","receivedAt":"2017-01-19T03:19:13Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Do this by moving the existing documentation from\nread-cache.c to cache.h.\n\nSigned-off-by: Stefan Beller \n---\n cache.h | 3 +++\n read-cache.c | 1 -\n 2 files changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/cache.h b/cache.h\nindex 1469ddeafe..929474d7a9 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -603,7 +603,10 @@ extern int index_name_pos(const struct index_state *, const char *name, int name\n #define ADD_CACHE_KEEP_CACHE_TREE 32\t/* Do not invalidate cache-tree */\n extern int add_index_entry(struct index_state *, struct cache_entry *ce, int option);\n extern void rename_index_entry_at(struct index_state *, int pos, const char *new_name);\n+\n+/* Remove entry, return true if there are more entries to go. */\n extern int remove_index_entry_at(struct index_state *, int pos);\n+\n extern void remove_marked_cache_entries(struct index_state *istate);\n extern int remove_file_from_index(struct index_state *, const char *path);\n #define ADD_CACHE_VERBOSE 1\ndiff --git a/read-cache.c b/read-cache.c\nindex 2eca639cce..63a414cdb5 100644\n--- a/read-cache.c\n+++ b/read-cache.c\n@@ -503,7 +503,6 @@ int index_name_pos(const struct index_state *istate, const char *name, int namel\n \treturn index_name_stage_pos(istate, name, namelen, 0);\n }\n \n-/* Remove entry, return true if there are more entries to go.. */\n int remove_index_entry_at(struct index_state *istate, int pos)\n {\n \tstruct cache_entry *ce = istate->cache[pos];\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309710","messageId":"20170119031854.4570-5-sbeller@google.com","threadId":"44902","inReplyTo":"20170119031854.4570-1-sbeller@google.com","subject":"[PATCHv3 4/4] documentation: retire unfinished documentation","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-19T03:18:54Z","receivedAt":"2017-01-19T03:19:14Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"When looking for documentation for a specific function, you may be tempted\nto run\n\n git -C Documentation grep index_name_pos\n\nonly to find the file technical/api-in-core-index.txt, which doesn't\nhelp for understanding the given function. It would be better to not find\nthese functions in the documentation, such that people directly dive into\nthe code instead.\n\nIn the previous patches we have documented\n* index_name_pos()\n* remove_index_entry_at()\n* add_[file_]to_index()\nin cache.h\n\nWe already have documentation for:\n* add_index_entry()\n* read_index()\n\nWhich leaves us with a TODO for:\n* cache -> the_index macros\n* refresh_index()\n* discard_index()\n* ie_match_stat() and ie_modified(); how they are different and when to\n use which.\n* write_index() that was renamed to write_locked_index\n* cache_tree_invalidate_path()\n* cache_tree_update()\n\nSigned-off-by: Stefan Beller \n---\n Documentation/technical/api-in-core-index.txt | 21 ---------------------\n 1 file changed, 21 deletions(-)\n delete mode 100644 Documentation/technical/api-in-core-index.txt\n\ndiff --git a/Documentation/technical/api-in-core-index.txt b/Documentation/technical/api-in-core-index.txt\ndeleted file mode 100644\nindex adbdbf5d75..0000000000\n--- a/Documentation/technical/api-in-core-index.txt\n+++ /dev/null\n@@ -1,21 +0,0 @@\n-in-core index API\n-=================\n-\n-Talk about and , things like:\n-\n-* cache -> the_index macros\n-* read_index()\n-* write_index()\n-* ie_match_stat() and ie_modified(); how they are different and when to\n- use which.\n-* index_name_pos()\n-* remove_index_entry_at()\n-* remove_file_from_index()\n-* add_file_to_index()\n-* add_index_entry()\n-* refresh_index()\n-* discard_index()\n-* cache_tree_invalidate_path()\n-* cache_tree_update()\n-\n-(JC, Linus)\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309711","messageId":"20170119031854.4570-4-sbeller@google.com","threadId":"44902","inReplyTo":"20170119031854.4570-1-sbeller@google.com","subject":"[PATCHv3 3/4] cache.h: document add_[file_]to_index","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-01-19T03:18:53Z","receivedAt":"2017-01-19T03:19:18Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Helped-by: Junio C Hamano \nSigned-off-by: Stefan Beller \n---\n cache.h | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\ndiff --git a/cache.h b/cache.h\nindex 929474d7a9..12394eb541 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -614,8 +614,18 @@ extern int remove_file_from_index(struct index_state *, const char *path);\n #define ADD_CACHE_IGNORE_ERRORS\t4\n #define ADD_CACHE_IGNORE_REMOVAL 8\n #define ADD_CACHE_INTENT 16\n+/*\n+ * These two are used to add the contents of the file at path\n+ * to the index, marking the working tree up-to-date by storing\n+ * the cached stat info in the resulting cache entry. A caller\n+ * that has already run lstat(2) on the path can call\n+ * add_to_index(), and all others can call add_file_to_index();\n+ * the latter will do necessary lstat(2) internally before\n+ * calling the former.\n+ */\n extern int add_to_index(struct index_state *, const char *path, struct stat *, int flags);\n extern int add_file_to_index(struct index_state *, const char *path, int flags);\n+\n extern struct cache_entry *make_cache_entry(unsigned int mode, const unsigned char *sha1, const char *path, int stage, unsigned int refresh_options);\n extern int chmod_index_entry(struct index_state *, struct cache_entry *ce, char flip);\n extern int ce_same_name(const struct cache_entry *a, const struct cache_entry *b);\n-- \n2.11.0.299.g762782ba8a\n\n"},{"id":"309767","messageId":"xmqqziimztw0.fsf@gitster.mtv.corp.google.com","threadId":"44902","inReplyTo":"20170119031854.4570-2-sbeller@google.com","subject":"Re: [PATCHv3 1/4] cache.h: document index_name_pos","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-19T20:17:51Z","receivedAt":"2017-01-19T20:22:03Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> Signed-off-by: Stefan Beller \n> ---\n> cache.h | 19 +++++++++++++++++++\n> 1 file changed, 19 insertions(+)\n>\n> diff --git a/cache.h b/cache.h\n> index 1b67f078dd..1469ddeafe 100644\n> --- a/cache.h\n> +++ b/cache.h\n> @@ -575,7 +575,26 @@ extern int verify_path(const char *path);\n> extern int index_dir_exists(struct index_state *istate, const char *name, int namelen);\n> extern void adjust_dirname_case(struct index_state *istate, char *name);\n> extern struct cache_entry *index_file_exists(struct index_state *istate, const char *name, int namelen, int igncase);\n> +\n> +/*\n> + * Searches for an entry defined by name and namelen in the given index.\n> + * If the return value is positive (including 0) it is the position of an\n> + * exact match. If the return value is negative, the negated value minus 1\n> + * is the position where the entry would be inserted.\n\nSo if the return value is -3, you negate it to get 3 and then\nsubtract 1 to get 2. The function is telling you that \"e\" will\nsit at active_cache[2] in the following example.\n\nWhich is correct.\n\n> + * Example: The current index consists of these files and its stages:\n> + *\n> + * b#0, d#0, f#1, f#3\n> + *\n> + * index_name_pos(&index, \"a\", 1) -> -1\n> + * index_name_pos(&index, \"b\", 1) -> 0\n> + * index_name_pos(&index, \"c\", 1) -> -2\n> + * index_name_pos(&index, \"d\", 1) -> 1\n> + * index_name_pos(&index, \"e\", 1) -> -3\n> + * index_name_pos(&index, \"f\", 1) -> -3\n> + * index_name_pos(&index, \"g\", 1) -> -5\n> + */\n\nThis time the counting seems correct.\n\nThanks.\n"}]}