{"thread":{"id":"44241","subject":"[PATCH] documentation: clarify submodule..[url, path] variables","startedAt":"2016-10-06T23:52:01Z","lastAt":"2016-10-10T19:44:45Z","messageCount":5,"participants":["Stefan Beller","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"303545","messageId":"20161006235149.10232-1-sbeller@google.com","threadId":"44241","inReplyTo":null,"subject":"[PATCH] documentation: clarify submodule..[url, path] variables","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2016-10-06T23:51:49Z","receivedAt":"2016-10-06T23:52:01Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Signed-off-by: Stefan Beller \n---\n\nThis was raised in the discussion of \nhttps://public-inbox.org/git/20161006193725.31553-1-sbeller@google.com/raw\n\nHowever this can go as a separate patch instead of adding it to the series.\n\nThanks,\nStefan\n\n Documentation/config.txt | 15 +++++++++++----\n 1 file changed, 11 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex e78293b..1f68d05 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -2812,11 +2812,18 @@ stash.showStat::\n \tSee description of 'show' command in linkgit:git-stash[1].\n \n submodule..path::\n+\tThe path within this project for a submodule. This variable is\n+\tkept in the .gitmodules file. See linkgit:git-submodule[1] and\n+\tlinkgit:gitmodules[5] for details.\n+\n submodule..url::\n-\tThe path within this project and URL for a submodule. These\n-\tvariables are initially populated by 'git submodule init'. See\n-\tlinkgit:git-submodule[1] and linkgit:gitmodules[5] for\n-\tdetails.\n+\tThe URL for a submodule. This variable is copied from the .gitmodules\n+\tfile to the git config via 'git submodule init'. The user can change\n+\tthe configured URL before obtaining the submodule via 'git submodule\n+\tupdate'. After obtaining the submodule, this variable is kept in the\n+\tconfig as a boolean flag to indicate whether the submodule is of\n+\tinterest to git commands. See linkgit:git-submodule[1] and\n+\tlinkgit:gitmodules[5] for details.\n \n submodule..update::\n \tThe default update procedure for a submodule. This variable\n-- \n2.10.1.353.g1629400\n\n"},{"id":"303772","messageId":"xmqqpon8f54i.fsf@gitster.mtv.corp.google.com","threadId":"44241","inReplyTo":"20161006235149.10232-1-sbeller@google.com","subject":"Re: [PATCH] documentation: clarify submodule..[url, path] variables","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-10T18:09:17Z","receivedAt":"2016-10-10T18:10:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n> submodule..path::\n> +\tThe path within this project for a submodule. This variable is\n> +\tkept in the .gitmodules file. See linkgit:git-submodule[1] and\n> +\tlinkgit:gitmodules[5] for details.\n\nWhat does it exactly mean to be \"kept\"?\n\nDoes it mean \"never appears in .git/config, and when it appears it\nwill not be used at all\"? If so we shouldn't even list it here.\n\nI doubt there is any reason for .path to exist in .git/config; where\neach submodule appears in the working tree is what is recorded in\nthe tree object, and the \"identity\" (i.e. that which links a\nsubmodule in a tree to one of the repositories kept in\n.git/modules/*) by reverse look-up of submodule..path from\nin-tree .gitmodules, not from configuration, and it is not something\na per-repository configuration should be able to change at the\nconceptual level.\n\n> submodule..url::\n> -\tThe path within this project and URL for a submodule. These\n> -\tvariables are initially populated by 'git submodule init'. See\n> -\tlinkgit:git-submodule[1] and linkgit:gitmodules[5] for\n> -\tdetails.\n> +\tThe URL for a submodule. This variable is copied from the .gitmodules\n> +\tfile to the git config via 'git submodule init'. The user can change\n> +\tthe configured URL before obtaining the submodule via 'git submodule\n> +\tupdate'. After obtaining the submodule, this variable is kept in the\n> +\tconfig as a boolean flag to indicate whether the submodule is of\n> +\tinterest to git commands. See linkgit:git-submodule[1] and\n> +\tlinkgit:gitmodules[5] for details.\n\nI think it is great that you are describing that this serves two\npurposes, but \"as a boolean flag\" is very misleading. It sounds as\nif at some point \"git submodule $something\" command stores\ntrue/false there.\n\n - It overrides the URL suggested by the project in .gitmodules and\n replace it with another URL viewed from the local environment\n (e.g. the project may suggest you to use http://github.com/ while\n you may have a local mirror elsewhere).\n\n - Its presence is also used as a sign that the user is interested in\n the submodule.\n"},{"id":"303781","messageId":"CAGZ79kZiKwOTiJiw4X3uLit2LrBRe_Y1oVn0-HJT-ey15D49Qw@mail.gmail.com","threadId":"44241","inReplyTo":"xmqqpon8f54i.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] documentation: clarify submodule..[url, path] variables","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2016-10-10T18:35:14Z","receivedAt":"2016-10-10T18:35:20Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Mon, Oct 10, 2016 at 11:09 AM, Junio C Hamano wrote:\n> Stefan Beller writes:\n>> submodule..path::\n>> + The path within this project for a submodule. This variable is\n>> + kept in the .gitmodules file. See linkgit:git-submodule[1] and\n>> + linkgit:gitmodules[5] for details.\n>\n> What does it exactly mean to be \"kept\"?\n>\n> Does it mean \"never appears in .git/config, and when it appears it\n> will not be used at all\"? If so we shouldn't even list it here.\n\nI meant:\nGit wont put it into .git/config on its own. If you really wanted to have\nit there, you need to do it yourself.\n\nI assumed you can overwrite the path via the config. It turns out,\nthe value from the config is ignored, so it doesn't even make sense\nto put it into the config. Only the value from the .gitmodules file counts.\n\nSo with that knowledge, I'll just remove it here, but I'll cross check if it\nis referenced else where enough.\n\n>\n> I doubt there is any reason for .path to exist in .git/config; where\n> each submodule appears in the working tree is what is recorded in\n> the tree object, and the \"identity\" (i.e. that which links a\n> submodule in a tree to one of the repositories kept in\n> .git/modules/*) by reverse look-up of submodule..path from\n> in-tree .gitmodules, not from configuration, and it is not something\n> a per-repository configuration should be able to change at the\n> conceptual level.\n\nAs said above, currently we'd only rely on the .gitmodules file.\n\nHowever I think this may conceptually the wrong thing to do.\nThe name is set in stone and ought to never be changed, unlike\nthe path. But as we only obtain this information from within the\nrepository at all times and not make a copy of it, upstream may\ngo crazy and change the names within the .gitmodules file.\n\nThen the downstream user is left with a mess and they have no\nway of fixing it except by modifying the data in the repository. So it\nmay be a sensible thing to allow the user to create their own\npath -> name mapping in the config file.\n\nWe as the Git developers may even think about whether we'd\nwant to have the path -> name lookup all the time from upstream,\nor rather on initialization want to make a copy of the path->name\nmapping. Then we can never change the name locally, but we'd\nneed to track upstream for rename detection of submodule.\n\n>\n>> submodule..url::\n>> - The path within this project and URL for a submodule. These\n>> - variables are initially populated by 'git submodule init'. See\n>> - linkgit:git-submodule[1] and linkgit:gitmodules[5] for\n>> - details.\n>> + The URL for a submodule. This variable is copied from the .gitmodules\n>> + file to the git config via 'git submodule init'. The user can change\n>> + the configured URL before obtaining the submodule via 'git submodule\n>> + update'. After obtaining the submodule, this variable is kept in the\n>> + config as a boolean flag to indicate whether the submodule is of\n>> + interest to git commands. See linkgit:git-submodule[1] and\n>> + linkgit:gitmodules[5] for details.\n>\n> I think it is great that you are describing that this serves two\n> purposes, but \"as a boolean flag\" is very misleading. It sounds as\n> if at some point \"git submodule $something\" command stores\n> true/false there.\n>\n> - It overrides the URL suggested by the project in .gitmodules and\n> replace it with another URL viewed from the local environment\n> (e.g. the project may suggest you to use http://github.com/ while\n> you may have a local mirror elsewhere).\n>\n> - Its presence is also used as a sign that the user is interested in\n> the submodule.\n\nI see, that makes it clearer, I'll reword this.\n"},{"id":"303789","messageId":"xmqqshs4dnq1.fsf@gitster.mtv.corp.google.com","threadId":"44241","inReplyTo":"CAGZ79kZiKwOTiJiw4X3uLit2LrBRe_Y1oVn0-HJT-ey15D49Qw@mail.gmail.com","subject":"Re: [PATCH] documentation: clarify submodule..[url, path] variables","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-10T19:10:30Z","receivedAt":"2016-10-10T19:10:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n>> Does it mean \"never appears in .git/config, and when it appears it\n>> will not be used at all\"? If so we shouldn't even list it here.\n>\n> I meant:\n> Git wont put it into .git/config on its own. If you really wanted to have\n> it there, you need to do it yourself.\n>\n> I assumed you can overwrite the path via the config. It turns out,\n> the value from the config is ignored, so it doesn't even make sense\n> to put it into the config. Only the value from the .gitmodules file counts.\n>\n> So with that knowledge, I'll just remove it here, but I'll cross check if it\n> is referenced else where enough.\n\nGood. I do recall we designed this part of the system in such a way\nthat .path is conceptually uncostimizable (it _is_ part of what the\ncontaining tree already records), and was wondering why it is there\nas if it can be overridden.\n"},{"id":"303793","messageId":"20161010193641.16489-1-sbeller@google.com","threadId":"44241","inReplyTo":"xmqqshs4dnq1.fsf@gitster.mtv.corp.google.com","subject":"[PATCHv2] documentation: improve submodule..{url, path} description","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2016-10-10T19:36:41Z","receivedAt":"2016-10-10T19:44:45Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Unlike the url variable a user cannot override the the path variable,\nas it is part of the content together with the gitlink at the given\npath. To avoid confusion do not mention the .path variable in the config\nsection and rely on the documentation provided in gitmodules[5].\n\nEnhance the description of submodule..url and mention its two use\ncases separately.\n\nSigned-off-by: Stefan Beller \n---\n\nI think the gitmodules[5] is enough for .path, so let's just\ndo this one instead.\n\nThanks,\nStefan\n\n\n Documentation/config.txt | 11 ++++++-----\n 1 file changed, 6 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex e78293b..fd775b4 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -2811,12 +2811,13 @@ stash.showStat::\n \toption will show diffstat of the stash. Defaults to true.\n \tSee description of 'show' command in linkgit:git-stash[1].\n \n-submodule..path::\n submodule..url::\n-\tThe path within this project and URL for a submodule. These\n-\tvariables are initially populated by 'git submodule init'. See\n-\tlinkgit:git-submodule[1] and linkgit:gitmodules[5] for\n-\tdetails.\n+\tThe URL for a submodule. This variable is copied from the .gitmodules\n+\tfile to the git config via 'git submodule init'. The user can change\n+\tthe configured URL before obtaining the submodule via 'git submodule\n+\tupdate'. After obtaining the submodule, the presence of this variable\n+\tis used as a sign whether the submodule is of interest to git commands.\n+\tSee linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\n \n submodule..update::\n \tThe default update procedure for a submodule. This variable\n-- \n2.10.1.382.ga23ca1b.dirty\n\n"}]}