{"thread":{"id":"14462","subject":"[PATCH] Documentation/git-submodule.txt: Add Description section","startedAt":"2008-07-15T10:22:07Z","lastAt":"2008-07-18T13:40:41Z","messageCount":13,"participants":["Petr Baudis","Junio C Hamano","Heikki Orsila","Kalle Olavi Niemitalo"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"83385","messageId":"20080715102119.26321.78530.stgit@localhost","threadId":"14462","inReplyTo":null,"subject":"[PATCH] Documentation/git-submodule.txt: Add Description section","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2008-07-15T10:22:07Z","receivedAt":"2008-07-15T10:22:07Z","isPatch":true,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"Figuring out how submodules work conceptually is quite a bumpy\nride for a newcomer; the user manual helps (if one knows to actually\nlook into it), but the reference documentation should provide good\nquick intro as well. This patch attempts to do that.\n\nSigned-off-by: Petr Baudis \n---\n\n Documentation/git-submodule.txt | 18 ++++++++++++++++++\n 1 files changed, 18 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 105fc2d..3413704 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -16,6 +16,24 @@ SYNOPSIS\n 'git submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...]\n \n \n+DESCRIPTION\n+-----------\n+Submodules are a special kind of tree entries which do not refer to a blob or\n+a directory, but to a particular tree in another repository (living at a given\n+URL). The tree entry describes the existence of a submodule with the given\n+name and the exact revision that should be used, while the location of the\n+repository is described in the `/.gitmodules` file. This command will manage\n+the tree entries and contents of this file for you, as well as inspecting the\n+status of your submodules and updating them.\n+\n+When adding a new submodule to the tree, the 'add' subcommand is to be used.\n+However, when pulling a tree containing submodules, these will not be checked\n+out by default; the 'init' and 'update' subcommands will maintain submodules\n+checked out and at appropriate revision in your working tree. You can inspect\n+the current status of your submodules using the 'submodule' subcommand and get\n+an overview of changes 'update' would perform using the 'summary' subcommand.\n+\n+\n COMMANDS\n --------\n add::\n"},{"id":"83392","messageId":"7vprpf44ym.fsf@gitster.siamese.dyndns.org","threadId":"14462","inReplyTo":"20080715102119.26321.78530.stgit@localhost","subject":"Re: [PATCH] Documentation/git-submodule.txt: Add Description section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-07-15T14:06:25Z","receivedAt":"2008-07-15T14:06:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Petr Baudis writes:\n\n> Figuring out how submodules work conceptually is quite a bumpy\n> ride for a newcomer; the user manual helps (if one knows to actually\n> look into it), but the reference documentation should provide good\n> quick intro as well. This patch attempts to do that.\n\nGood discussion starter, I think. There seem to be a few technical\ninaccuracies though.\n\nI'll wait until the people interested in submodules on the list form\nconsensus on the wording and contents.\n"},{"id":"83421","messageId":"20080715183705.GD4379@zakalwe.fi","threadId":"14462","inReplyTo":"20080715102119.26321.78530.stgit@localhost","subject":"Re: [PATCH] Documentation/git-submodule.txt: Add Description section","fromName":"Heikki Orsila","fromEmail":"shdl@zakalwe.fi","sentAt":"2008-07-15T18:37:05Z","receivedAt":"2008-07-15T18:37:05Z","isPatch":true,"sender":{"key":"shdl@zakalwe.fi","avatar":null},"body":"On Tue, Jul 15, 2008 at 12:22:07PM +0200, Petr Baudis wrote:\n> +Submodules are a special kind of tree entries which do not refer to a blob or\n> +a directory, but to a particular tree in another repository (living at a given\n> +URL). \n\nBetter to say what a submodule is, rather than what it isn't:\n\n\"Submodules are a special kind of tree entries which refer to a \nparticular tree in another repository ...\"\n\nAlso, I think you should make the following explicit:\n\n\"A submodule is visible as subdirectory in the working directory.\nHowever, the submodule is not part of the main repository.\nThis is a differene to \"remotes\". In remotes only the contents of \nother repositories is tracked, but their content is not visible in the\nworking directory.\"\n\n-- \nHeikki Orsila\nheikki.orsila@iki.fi\nhttp://www.iki.fi/shd\n"},{"id":"83550","messageId":"20080716184248.6524.38463.stgit@localhost","threadId":"14462","inReplyTo":"20080715183705.GD4379@zakalwe.fi","subject":"[PATCHv2] Documentation/git-submodule.txt: Add Description section","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2008-07-16T18:44:12Z","receivedAt":"2008-07-16T18:44:12Z","isPatch":false,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"Figuring out how submodules work conceptually is quite a bumpy\nride for a newcomer; the user manual helps (if one knows to actually\nlook into it), but the reference documentation should provide good\nquick intro as well. This patch attempts to do that, with suggestions\nfrom Heikki Orsila.\n\nCc: Heikki Orsila \nSigned-off-by: Petr Baudis \n---\n\nI have adjusted the description a bit; however, I believe mentioning remotes in\nthe description would only raise the danger of confusion - I emphasized the\nlevel of separation, though.\n\n Documentation/git-submodule.txt | 22 ++++++++++++++++++++++\n 1 files changed, 22 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 76702a0..87c4ece 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -16,6 +16,28 @@ SYNOPSIS\n 'git submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...]\n \n \n+DESCRIPTION\n+-----------\n+Submodules are a special kind of tree entries which refer to a particular tree\n+in another repository (living at a given URL). The tree entry describes\n+the existence of a submodule with the given name and the exact revision that\n+should be used, while the location of the repository is described in the\n+`/.gitmodules` file.\n+\n+When checked out, submodules will maintain their own independent repositories\n+within their directories; the only link between the submodule and the \"parent\n+project\" is the tree entry within the parent project mentioned above.\n+\n+This command will manage the tree entries and contents of the gitmodules file\n+for you, as well as inspecting the status of your submodules and updating them.\n+When adding a new submodule to the tree, the 'add' subcommand is to be used.\n+However, when pulling a tree containing submodules, these will not be checked\n+out by default; the 'init' and 'update' subcommands will maintain submodules\n+checked out and at appropriate revision in your working tree. You can inspect\n+the current status of your submodules using the 'submodule' subcommand and get\n+an overview of changes 'update' would perform using the 'summary' subcommand.\n+\n+\n COMMANDS\n --------\n add::\n"},{"id":"83564","messageId":"87d4ldvdwx.fsf@Astalo.kon.iki.fi","threadId":"14462","inReplyTo":"20080716184248.6524.38463.stgit@localhost","subject":"Re: [PATCHv2] Documentation/git-submodule.txt: Add Description section","fromName":"Kalle Olavi Niemitalo","fromEmail":"kon@iki.fi","sentAt":"2008-07-16T19:15:26Z","receivedAt":"2008-07-16T19:15:26Z","isPatch":false,"sender":{"key":"kon@iki.fi","avatar":null},"body":"Petr Baudis writes:\n\n> +Submodules are a special kind of tree entries which refer to a particular tree\n> +in another repository (living at a given URL). The tree entry describes\n> +the existence of a submodule with the given name and the exact revision that\n> +should be used, while the location of the repository is described in the\n> +`/.gitmodules` file.\n\nI was surprised to learn that a commit ID in a tree does not\nprevent Git from pruning the corresponding commit object if\none happens to exist in the same repository. That might be\nbest documented under \"Tree Object\" in user-manual.txt though,\nrather than in git-submodule.txt.\n"},{"id":"83568","messageId":"7vej5tr5kv.fsf@gitster.siamese.dyndns.org","threadId":"14462","inReplyTo":"20080716184248.6524.38463.stgit@localhost","subject":"Re: [PATCHv2] Documentation/git-submodule.txt: Add Description section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-07-16T19:29:03Z","receivedAt":"2008-07-16T19:29:03Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Petr Baudis writes:\n\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index 76702a0..87c4ece 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -16,6 +16,28 @@ SYNOPSIS\n> 'git submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...]\n> \n> \n> +DESCRIPTION\n> +-----------\n> +Submodules are a special kind of tree entries which refer to a particular tree\n> +in another repository (living at a given URL). ...\n\nIn the documentation, \"tree\" has a specific meaning. Perhaps \"a\nparticular tree state\" is a better wording than another alternative \"a\nparticular commit\", because you mention \"the exact revision\" in the\nfollowing sentence.\n\nI'd suggest dropping \" (living at a given URL)\" from here, though.\n\n> ... The tree entry describes\n> +the existence of a submodule with the given name and the exact revision that\n> +should be used, while the location of the repository is described in the\n> +`/.gitmodules` file.\n\nStrictly speaking, \".gitmodules\" merely gives a hint to be used by\n\"submodule init\", the canonical location from which the repository is\nexpected to be cloned. I do not think this overview needs to go into such\na detail. The description of \"init\" subcommand might need clarification,\nthough.\n\n> +When checked out, submodules will maintain their own independent repositories\n> +within their directories; the only link between the submodule and the \"parent\n> +project\" is the tree entry within the parent project mentioned above.\n> +\n> +This command will manage the tree entries and contents of the gitmodules file\n> +for you, as well as inspecting the status of your submodules and updating them.\n> +When adding a new submodule to the tree, the 'add' subcommand is to be used.\n> +However, when pulling a tree containing submodules, these will not be checked\n> +out by default; the 'init' and 'update' subcommands will maintain submodules\n> +checked out and at appropriate revision in your working tree. You can inspect\n> +the current status of your submodules using the 'submodule' subcommand and get\n> +an overview of changes 'update' would perform using the 'summary' subcommand.\n\nOtherwise this is a nice write-up. Will queue; further comments from\nother submodule users are appreciated if there are any. Thanks.\n"},{"id":"83666","messageId":"20080717104124.GE4379@zakalwe.fi","threadId":"14462","inReplyTo":"20080716184248.6524.38463.stgit@localhost","subject":"Re: [PATCHv2] Documentation/git-submodule.txt: Add Description section","fromName":"Heikki Orsila","fromEmail":"shdl@zakalwe.fi","sentAt":"2008-07-17T10:41:24Z","receivedAt":"2008-07-17T10:41:24Z","isPatch":false,"sender":{"key":"shdl@zakalwe.fi","avatar":null},"body":"On Wed, Jul 16, 2008 at 08:44:12PM +0200, Petr Baudis wrote:\n> I have adjusted the description a bit; however, I believe mentioning\n> remotes in\n> the description would only raise the danger of confusion - I emphasized the\n> level of separation, though.\n\nI think not doing a comparison actually creates confusion. My immediate \nthought about submodules was \"how does this differ from remotes? why do \nsubmodules exist rather than just remotes?\"\n\n-- \nHeikki Orsila\nheikki.orsila@iki.fi\nhttp://www.iki.fi/shd\n"},{"id":"83674","messageId":"20080717121813.GC10151@machine.or.cz","threadId":"14462","inReplyTo":"20080717104124.GE4379@zakalwe.fi","subject":"Re: [PATCHv2] Documentation/git-submodule.txt: Add Description section","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2008-07-17T12:18:13Z","receivedAt":"2008-07-17T12:18:13Z","isPatch":false,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"On Wed, Jul 16, 2008 at 12:29:03PM -0700, Junio C Hamano wrote:\n> Petr Baudis writes:\n> \n> > diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> > index 76702a0..87c4ece 100644\n> > --- a/Documentation/git-submodule.txt\n> > +++ b/Documentation/git-submodule.txt\n> > @@ -16,6 +16,28 @@ SYNOPSIS\n> > 'git submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...]\n> > \n> > \n> > +DESCRIPTION\n> > +-----------\n> > +Submodules are a special kind of tree entries which refer to a particular tree\n> > +in another repository (living at a given URL). ...\n> \n> In the documentation, \"tree\" has a specific meaning. Perhaps \"a\n> particular tree state\" is a better wording than another alternative \"a\n> particular commit\", because you mention \"the exact revision\" in the\n> following sentence.\n\nThe two sentences are now highly redundant, so...\n\n> I'd suggest dropping \" (living at a given URL)\" from here, though.\n\n...actually, in the end I have completely rewritten this yet again. The\ndescription was too low-level (and kind of in fact explained gitlinks\ninstead of submodules), while we should carefully explain the high-level\nconcept of submodules first, only then talk about tree entries.\n\n> > ... The tree entry describes\n> > +the existence of a submodule with the given name and the exact revision that\n> > +should be used, while the location of the repository is described in the\n> > +`/.gitmodules` file.\n> \n> Strictly speaking, \".gitmodules\" merely gives a hint to be used by\n> \"submodule init\", the canonical location from which the repository is\n> expected to be cloned. I do not think this overview needs to go into such\n> a detail. The description of \"init\" subcommand might need clarification,\n> though.\n\nI believe we should mention it. The users *will* see this file e.g.\nduring submodule merges, as well as in git status output when\nmanipulating submodules.\n\n\nOn Thu, Jul 17, 2008 at 01:41:24PM +0300, Heikki Orsila wrote:\n> On Wed, Jul 16, 2008 at 08:44:12PM +0200, Petr Baudis wrote:\n> > I have adjusted the description a bit; however, I believe mentioning\n> > remotes in\n> > the description would only raise the danger of confusion - I emphasized the\n> > level of separation, though.\n> \n> I think not doing a comparison actually creates confusion. My immediate \n> thought about submodules was \"how does this differ from remotes? why do \n> submodules exist rather than just remotes?\"\n\nOk, now I realize this is a good point, and it's a nice chance to give a\nplug for the subtree merge strategy as an alternative. ;-)\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nGNU, n. An animal of South Africa, which in its domesticated state\nresembles a horse, a buffalo and a stag. In its wild condition it is\nsomething like a thunderbolt, an earthquake and a cyclone. -- A. Pierce\n"},{"id":"83676","messageId":"20080717122911.32334.73465.stgit@localhost","threadId":"14462","inReplyTo":"20080717121813.GC10151@machine.or.cz","subject":"[PATCH] Documentation/git-submodule.txt: Further clarify the description","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2008-07-17T12:29:20Z","receivedAt":"2008-07-17T12:29:20Z","isPatch":true,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"This patch rewrites the general description yet again, first clarifying\nthe high-level concept, mentioning the difference to remotes and using\nthe subtree merge strategy, then getting to the details about tree\nentries and .gitmodules file.\n\nThe patch also makes few smallar grammar fixups of the rest of the\ndescription and clarifies how does 'init' relate to 'update --init'.\n\nCc: Heikki Orsila \nSigned-off-by: Petr Baudis \n---\n\n Documentation/git-submodule.txt | 39 +++++++++++++++++++++++++++------------\n 1 files changed, 27 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex bb4e6fb..01d0d91 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -18,24 +18,35 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Submodules are a special kind of tree entries which refer to a particular tree\n-state in another repository. The tree entry describes\n-the existence of a submodule with the given name and the exact revision that\n-should be used, while an entry in `.gitmodules` file gives the location of\n-the repository.\n-\n-When checked out, submodules will maintain their own independent repositories\n-within their directories; the only link between the submodule and the \"parent\n-project\" is the tree entry within the parent project mentioned above.\n+Submodules allow foreign repositories to be embedded within a dedicated\n+subdirectory of the source tree, always pointed at a particular commit.\n+They are not to be confused with remotes, which are meant mainly for branches\n+of the same project; submodules are meant for different projects you would like\n+to make part of your source tree, while the history of the two projects still\n+stays completely independent and you cannot modify the contents of the\n+submodule from within the main project. In case you want to merge the project\n+histories, possibly make local modifications within the tree, but also do not\n+mind that your repository will bulk up with all the contents of the other\n+project, consider adding a remote for the other project and using the 'subtree'\n+merge strategy instead of setting up a submodule.\n+\n+Submodules are composed from a special kind of tree entry (so-called `gitlink`)\n+in the main repository that refers to a particular commit object within\n+the (completely separate) inner repository, and a record in the `.gitmodules`\n+file at the root of the source tree, assigning a logical name to the submodule\n+and describing the default URL the submodule shall be cloned from. The logical\n+name can be used for overriding this URL within your local repository\n+configuration (see 'submodule init').\n \n This command will manage the tree entries and contents of the gitmodules file\n-for you, as well as inspecting the status of your submodules and updating them.\n+for you, as well as inspect the status of your submodules and update them.\n When adding a new submodule to the tree, the 'add' subcommand is to be used.\n However, when pulling a tree containing submodules, these will not be checked\n out by default; the 'init' and 'update' subcommands will maintain submodules\n checked out and at appropriate revision in your working tree. You can inspect\n the current status of your submodules using the 'submodule' subcommand and get\n-an overview of changes 'update' would perform using the 'summary' subcommand.\n+an overview of the changes 'update' would perform using the 'summary'\n+subcommand.\n \n \n COMMANDS\n@@ -81,7 +92,11 @@ init::\n \tInitialize the submodules, i.e. register in .git/config each submodule\n \tname and url found in .gitmodules. The key used in .git/config is\n \t`submodule.$name.url`. This command does not alter existing information\n-\tin .git/config.\n+\tin .git/config. You can then customize the submodule clone URLs in\n+\t.git/config for your local setup and proceed to 'git submodule update';\n+\tyou can also just use 'git submodule update --init' without\n+\tthe explicit 'init' step if you do not intend to customize any\n+\tsubmodule URLs.\n \n update::\n \tUpdate the registered submodules, i.e. clone missing submodules and\n"},{"id":"83686","messageId":"20080717133729.GF4379@zakalwe.fi","threadId":"14462","inReplyTo":"20080717122911.32334.73465.stgit@localhost","subject":"Re: [PATCH] Documentation/git-submodule.txt: Further clarify the description","fromName":"Heikki Orsila","fromEmail":"shdl@zakalwe.fi","sentAt":"2008-07-17T13:37:29Z","receivedAt":"2008-07-17T13:37:29Z","isPatch":true,"sender":{"key":"shdl@zakalwe.fi","avatar":null},"body":"On Thu, Jul 17, 2008 at 02:29:20PM +0200, Petr Baudis wrote:\n> +Submodules allow foreign repositories to be embedded within a dedicated\n> +subdirectory of the source tree, always pointed at a particular commit.\n> +They are not to be confused with remotes, which are meant mainly for branches\n> +of the same project; submodules are meant for different projects you would like\n> +to make part of your source tree, while the history of the two projects still\n> +stays completely independent and you cannot modify the contents of the\n> +submodule from within the main project.\n\nThat is nice, thanks!\n\n-- \nHeikki Orsila\nheikki.orsila@iki.fi\nhttp://www.iki.fi/shd\n"},{"id":"83745","messageId":"7v4p6ofedl.fsf@gitster.siamese.dyndns.org","threadId":"14462","inReplyTo":"20080717122911.32334.73465.stgit@localhost","subject":"Re: [PATCH] Documentation/git-submodule.txt: Further clarify the description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-07-17T20:24:22Z","receivedAt":"2008-07-17T20:24:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Petr Baudis writes:\n\n> This patch rewrites the general description yet again, first clarifying\n> the high-level concept, mentioning the difference to remotes and using\n> the subtree merge strategy, then getting to the details about tree\n> entries and .gitmodules file.\n>\n> The patch also makes few smallar grammar fixups of the rest of the\n> description and clarifies how does 'init' relate to 'update --init'.\n>\n> Cc: Heikki Orsila \n> Signed-off-by: Petr Baudis \n> ---\n>\n> Documentation/git-submodule.txt | 39 +++++++++++++++++++++++++++------------\n> 1 files changed, 27 insertions(+), 12 deletions(-)\n>\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index bb4e6fb..01d0d91 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -18,24 +18,35 @@ SYNOPSIS\n> \n> DESCRIPTION\n> -----------\n> +Submodules allow foreign repositories to be embedded within a dedicated\n> +subdirectory of the source tree, always pointed at a particular commit.\n> +They are not to be confused with remotes, which are meant mainly for branches\n> +of the same project; submodules are meant for different projects you would like\n\nYour lines are getting overlong to be easily quoted and commented...\n\n> +.... In case you want to merge the project\n> +histories, possibly make local modifications within the tree, but also do not\n> +mind that your repository will bulk up with all the contents of the other\n> +project, consider adding a remote for the other project and using the 'subtree'\n> +merge strategy instead of setting up a submodule.\n\nI'd suggest rephrasing \"do not mind\" to something a lot less nagative.\nThe user decides to merge because both histories *are* relevant and at\nthat point there is no _minding_ anymore. If you want to have them, you\nnot only \"do not mind to have\" them but you positively \"want\" them.\n\nOn the other hand, a situation where you would want to use submodules is\nwhen not necessarily all users of the superproject would want to have all\nsubmodules cloned nor checked out. This needs to be stressed with equal\nweight as the above sentence in this \"contrasting merged histories and\nsubmodules\" paragraph. With that explained clearly upfront, it would\nbecome easier for the readers to understand why you can choose not to even\nupdate nor fetch submodules you are not interested in.\n\n> +Submodules are composed from a special kind of tree entry (so-called `gitlink`)\n> +in the main repository that refers to a particular commit object within\n\nDo we have to say \"special\"? Is a gitlink any more special than blob and\ntree entries are? It tends to be rarer, it came later, but I do not think\nthere is anything special from the end user's point of view.\n\n> checked out and at appropriate revision in your working tree. You can inspect\n> the current status of your submodules using the 'submodule' subcommand and get\n> +an overview of the changes 'update' would perform using the 'summary'\n> +subcommand.\n\nSorry, cannot parse the last three lines...\n"},{"id":"83875","messageId":"20080718133644.GQ10151@machine.or.cz","threadId":"14462","inReplyTo":"7v4p6ofedl.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-submodule.txt: Further clarify the description","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2008-07-18T13:36:44Z","receivedAt":"2008-07-18T13:36:44Z","isPatch":true,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"On Thu, Jul 17, 2008 at 01:24:22PM -0700, Junio C Hamano wrote:\n> Your lines are getting overlong to be easily quoted and commented...\n\nI will watch for that.\n\n> Petr Baudis writes:\n> > +.... In case you want to merge the project\n> > +histories, possibly make local modifications within the tree, but also do not\n> > +mind that your repository will bulk up with all the contents of the other\n> > +project, consider adding a remote for the other project and using the 'subtree'\n> > +merge strategy instead of setting up a submodule.\n> \n> I'd suggest rephrasing \"do not mind\" to something a lot less nagative.\n> The user decides to merge because both histories *are* relevant and at\n> that point there is no _minding_ anymore. If you want to have them, you\n> not only \"do not mind to have\" them but you positively \"want\" them.\n> \n> On the other hand, a situation where you would want to use submodules is\n> when not necessarily all users of the superproject would want to have all\n> submodules cloned nor checked out. This needs to be stressed with equal\n> weight as the above sentence in this \"contrasting merged histories and\n> submodules\" paragraph. With that explained clearly upfront, it would\n> become easier for the readers to understand why you can choose not to even\n> update nor fetch submodules you are not interested in.\n\nYou are right. I have tried to reword the sentence to fix these issues.\n\n> > +Submodules are composed from a special kind of tree entry (so-called `gitlink`)\n> > +in the main repository that refers to a particular commit object within\n> \n> Do we have to say \"special\"? Is a gitlink any more special than blob and\n> tree entries are? It tends to be rarer, it came later, but I do not think\n> there is anything special from the end user's point of view.\n\nAlso the parenthesis look ugly, so I have reworded this to a simpler\nformulation.\n\n> > checked out and at appropriate revision in your working tree. You can inspect\n> > the current status of your submodules using the 'submodule' subcommand and get\n> > +an overview of the changes 'update' would perform using the 'summary'\n> > +subcommand.\n> \n> Sorry, cannot parse the last three lines...\n\nThe mention of 'update' is confusing, and it was overally imprecise.\n(I think that in general, the summary/status distinction was not a wise\nUI decision.)\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nAs in certain cults it is possible to kill a process if you know\nits true name. -- Ken Thompson and Dennis M. Ritchie\n"},{"id":"83877","messageId":"20080718134008.26901.17348.stgit@localhost","threadId":"14462","inReplyTo":"20080718133644.GQ10151@machine.or.cz","subject":"[PATCH] Documentation/git-submodule.txt: Further clarify the description","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2008-07-18T13:40:41Z","receivedAt":"2008-07-18T13:40:41Z","isPatch":true,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"This patch rewrites the general description yet again, first clarifying\nthe high-level concept, mentioning the difference to remotes and using\nthe subtree merge strategy, then getting to the details about tree\nentries and .gitmodules file.\n\nThe patch also makes few smallar grammar fixups within the rest of the\ndescription and clarifies how does 'init' relate to 'update --init'.\n\nCc: Heikki Orsila \nSigned-off-by: Petr Baudis \n---\n\n Documentation/git-submodule.txt | 68 ++++++++++++++++++++++++++-------------\n 1 files changed, 46 insertions(+), 22 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex bb4e6fb..755142c 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -18,24 +18,43 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Submodules are a special kind of tree entries which refer to a particular tree\n-state in another repository. The tree entry describes\n-the existence of a submodule with the given name and the exact revision that\n-should be used, while an entry in `.gitmodules` file gives the location of\n-the repository.\n-\n-When checked out, submodules will maintain their own independent repositories\n-within their directories; the only link between the submodule and the \"parent\n-project\" is the tree entry within the parent project mentioned above.\n-\n-This command will manage the tree entries and contents of the gitmodules file\n-for you, as well as inspecting the status of your submodules and updating them.\n-When adding a new submodule to the tree, the 'add' subcommand is to be used.\n-However, when pulling a tree containing submodules, these will not be checked\n-out by default; the 'init' and 'update' subcommands will maintain submodules\n-checked out and at appropriate revision in your working tree. You can inspect\n-the current status of your submodules using the 'submodule' subcommand and get\n-an overview of changes 'update' would perform using the 'summary' subcommand.\n+Submodules allow foreign repositories to be embedded within\n+a dedicated subdirectory of the source tree, always pointed\n+at a particular commit.\n+\n+They are not to be confused with remotes, which are meant mainly\n+for branches of the same project; submodules are meant for\n+different projects you would like to make part of your source tree,\n+while the history of the two projects still stays completely\n+independent and you cannot modify the contents of the submodule\n+from within the main project.\n+In case you want to merge the project histories, possibly make\n+local modifications within the subtree, and considered the fact\n+that all users will have to download and check out the subtree,\n+you may choose to add a remote for the other project and use\n+the 'subtree' merge strategy instead of setting up a submodule.\n+\n+Submodules are composed from a so-called `gitlink` tree entry\n+in the main repository that refers to a particular commit object\n+within the (completely separate) inner repository,\n+and a record in the `.gitmodules` file at the root of the source\n+tree, assigning a logical name to the submodule and describing\n+the default URL the submodule shall be cloned from.\n+The logical name can be used for overriding this URL within your\n+local repository configuration (see 'submodule init').\n+\n+This command will manage the tree entries and contents of the\n+gitmodules file for you, as well as inspect the status of your\n+submodules and update them.\n+When adding a new submodule to the tree, the 'add' subcommand\n+is to be used. However, when pulling a tree containing submodules,\n+these will not be checked out by default;\n+the 'init' and 'update' subcommands will maintain submodules\n+checked out and at appropriate revision in your working tree.\n+You can briefly inspect the up-to-date status of your submodules\n+using the 'status' subcommand and get a detailed overview of the\n+difference between the index and checkouts using the 'summary'\n+subcommand.\n \n \n COMMANDS\n@@ -78,10 +97,15 @@ status::\n \trepository. This command is the default command for 'git-submodule'.\n \n init::\n-\tInitialize the submodules, i.e. register in .git/config each submodule\n-\tname and url found in .gitmodules. The key used in .git/config is\n-\t`submodule.$name.url`. This command does not alter existing information\n-\tin .git/config.\n+\tInitialize the submodules, i.e. register each submodule name\n+\tand url found in .gitmodules into .git/config.\n+\tThe key used in .git/config is `submodule.$name.url`.\n+\tThis command does not alter existing information in .git/config.\n+\tYou can then customize the submodule clone URLs in .git/config\n+\tfor your local setup and proceed to 'git submodule update';\n+\tyou can also just use 'git submodule update --init' without\n+\tthe explicit 'init' step if you do not intend to customize\n+\tany submodule locations.\n \n update::\n \tUpdate the registered submodules, i.e. clone missing submodules and\n"}]}