Stefan Beller [off-list ref] writes:
DESCRIPTION
-----------
+This command will inspect, update and manage submodules.
+Submodules allow you to keep another Git repository in a subdirectory
+of your repository. The other repository has its own history,...
The first line somehow bothered me, so I took a random sample of
commands I often use:
git log
Shows the commit logs.
git show
Shows one or more objects (blobs, trees, tags and commits).
git commit
Stores the current contents of the index in a new commit along with a
log message from the user describing the changes.
git diff
Show changes between the working tree and the index or a tree, changes
between the index and a tree, changes between two trees, changes
between two blob objects, or changes between two files on disk.
git push
Updates remote refs using local refs, while sending objects necessary
to complete the given refs.
I _think_ what bothered me was "This command" (drawing the reaction
"eh, what other command are you going to talk about in the help page
for this command?"). Perhaps
Inspects, updates and manages submodules.
may match the style of other help pages better.
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.
The description of "git config", on which I have a similar
perception, seem to match ;-)
git config
You can query/set/replace/unset options with this command.
On Mon, May 25, 2015 at 3:00 PM, Junio C Hamano [off-list ref] wrote:
Stefan Beller [off-list ref] writes:
quoted
DESCRIPTION
-----------
+This command will inspect, update and manage submodules.
+Submodules allow you to keep another Git repository in a subdirectory
+of your repository. The other repository has its own history,...
The first line somehow bothered me, so I took a random sample of
commands I often use:
git log
Shows the commit logs.
git show
Shows one or more objects (blobs, trees, tags and commits).
git commit
Stores the current contents of the index in a new commit along with a
log message from the user describing the changes.
git diff
Show changes between the working tree and the index or a tree, changes
between the index and a tree, changes between two trees, changes
between two blob objects, or changes between two files on disk.
git push
Updates remote refs using local refs, while sending objects necessary
to complete the given refs.
I _think_ what bothered me was "This command" (drawing the reaction
"eh, what other command are you going to talk about in the help page
for this command?"). Perhaps
Inspects, updates and manages submodules.
may match the style of other help pages better.
Sounds much better than my patch.
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`.
The description of "git config", on which I have a similar
perception, seem to match ;-)
git config
You can query/set/replace/unset options with this command.
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 [off-list ref] wrote:
quoted
Stefan Beller [off-list ref] 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