{"thread":{"id":"63368","subject":"[PATCH] tree-walk.h: fix incorrect API comment","startedAt":"2025-04-29T15:45:07Z","lastAt":"2025-05-02T19:19:15Z","messageCount":3,"participants":["Elijah Newren via GitGitGadget","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"516960","messageId":"pull.1912.git.1745941503913.gitgitgadget@gmail.com","threadId":"63368","inReplyTo":null,"subject":"[PATCH] tree-walk.h: fix incorrect API comment","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-04-29T15:45:03Z","receivedAt":"2025-04-29T15:45:07Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nWhen commit 50ddb089ff68 (tree-walk.c: remove the_repo from\nget_tree_entry(), 2019-06-27) added an extra parameter to\nget_tree_entry(), it did not fix the ordering comment about the meaning\nof the parameters. Rather than just changing \"third\"->\"fourth\" and\n\"fourth\"->\"fifth\", give the paramemters meaningful names (or actually,\njust take the existing names from the get_tree_entry() definition in the\ntree-walk.c file) and strike the comment.\n\nSigned-off-by: Elijah Newren \n---\n tree-walk.h: fix incorrect API comment\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1912%2Fnewren%2Ffix-tree-walk-api-comment-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1912/newren/fix-tree-walk-api-comment-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1912\n\n tree-walk.h | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/tree-walk.h b/tree-walk.h\nindex aaea689f9ae..226b535f085 100644\n--- a/tree-walk.h\n+++ b/tree-walk.h\n@@ -177,10 +177,11 @@ struct traverse_info {\n \n /**\n * Find an entry in a tree given a pathname and the sha1 of a tree to\n- * search. Returns 0 if the entry is found and -1 otherwise. The third\n- * and fourth parameters are set to the entry's sha1 and mode respectively.\n+ * search. Returns 0 if the entry is found and -1 otherwise.\n */\n-int get_tree_entry(struct repository *, const struct object_id *, const char *, struct object_id *, unsigned short *);\n+int get_tree_entry(struct repository *repo, const struct object_id *tree_oid,\n+\t\t const char *name, struct object_id *oid,\n+\t\t unsigned short *mode);\n \n /**\n * Generate the full pathname of a tree entry based from the root of the\n\nbase-commit: f65182a99e545d2f2bc22e6c1c2da192133b16a3\n-- \ngitgitgadget\n"},{"id":"516968","messageId":"xmqqr01a6gwu.fsf@gitster.g","threadId":"63368","inReplyTo":"pull.1912.git.1745941503913.gitgitgadget@gmail.com","subject":"Re: [PATCH] tree-walk.h: fix incorrect API comment","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-04-29T17:01:21Z","receivedAt":"2025-04-29T17:01:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Elijah Newren via GitGitGadget\" writes:\n\n> From: Elijah Newren \n>\n> When commit 50ddb089ff68 (tree-walk.c: remove the_repo from\n> get_tree_entry(), 2019-06-27) added an extra parameter to\n> get_tree_entry(), it did not fix the ordering comment about the meaning\n> of the parameters. Rather than just changing \"third\"->\"fourth\" and\n> \"fourth\"->\"fifth\", give the paramemters meaningful names (or actually,\n> just take the existing names from the get_tree_entry() definition in the\n> tree-walk.c file) and strike the comment.\n\nPlease drop \"and strike the comment\" part. The \"oid\" and \"mode\"\nbeing out-parameters is significant for callers.\n\n> /**\n> * Find an entry in a tree given a pathname and the sha1 of a tree to\n> - * search. Returns 0 if the entry is found and -1 otherwise. The third\n> - * and fourth parameters are set to the entry's sha1 and mode respectively.\n> + * search. Returns 0 if the entry is found and -1 otherwise.\n> */\n> -int get_tree_entry(struct repository *, const struct object_id *, const char *, struct object_id *, unsigned short *);\n> +int get_tree_entry(struct repository *repo, const struct object_id *tree_oid,\n> +\t\t const char *name, struct object_id *oid,\n> +\t\t unsigned short *mode);\n> \n> /**\n> * Generate the full pathname of a tree entry based from the root of the\n>\n> base-commit: f65182a99e545d2f2bc22e6c1c2da192133b16a3\n\n\tFind an entry with the \"name\" in a tree object \"tree_oid\",\n\tand return the the object name and the mode of the found\n\tentry via the \"oid\" and the \"mode\" parameters. Return 0 if\n\tthe entry is found, and -1 otherwise.\n\nor something, perhaps.\n\nThanks.\n"},{"id":"517128","messageId":"pull.1912.v2.git.1746213551473.gitgitgadget@gmail.com","threadId":"63368","inReplyTo":"pull.1912.git.1745941503913.gitgitgadget@gmail.com","subject":"[PATCH v2] tree-walk.h: fix incorrect API comment","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-05-02T19:19:11Z","receivedAt":"2025-05-02T19:19:15Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nWhen commit 50ddb089ff68 (tree-walk.c: remove the_repo from\nget_tree_entry(), 2019-06-27) added an extra parameter to\nget_tree_entry(), it did not fix the ordering comment about the meaning\nof the parameters. Rather than just changing \"third\"->\"fourth\" and\n\"fourth\"->\"fifth\", give the paramemters meaningful names (or actually,\njust take the existing names from the get_tree_entry() definition in the\ntree-walk.c file) and while at it, tweak the rest of the description to\nincorporate the other parameter names as well.\n\nSigned-off-by: Elijah Newren \n---\n tree-walk.h: fix incorrect API comment\n \n Changes since v1:\n \n * Updated the documentation to explain that oid and mode are output\n parameters, and slightly tweaked the description further.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1912%2Fnewren%2Ffix-tree-walk-api-comment-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1912/newren/fix-tree-walk-api-comment-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1912\n\nRange-diff vs v1:\n\n 1: 6375bc7d351 ! 1: a47aceb6394 tree-walk.h: fix incorrect API comment\n @@ Commit message\n of the parameters. Rather than just changing \"third\"->\"fourth\" and\n \"fourth\"->\"fifth\", give the paramemters meaningful names (or actually,\n just take the existing names from the get_tree_entry() definition in the\n - tree-walk.c file) and strike the comment.\n + tree-walk.c file) and while at it, tweak the rest of the description to\n + incorporate the other parameter names as well.\n \n Signed-off-by: Elijah Newren \n \n ## tree-walk.h ##\n @@ tree-walk.h: struct traverse_info {\n + };\n \n /**\n - * Find an entry in a tree given a pathname and the sha1 of a tree to\n +- * Find an entry in a tree given a pathname and the sha1 of a tree to\n - * search. Returns 0 if the entry is found and -1 otherwise. The third\n - * and fourth parameters are set to the entry's sha1 and mode respectively.\n -+ * search. Returns 0 if the entry is found and -1 otherwise.\n - */\n +- */\n -int get_tree_entry(struct repository *, const struct object_id *, const char *, struct object_id *, unsigned short *);\n ++ * Walk trees starting with \"tree_oid\" to find the entry for \"name\", and\n ++ * return the the object name and the mode of the found entry via the\n ++ * \"oid\" and \"mode\" parameters. Return 0 if the entry is found, and -1\n ++ * otherwise.\n ++ */\n +int get_tree_entry(struct repository *repo, const struct object_id *tree_oid,\n +\t\t const char *name, struct object_id *oid,\n +\t\t unsigned short *mode);\n\n\n tree-walk.h | 13 ++++++++-----\n 1 file changed, 8 insertions(+), 5 deletions(-)\n\ndiff --git a/tree-walk.h b/tree-walk.h\nindex aaea689f9ae..29a55328bd9 100644\n--- a/tree-walk.h\n+++ b/tree-walk.h\n@@ -176,11 +176,14 @@ struct traverse_info {\n };\n \n /**\n- * Find an entry in a tree given a pathname and the sha1 of a tree to\n- * search. Returns 0 if the entry is found and -1 otherwise. The third\n- * and fourth parameters are set to the entry's sha1 and mode respectively.\n- */\n-int get_tree_entry(struct repository *, const struct object_id *, const char *, struct object_id *, unsigned short *);\n+ * Walk trees starting with \"tree_oid\" to find the entry for \"name\", and\n+ * return the the object name and the mode of the found entry via the\n+ * \"oid\" and \"mode\" parameters. Return 0 if the entry is found, and -1\n+ * otherwise.\n+ */\n+int get_tree_entry(struct repository *repo, const struct object_id *tree_oid,\n+\t\t const char *name, struct object_id *oid,\n+\t\t unsigned short *mode);\n \n /**\n * Generate the full pathname of a tree entry based from the root of the\n\nbase-commit: f65182a99e545d2f2bc22e6c1c2da192133b16a3\n-- \ngitgitgadget\n"}]}