{"thread":{"id":"39412","subject":"[PATCH] submodule documentation: Reorder introductory paragraphs","startedAt":"2015-05-22T19:38:47Z","lastAt":"2015-05-26T21:58:09Z","messageCount":5,"participants":["Stefan Beller","Philip Oakley","Junio C Hamano","Heiko Voigt"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"261941","messageId":"1432323527-26868-1-git-send-email-sbeller@google.com","threadId":"39412","inReplyTo":null,"subject":"[PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-05-22T19:38:47Z","receivedAt":"2015-05-22T19:38:47Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"It's better to start the man page with a description of what submodules\nactually are instead of saying what they are not.\n\nReorder the paragraphs such that\nthe first short paragraph introduces the submodule concept,\nthe second paragraph highlights the usage of the submodule command,\nthe third paragraph giving background information,\nand finally the fourth paragraph discusing alternatives such\nas subtrees and remotes, which we don't want to be confused with.\n\nThis ordering deepens the knowledge on submodules with each paragraph.\nFirst the basic questions like \"How/what\" will be answered, while the\nunderlying concepts will be taught at a later time.\n\nMaking sure it is not confused with subtrees and remotes is not really\nenhancing knowledge of submodules itself, but rather painting the big\npicture of git concepts, so you could also argue to have it as the second\nparagraph. Personally I think this may confuse readers, specially\nnewcomers though.\n\nAdditionally to reordering the paragraphs, they have been slightly\nreworded.\n\nSigned-off-by: Stefan Beller <sbeller@google.com>\n---\n\nFor now I used a part of Junios suggestion\n    Submodules are not to be confused with remotes, which are other\n    repositories of the same project;\n    \nI like the \"are not to be confused\" part, as they warn the reader\nthat there will be a paragraph not as concise but touching other\ncommands and topics.\n\n Documentation/git-submodule.txt | 50 ++++++++++++++++++-----------------------\n 1 file changed, 22 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 2c25916..d126c86 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -25,22 +25,17 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\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+This command will inspect, update and manage submodules.\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-If you want to merge the project histories and want to treat the\n-aggregated whole as a single project from then on, you may want to\n-add a remote for the other project and use the 'subtree' merge strategy,\n-instead of treating the other project as a submodule. Directories\n-that come from both projects can be cloned and checked out as a whole\n-if you choose to go that route.\n+Submodules allow you to keep another Git repository in a subdirectory\n+of your repository. The other repository has its own history, which does not\n+interfere with the history of the current repository. This can be used to\n+have external dependencies such as libraries for example.\n+\n+When cloning or pulling a repository containing submodules however,\n+these will not be checked out by default; the 'init' and 'update'\n+subcommands will maintain submodules checked out and at\n+appropriate revision in your working tree.\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@@ -51,19 +46,18 @@ describes 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+Submodules are not to be confused with remotes, which are other\n+repositories 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+If you want to merge the project histories and want to treat the\n+aggregated whole as a single project from then on, you may want to\n+add a remote for the other project and use the 'subtree' merge strategy,\n+instead of treating the other project as a submodule. Directories\n+that come from both projects can be cloned and checked out as a whole\n+if you choose to go that route.\n \n COMMANDS\n --------\n-- \n2.4.1.233.g3f9b614.dirty\n"},{"id":"261951","messageId":"FB89514A616F4190A54B09E0520A7ADD@PhilipOakley","threadId":"39412","inReplyTo":"1432323527-26868-1-git-send-email-sbeller@google.com","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-05-22T21:18:27Z","receivedAt":"2015-05-22T21:18:27Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Stefan Beller\" <sbeller@google.com>\n> It's better to start the man page with a description of what \n> submodules\n> actually are instead of saying what they are not.\n>\n> Reorder the paragraphs such that\n> the first short paragraph introduces the submodule concept,\n> the second paragraph highlights the usage of the submodule command,\n> the third paragraph giving background information,\n> and finally the fourth paragraph discusing alternatives such\n> as subtrees and remotes, which we don't want to be confused with.\n>\n> This ordering deepens the knowledge on submodules with each paragraph.\n> First the basic questions like \"How/what\" will be answered, while the\n> underlying concepts will be taught at a later time.\n>\n> Making sure it is not confused with subtrees and remotes is not really\n> enhancing knowledge of submodules itself, but rather painting the big\n> picture of git concepts, so you could also argue to have it as the \n> second\n> paragraph. Personally I think this may confuse readers, specially\n> newcomers though.\n>\n> Additionally to reordering the paragraphs, they have been slightly\n> reworded.\n>\n> Signed-off-by: Stefan Beller <sbeller@google.com>\n> ---\n>\n> For now I used a part of Junios suggestion\n>    Submodules are not to be confused with remotes, which are other\n>    repositories of the same project;\n>\n> I like the \"are not to be confused\" part, as they warn the reader\n> that there will be a paragraph not as concise but touching other\n> commands and topics.\n>\n> Documentation/git-submodule.txt | 50 \n> ++++++++++++++++++-----------------------\n> 1 file changed, 22 insertions(+), 28 deletions(-)\n>\n> diff --git a/Documentation/git-submodule.txt \n> b/Documentation/git-submodule.txt\n> index 2c25916..d126c86 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -25,22 +25,17 @@ SYNOPSIS\n>\n> DESCRIPTION\n> -----------\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> +This command will inspect, update and manage submodules.\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> -If you want to merge the project histories and want to treat the\n> -aggregated whole as a single project from then on, you may want to\n> -add a remote for the other project and use the 'subtree' merge \n> strategy,\n> -instead of treating the other project as a submodule. Directories\n> -that come from both projects can be cloned and checked out as a whole\n> -if you choose to go that route.\n> +Submodules allow you to keep another Git repository in a subdirectory\n> +of your repository. The other repository has its own history, which \n> does not\n> +interfere with the history of the current repository. This can be \n> used to\n> +have external dependencies such as libraries for example.\n> +\n> +When cloning or pulling a repository containing submodules however,\n> +these will not be checked out by default; the 'init' and 'update'\n> +subcommands will maintain submodules checked out and at\n> +appropriate revision in your working tree.\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> @@ -51,19 +46,18 @@ describes the default URL the submodule shall be \n> 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> +Submodules are not to be confused with remotes, which are other\n> +repositories of the same project;\n\nI said (22 May 2015 20:47):\n\"if a nice well understood explanatory phrase can be found \" - I'm happy \nwith yours. Many thanks\n\n>                                        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> +If you want to merge the project histories and want to treat the\n> +aggregated whole as a single project from then on, you may want to\n> +add a remote for the other project and use the 'subtree' merge \n> strategy,\n> +instead of treating the other project as a submodule. Directories\n> +that come from both projects can be cloned and checked out as a whole\n> +if you choose to go that route.\n>\n> COMMANDS\n> --------\n> -- \n> 2.4.1.233.g3f9b614.dirty\n>\n> --\nPhilip \n"},{"id":"262099","messageId":"xmqqfv6k9v1x.fsf@gitster.dls.corp.google.com","threadId":"39412","inReplyTo":"1432323527-26868-1-git-send-email-sbeller@google.com","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-25T22:00:42Z","receivedAt":"2015-05-25T22:00:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller <sbeller@google.com> writes:\n\n>  DESCRIPTION\n>  -----------\n> +This command will inspect, update and manage submodules.\n>  \n> +Submodules allow you to keep another Git repository in a subdirectory\n> +of your repository. The other repository has its own history,...\n\nThe first line somehow bothered me, so I took a random sample of\ncommands I often use:\n\n    git log\n       Shows the commit logs.\n\n    git show\n       Shows one or more objects (blobs, trees, tags and commits).\n\n    git commit\n       Stores the current contents of the index in a new commit along with a\n       log message from the user describing the changes.\n\n    git diff\n       Show changes between the working tree and the index or a tree, changes\n       between the index and a tree, changes between two trees, changes\n       between two blob objects, or changes between two files on disk.\n\n    git push\n       Updates remote refs using local refs, while sending objects necessary\n       to complete the given refs.\n\nI _think_ what bothered me was \"This command\" (drawing the reaction\n\"eh, what other command are you going to talk about in the help page\nfor this command?\").  Perhaps\n\n    Inspects, updates and manages submodules.\n\nmay match the style of other help pages better.\n\nOn the other hand, I probably would not have felt such a strong\n\"strangeness\" if it were described like this:\n\n    This command can help you inspect, update, and manage\n    submodules.\n\nI haven't analized it enough to say why it is, but I suspect it has\nsomething to do with (my own) perception that \"git submodule\" is not\nvery essential to do any of these things (i.e. .gitmodules is a very\nsimple text file), but is primarily a helpful wrapper.\n\nThe description of \"git config\", on which I have a similar\nperception, seem to match ;-)\n\n    git config\n       You can query/set/replace/unset options with this command.\n"},{"id":"262144","messageId":"CAGZ79kZHRRqKpSmnEfd7-UOL9QrPOhQYt7wsfaqGVTZkHc+mhQ@mail.gmail.com","threadId":"39412","inReplyTo":"xmqqfv6k9v1x.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-05-26T17:53:15Z","receivedAt":"2015-05-26T17:53:15Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Mon, May 25, 2015 at 3:00 PM, Junio C Hamano <gitster@pobox.com> wrote:\n> Stefan Beller <sbeller@google.com> writes:\n>\n>>  DESCRIPTION\n>>  -----------\n>> +This command will inspect, update and manage submodules.\n>>\n>> +Submodules allow you to keep another Git repository in a subdirectory\n>> +of your repository. The other repository has its own history,...\n>\n> The first line somehow bothered me, so I took a random sample of\n> commands I often use:\n>\n>     git log\n>        Shows the commit logs.\n>\n>     git show\n>        Shows one or more objects (blobs, trees, tags and commits).\n>\n>     git commit\n>        Stores the current contents of the index in a new commit along with a\n>        log message from the user describing the changes.\n>\n>     git diff\n>        Show changes between the working tree and the index or a tree, changes\n>        between the index and a tree, changes between two trees, changes\n>        between two blob objects, or changes between two files on disk.\n>\n>     git push\n>        Updates remote refs using local refs, while sending objects necessary\n>        to complete the given refs.\n>\n> I _think_ what bothered me was \"This command\" (drawing the reaction\n> \"eh, what other command are you going to talk about in the help page\n> for this command?\").  Perhaps\n>\n>     Inspects, updates and manages submodules.\n>\n> may match the style of other help pages better.\n\nSounds much better than my patch.\n\n>\n> On the other hand, I probably would not have felt such a strong\n> \"strangeness\" if it were described like this:\n>\n>     This command can help you inspect, update, and manage\n>     submodules.\n>\n> I haven't analized it enough to say why it is, but I suspect it has\n> something to do with (my own) perception that \"git submodule\" is not\n> very essential to do any of these things (i.e. .gitmodules is a very\n> simple text file), but is primarily a helpful wrapper.\n\nMy perception is that the submodule man page similar to the subtree\nman page tries to explain an underlying concept as well. The other man\npages you quoted don't do that as the concepts are explained elsewhere(?)\n\nAs a side note: In the Gerrit test suite I use the JGit implementation of\nthe config command to write out .gitmodules files. So maybe `git submodule`\ncan be understood as a specialized form of `git config`.\n\n>\n> The description of \"git config\", on which I have a similar\n> perception, seem to match ;-)\n>\n>     git config\n>        You can query/set/replace/unset options with this command.\n>\n"},{"id":"262169","messageId":"20150526215809.GA922@book.hvoigt.net","threadId":"39412","inReplyTo":"CAGZ79kZHRRqKpSmnEfd7-UOL9QrPOhQYt7wsfaqGVTZkHc+mhQ@mail.gmail.com","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Heiko Voigt","fromEmail":"hvoigt@hvoigt.net","sentAt":"2015-05-26T21:58:09Z","receivedAt":"2015-05-26T21:58:09Z","isPatch":true,"sender":{"key":"hvoigt@hvoigt.net","avatar":"https://avatars.githubusercontent.com/u/184958?v=4"},"body":"On Tue, May 26, 2015 at 10:53:15AM -0700, Stefan Beller wrote:\n> On Mon, May 25, 2015 at 3:00 PM, Junio C Hamano <gitster@pobox.com> wrote:\n> > Stefan Beller <sbeller@google.com> writes:\n> > On the other hand, I probably would not have felt such a strong\n> > \"strangeness\" if it were described like this:\n> >\n> >     This command can help you inspect, update, and manage\n> >     submodules.\n> >\n> > I haven't analized it enough to say why it is, but I suspect it has\n> > something to do with (my own) perception that \"git submodule\" is not\n> > very essential to do any of these things (i.e. .gitmodules is a very\n> > simple text file), but is primarily a helpful wrapper.\n> \n> My perception is that the submodule man page similar to the subtree\n> man page tries to explain an underlying concept as well. The other man\n> pages you quoted don't do that as the concepts are explained elsewhere(?)\n> \n> As a side note: In the Gerrit test suite I use the JGit implementation of\n> the config command to write out .gitmodules files. So maybe `git submodule`\n> can be understood as a specialized form of `git config`.\n\nI do not agree here. That view is too limited. Since in the case of e.g. 'git\nsubmodule add‘ it does not only change the .gitmodules file but adds a gitlink\nentry to the index, moves the database into .git/modules, ... .\n\nAnd even though it is currently not doing much more it might in the\nfuture. E.g. it might make sense to add a 'git submodule gc' command\nwhich allows the user to purge unused submodule databases from the\n.git/modules directory.\n\nSo I would say it is: \"a helper\" or \"a tool\" for submodules. Nothing less\nnothing more. But on the other hand the same is true for other porcelain\ncommands like e.g. 'git commit'. If you take a look at gitcore-tutorial\nyou could also describe it as a wrapper for write-tree, commit-tree and\nupdate-ref to create a commit. Yet the man page says: \"Record changes to\nthe repository\".\n\nSo I am not sure where to draw the line between wrapper and essential\ncommand. As a user I would see it as quite essential since for adding a\nsubmodule I would need to remember a couple of things:\n\n  * clone the database into .git/modules\n  * create the gitlink file\n  * checkout the files to the desired directory\n  * add the url to the .gitmodules file\n\nSo why not go with Junios first suggestion and lets drop the \"This\ncommand can help you...\" and say: \"Inspect, update and manage\nsubmodules\".\n\nCheers Heiko\n"}]}