# [PATCH] tree-walk.h: fix incorrect API comment 3 messages from 2025-04-29 to 2025-05-02. Participants: Elijah Newren via GitGitGadget, Junio C Hamano. Thread: https://gitlist.dev/t/63368 ## Elijah Newren via GitGitGadget, 2025-04-29 15:45 Subject: [PATCH] tree-walk.h: fix incorrect API comment Message-ID: URL: https://gitlist.dev/e/pull.1912.git.1745941503913.gitgitgadget%40gmail.com ``` From: Elijah Newren When commit 50ddb089ff68 (tree-walk.c: remove the_repo from get_tree_entry(), 2019-06-27) added an extra parameter to get_tree_entry(), it did not fix the ordering comment about the meaning of the parameters. Rather than just changing "third"->"fourth" and "fourth"->"fifth", give the paramemters meaningful names (or actually, just take the existing names from the get_tree_entry() definition in the tree-walk.c file) and strike the comment. Signed-off-by: Elijah Newren --- tree-walk.h: fix incorrect API comment Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1912%2Fnewren%2Ffix-tree-walk-api-comment-v1 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1912/newren/fix-tree-walk-api-comment-v1 Pull-Request: https://github.com/gitgitgadget/git/pull/1912 tree-walk.h | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/tree-walk.h b/tree-walk.h index aaea689f9ae..226b535f085 100644 --- a/tree-walk.h +++ b/tree-walk.h @@ -177,10 +177,11 @@ struct traverse_info { /** * Find an entry in a tree given a pathname and the sha1 of a tree to - * search. Returns 0 if the entry is found and -1 otherwise. The third - * and fourth parameters are set to the entry's sha1 and mode respectively. + * search. Returns 0 if the entry is found and -1 otherwise. */ -int get_tree_entry(struct repository *, const struct object_id *, const char *, struct object_id *, unsigned short *); +int get_tree_entry(struct repository *repo, const struct object_id *tree_oid, + const char *name, struct object_id *oid, + unsigned short *mode); /** * Generate the full pathname of a tree entry based from the root of the base-commit: f65182a99e545d2f2bc22e6c1c2da192133b16a3 -- gitgitgadget ``` ## Junio C Hamano, 2025-04-29 17:01 Subject: Re: [PATCH] tree-walk.h: fix incorrect API comment Message-ID: URL: https://gitlist.dev/e/xmqqr01a6gwu.fsf%40gitster.g In-Reply-To: ``` "Elijah Newren via GitGitGadget" writes: > From: Elijah Newren > > When commit 50ddb089ff68 (tree-walk.c: remove the_repo from > get_tree_entry(), 2019-06-27) added an extra parameter to > get_tree_entry(), it did not fix the ordering comment about the meaning > of the parameters. Rather than just changing "third"->"fourth" and > "fourth"->"fifth", give the paramemters meaningful names (or actually, > just take the existing names from the get_tree_entry() definition in the > tree-walk.c file) and strike the comment. Please drop "and strike the comment" part. The "oid" and "mode" being out-parameters is significant for callers. > /** > * Find an entry in a tree given a pathname and the sha1 of a tree to > - * search. Returns 0 if the entry is found and -1 otherwise. The third > - * and fourth parameters are set to the entry's sha1 and mode respectively. > + * search. Returns 0 if the entry is found and -1 otherwise. > */ > -int get_tree_entry(struct repository *, const struct object_id *, const char *, struct object_id *, unsigned short *); > +int get_tree_entry(struct repository *repo, const struct object_id *tree_oid, > + const char *name, struct object_id *oid, > + unsigned short *mode); > > /** > * Generate the full pathname of a tree entry based from the root of the > > base-commit: f65182a99e545d2f2bc22e6c1c2da192133b16a3 Find an entry with the "name" in a tree object "tree_oid", and return the the object name and the mode of the found entry via the "oid" and the "mode" parameters. Return 0 if the entry is found, and -1 otherwise. or something, perhaps. Thanks. ``` ## Elijah Newren via GitGitGadget, 2025-05-02 19:19 Subject: [PATCH v2] tree-walk.h: fix incorrect API comment Message-ID: URL: https://gitlist.dev/e/pull.1912.v2.git.1746213551473.gitgitgadget%40gmail.com In-Reply-To: ``` From: Elijah Newren When commit 50ddb089ff68 (tree-walk.c: remove the_repo from get_tree_entry(), 2019-06-27) added an extra parameter to get_tree_entry(), it did not fix the ordering comment about the meaning of the parameters. Rather than just changing "third"->"fourth" and "fourth"->"fifth", give the paramemters meaningful names (or actually, just take the existing names from the get_tree_entry() definition in the tree-walk.c file) and while at it, tweak the rest of the description to incorporate the other parameter names as well. Signed-off-by: Elijah Newren --- tree-walk.h: fix incorrect API comment Changes since v1: * Updated the documentation to explain that oid and mode are output parameters, and slightly tweaked the description further. Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1912%2Fnewren%2Ffix-tree-walk-api-comment-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1912/newren/fix-tree-walk-api-comment-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/1912 Range-diff vs v1: 1: 6375bc7d351 ! 1: a47aceb6394 tree-walk.h: fix incorrect API comment @@ Commit message of the parameters. Rather than just changing "third"->"fourth" and "fourth"->"fifth", give the paramemters meaningful names (or actually, just take the existing names from the get_tree_entry() definition in the - tree-walk.c file) and strike the comment. + tree-walk.c file) and while at it, tweak the rest of the description to + incorporate the other parameter names as well. Signed-off-by: Elijah Newren ## tree-walk.h ## @@ tree-walk.h: struct traverse_info { + }; /** - * Find an entry in a tree given a pathname and the sha1 of a tree to +- * Find an entry in a tree given a pathname and the sha1 of a tree to - * search. Returns 0 if the entry is found and -1 otherwise. The third - * and fourth parameters are set to the entry's sha1 and mode respectively. -+ * search. Returns 0 if the entry is found and -1 otherwise. - */ +- */ -int get_tree_entry(struct repository *, const struct object_id *, const char *, struct object_id *, unsigned short *); ++ * Walk trees starting with "tree_oid" to find the entry for "name", and ++ * return the the object name and the mode of the found entry via the ++ * "oid" and "mode" parameters. Return 0 if the entry is found, and -1 ++ * otherwise. ++ */ +int get_tree_entry(struct repository *repo, const struct object_id *tree_oid, + const char *name, struct object_id *oid, + unsigned short *mode); tree-walk.h | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/tree-walk.h b/tree-walk.h index aaea689f9ae..29a55328bd9 100644 --- a/tree-walk.h +++ b/tree-walk.h @@ -176,11 +176,14 @@ struct traverse_info { }; /** - * Find an entry in a tree given a pathname and the sha1 of a tree to - * search. Returns 0 if the entry is found and -1 otherwise. The third - * and fourth parameters are set to the entry's sha1 and mode respectively. - */ -int get_tree_entry(struct repository *, const struct object_id *, const char *, struct object_id *, unsigned short *); + * Walk trees starting with "tree_oid" to find the entry for "name", and + * return the the object name and the mode of the found entry via the + * "oid" and "mode" parameters. Return 0 if the entry is found, and -1 + * otherwise. + */ +int get_tree_entry(struct repository *repo, const struct object_id *tree_oid, + const char *name, struct object_id *oid, + unsigned short *mode); /** * Generate the full pathname of a tree entry based from the root of the base-commit: f65182a99e545d2f2bc22e6c1c2da192133b16a3 -- gitgitgadget ```