{"thread":{"id":"45676","subject":"[PATCH] refs.h: rename submodule arguments to submodule_path","startedAt":"2017-04-12T20:00:59Z","lastAt":"2017-04-21T09:40:06Z","messageCount":6,"participants":["Stefan Beller","Junio C Hamano","Michael Haggerty","Duy Nguyen"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"316700","messageId":"20170412200037.18752-1-sbeller@google.com","threadId":"45676","inReplyTo":null,"subject":"[PATCH] refs.h: rename submodule arguments to submodule_path","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-04-12T20:00:37Z","receivedAt":"2017-04-12T20:00:59Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"In submodule land we carefully need to distinguish between the path of a\nsubmodule and its name.\n\nThe path of a submodule is the path that is recorded in the working tree\nof the superproject and describes where the submodule is bound to the\nsuperprojects tree.\n\nThe name as introduced in 941987a554 (git-submodule: give submodules\nproper names, 2007-06-11) exists to track submodules across renames of\nsubmodules. It is also used for the internal path in .git/modules/\nto store the git directory of the submodule inside the superproject.\n\nWhen looking up ref functions to use, I was confused which of the two\nsubmodule properties are meant in the argument of the ref functions.\nThe context in which the functions were used however revealed it is the\npath of the submodules.\n\nRename the arguments to clearly describe what is expected as an input\nargument.\n\nSigned-off-by: Stefan Beller \n---\n refs.h | 14 +++++++-------\n 1 file changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/refs.h b/refs.h\nindex 3df0d45ebb..451f92958a 100644\n--- a/refs.h\n+++ b/refs.h\n@@ -86,7 +86,7 @@ int peel_ref(const char *refname, unsigned char *sha1);\n * successful, return 0 and set sha1 to the name of the object;\n * otherwise, return a non-zero value.\n */\n-int resolve_gitlink_ref(const char *submodule, const char *refname,\n+int resolve_gitlink_ref(const char *submodule_path, const char *refname,\n \t\t\tunsigned char *sha1);\n \n /*\n@@ -204,16 +204,16 @@ int for_each_glob_ref(each_ref_fn fn, const char *pattern, void *cb_data);\n int for_each_glob_ref_in(each_ref_fn fn, const char *pattern,\n \t\t\t const char *prefix, void *cb_data);\n \n-int head_ref_submodule(const char *submodule, each_ref_fn fn, void *cb_data);\n-int for_each_ref_submodule(const char *submodule,\n+int head_ref_submodule(const char *submodule_path, each_ref_fn fn, void *cb_data);\n+int for_each_ref_submodule(const char *submodule_path,\n \t\t\t each_ref_fn fn, void *cb_data);\n-int for_each_ref_in_submodule(const char *submodule, const char *prefix,\n+int for_each_ref_in_submodule(const char *submodule_path, const char *prefix,\n \t\teach_ref_fn fn, void *cb_data);\n-int for_each_tag_ref_submodule(const char *submodule,\n+int for_each_tag_ref_submodule(const char *submodule_path,\n \t\t\t each_ref_fn fn, void *cb_data);\n-int for_each_branch_ref_submodule(const char *submodule,\n+int for_each_branch_ref_submodule(const char *submodule_path,\n \t\t\t\t each_ref_fn fn, void *cb_data);\n-int for_each_remote_ref_submodule(const char *submodule,\n+int for_each_remote_ref_submodule(const char *submodule_path,\n \t\t\t\t each_ref_fn fn, void *cb_data);\n \n int head_ref_namespaced(each_ref_fn fn, void *cb_data);\n-- \n2.12.2.603.g7b28dc31ba\n\n"},{"id":"317362","messageId":"CAGZ79kYTqh=Qa+Pt1+MojrcYFr05HQgbPRcc=DvjCkUWsjP5Uw@mail.gmail.com","threadId":"45676","inReplyTo":"20170412200037.18752-1-sbeller@google.com","subject":"Re: [PATCH] refs.h: rename submodule arguments to submodule_path","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-04-20T18:21:04Z","receivedAt":"2017-04-20T18:21:11Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"+ Junio\n\nOn Wed, Apr 12, 2017 at 1:00 PM, Stefan Beller wrote:\n> In submodule land we carefully need to distinguish between the path of a\n> submodule and its name.\n>\n> The path of a submodule is the path that is recorded in the working tree\n> of the superproject and describes where the submodule is bound to the\n> superprojects tree.\n>\n> The name as introduced in 941987a554 (git-submodule: give submodules\n> proper names, 2007-06-11) exists to track submodules across renames of\n> submodules. It is also used for the internal path in .git/modules/\n> to store the git directory of the submodule inside the superproject.\n>\n> When looking up ref functions to use, I was confused which of the two\n> submodule properties are meant in the argument of the ref functions.\n> The context in which the functions were used however revealed it is the\n> path of the submodules.\n>\n> Rename the arguments to clearly describe what is expected as an input\n> argument.\n>\n> Signed-off-by: Stefan Beller \n> ---\n> refs.h | 14 +++++++-------\n> 1 file changed, 7 insertions(+), 7 deletions(-)\n>\n> diff --git a/refs.h b/refs.h\n> index 3df0d45ebb..451f92958a 100644\n> --- a/refs.h\n> +++ b/refs.h\n> @@ -86,7 +86,7 @@ int peel_ref(const char *refname, unsigned char *sha1);\n> * successful, return 0 and set sha1 to the name of the object;\n> * otherwise, return a non-zero value.\n> */\n> -int resolve_gitlink_ref(const char *submodule, const char *refname,\n> +int resolve_gitlink_ref(const char *submodule_path, const char *refname,\n> unsigned char *sha1);\n>\n> /*\n> @@ -204,16 +204,16 @@ int for_each_glob_ref(each_ref_fn fn, const char *pattern, void *cb_data);\n> int for_each_glob_ref_in(each_ref_fn fn, const char *pattern,\n> const char *prefix, void *cb_data);\n>\n> -int head_ref_submodule(const char *submodule, each_ref_fn fn, void *cb_data);\n> -int for_each_ref_submodule(const char *submodule,\n> +int head_ref_submodule(const char *submodule_path, each_ref_fn fn, void *cb_data);\n> +int for_each_ref_submodule(const char *submodule_path,\n> each_ref_fn fn, void *cb_data);\n> -int for_each_ref_in_submodule(const char *submodule, const char *prefix,\n> +int for_each_ref_in_submodule(const char *submodule_path, const char *prefix,\n> each_ref_fn fn, void *cb_data);\n> -int for_each_tag_ref_submodule(const char *submodule,\n> +int for_each_tag_ref_submodule(const char *submodule_path,\n> each_ref_fn fn, void *cb_data);\n> -int for_each_branch_ref_submodule(const char *submodule,\n> +int for_each_branch_ref_submodule(const char *submodule_path,\n> each_ref_fn fn, void *cb_data);\n> -int for_each_remote_ref_submodule(const char *submodule,\n> +int for_each_remote_ref_submodule(const char *submodule_path,\n> each_ref_fn fn, void *cb_data);\n>\n> int head_ref_namespaced(each_ref_fn fn, void *cb_data);\n> --\n> 2.12.2.603.g7b28dc31ba\n>\n"},{"id":"317443","messageId":"xmqqy3uu7ee3.fsf@gitster.mtv.corp.google.com","threadId":"45676","inReplyTo":"CAGZ79kYTqh=Qa+Pt1+MojrcYFr05HQgbPRcc=DvjCkUWsjP5Uw@mail.gmail.com","subject":"Re: [PATCH] refs.h: rename submodule arguments to submodule_path","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-04-21T01:12:04Z","receivedAt":"2017-04-21T01:12:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> + Junio\n\nJust like Michael, I do not have strong enough opinion for or\nagainst this patch to comment on it.\n\nI do agree with you that it would be a good longer-term direction to\nuse \"submodule\" for a \"struct submodule\" (i.e. submodule object),\nand call a string that names a submodule either \"submodule_name\" or\n\"submodule_path\" depending on how it names one, for maintainability\nof the code. \n\nHowever I am not convinced that this patch is an improvement. Even\nthough parameter names in decls only serve documentation purpose and\nit is even OK to only have type without name there, if we are going\nto _have_ names, it would make sense to match them to the parameter\nnames actually used in the implementation. \n\nUpdating these names used in refs.c would make a very noisy patch,\nof course. But I am not sure if it is a good middle ground to avoid\nthat and to update only refs.h.\n\n"},{"id":"317461","messageId":"cb1dd8b6-3357-57ff-650d-c55a7eb38d34@alum.mit.edu","threadId":"45676","inReplyTo":"xmqqy3uu7ee3.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] refs.h: rename submodule arguments to submodule_path","fromName":"Michael Haggerty","fromEmail":"mhagger@alum.mit.edu","sentAt":"2017-04-21T06:32:56Z","receivedAt":"2017-04-21T06:33:10Z","isPatch":true,"sender":{"key":"mhagger@alum.mit.edu","avatar":"https://avatars.githubusercontent.com/u/119718?v=4"},"body":"On 04/21/2017 03:12 AM, Junio C Hamano wrote:\n> Stefan Beller writes:\n> \n>> + Junio\n> \n> Just like Michael, I do not have strong enough opinion for or\n> against this patch to comment on it.\n> \n> I do agree with you that it would be a good longer-term direction to\n> use \"submodule\" for a \"struct submodule\" (i.e. submodule object),\n> and call a string that names a submodule either \"submodule_name\" or\n> \"submodule_path\" depending on how it names one, for maintainability\n> of the code. \n> \n> However I am not convinced that this patch is an improvement. Even\n> though parameter names in decls only serve documentation purpose and\n> it is even OK to only have type without name there, if we are going\n> to _have_ names, it would make sense to match them to the parameter\n> names actually used in the implementation. \n> \n> Updating these names used in refs.c would make a very noisy patch,\n> of course. But I am not sure if it is a good middle ground to avoid\n> that and to update only refs.h.\n\nOne should never infer too much from my silence. As often as not it's\nbecause I'm simply busy with other things.\n\nBut in this case Junio's right. I think it is a good idea to use\nargument names in declarations as documentation, and I also agree that\nit is a minus for the names in the declarations not to agree with the\nnames in the definition. But the code that would have to be touched\nalready has a lot of work going on in it, so conflicts would be likely.\n\nI've CCed Duy because I don't know whether he has more plans regarding\nsubmodule references. A natural followup to his recent work would be to\nadd a feature to the `submodule` module that allows a caller to look up\nthe `ref_store` object for the submodule. Then client code could use the\n`refs_for_each_ref(struct ref_store *, ...)` family of functions to\naccess such references, and we could get rid of the\n`for_each_ref_submodule()` family of functions entirely.\n\nSo perhaps the code that this patch touches won't be around long anyway.\n\nMichael\n\n"},{"id":"317463","messageId":"8b2ef70c-4064-f726-8752-5bb0a898ee7a@alum.mit.edu","threadId":"45676","inReplyTo":"cb1dd8b6-3357-57ff-650d-c55a7eb38d34@alum.mit.edu","subject":"Re: [PATCH] refs.h: rename submodule arguments to submodule_path","fromName":"Michael Haggerty","fromEmail":"mhagger@alum.mit.edu","sentAt":"2017-04-21T06:42:16Z","receivedAt":"2017-04-21T06:42:39Z","isPatch":true,"sender":{"key":"mhagger@alum.mit.edu","avatar":"https://avatars.githubusercontent.com/u/119718?v=4"},"body":"On 04/21/2017 08:32 AM, Michael Haggerty wrote:\n> [...]\n> I've CCed Duy because I don't know whether he has more plans regarding\n> submodule references [...] get rid of the\n> `for_each_ref_submodule()` family of functions entirely.\n> \n> So perhaps the code that this patch touches won't be around long anyway.\n\nOh yeah, he has done exactly that in his nd/prune-in-worktree patch\nseries. (I knew I'd seen that somewhere...)\n\nSo it seems that the argument renaming has mostly been overtaken by\nevents, though even after Duy's patch series there are a few `const char\n*submodule` arguments that could be renamed.\n\nMichael\n\n"},{"id":"317468","messageId":"CACsJy8BJ2_omtR+LyE71JSSmHf9qVanbdgembqg_HJD6qNheNA@mail.gmail.com","threadId":"45676","inReplyTo":"8b2ef70c-4064-f726-8752-5bb0a898ee7a@alum.mit.edu","subject":"Re: [PATCH] refs.h: rename submodule arguments to submodule_path","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2017-04-21T09:38:16Z","receivedAt":"2017-04-21T09:40:06Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Fri, Apr 21, 2017 at 1:42 PM, Michael Haggerty wrote:\n> On 04/21/2017 08:32 AM, Michael Haggerty wrote:\n>> [...]\n>> I've CCed Duy because I don't know whether he has more plans regarding\n>> submodule references [...] get rid of the\n>> `for_each_ref_submodule()` family of functions entirely.\n>>\n>> So perhaps the code that this patch touches won't be around long anyway.\n>\n> Oh yeah, he has done exactly that in his nd/prune-in-worktree patch\n> series. (I knew I'd seen that somewhere...)\n>\n> So it seems that the argument renaming has mostly been overtaken by\n> events, though even after Duy's patch series there are a few `const char\n> *submodule` arguments that could be renamed.\n\nYeah. After that series, the only place that takes a submodule (path)\nis get_submodule_ref_store() (other functions are just helpers).\nRenaming it to submodule_path makes perfect sense. Johannes Sixt when\nreviewing that series also noticed the \"path\" nature of this\n\"submodule\" argument and suggested converting submodule[x] == '/' to\nis_dir_sep(submodule[i]) for that reason.\n\nAt this point, I think Stefan even has the opportunity to\nreference/look up a submodule ref store by something other than a path\n (like \"struct submodule *\", or by name) if he wants to. But if you\ndo that, maybe rename the current function to\nget_submodule_ref_store_by_path() before you add a new\nget_submodule_ref_store_by_whatever().\n\nAbout \".. because I don't know whether he (Duy) has more plans\nregarding submodule references\", I plan to convert \"submodule[x] ==\n'/'\" to is_dir_sep(submodule[x]), but I think that's about it. I'm not\ninvolved much in submodule to see the direction it's heading. As far\nas refs code is concerned, a \"struct ref_store *\" is all it needs,\nregardless of how you obtain it.\n-- \nDuy\n"}]}