On Tue, May 26, 2015 at 10:53:15AM -0700, Stefan Beller wrote: > On Mon, May 25, 2015 at 3:00 PM, Junio C Hamano <gitster@xxxxxxxxx> wrote: > > Stefan Beller <sbeller@xxxxxxxxxx> writes: > > On the other hand, I probably would not have felt such a strong > > "strangeness" if it were described like this: > > > > This command can help you inspect, update, and manage > > submodules. > > > > I haven't analized it enough to say why it is, but I suspect it has > > something to do with (my own) perception that "git submodule" is not > > very essential to do any of these things (i.e. .gitmodules is a very > > simple text file), but is primarily a helpful wrapper. > > My perception is that the submodule man page similar to the subtree > man page tries to explain an underlying concept as well. The other man > pages you quoted don't do that as the concepts are explained elsewhere(?) > > As a side note: In the Gerrit test suite I use the JGit implementation of > the config command to write out .gitmodules files. So maybe `git submodule` > can be understood as a specialized form of `git config`. I do not agree here. That view is too limited. Since in the case of e.g. 'git submodule add‘ it does not only change the .gitmodules file but adds a gitlink entry to the index, moves the database into .git/modules, ... . And even though it is currently not doing much more it might in the future. E.g. it might make sense to add a 'git submodule gc' command which allows the user to purge unused submodule databases from the .git/modules directory. So I would say it is: "a helper" or "a tool" for submodules. Nothing less nothing more. But on the other hand the same is true for other porcelain commands like e.g. 'git commit'. If you take a look at gitcore-tutorial you could also describe it as a wrapper for write-tree, commit-tree and update-ref to create a commit. Yet the man page says: "Record changes to the repository". So I am not sure where to draw the line between wrapper and essential command. As a user I would see it as quite essential since for adding a submodule I would need to remember a couple of things: * clone the database into .git/modules * create the gitlink file * checkout the files to the desired directory * add the url to the .gitmodules file So why not go with Junios first suggestion and lets drop the "This command can help you..." and say: "Inspect, update and manage submodules". Cheers Heiko -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html