patchgit-submodule.txt: mention that 'git submodule update' fetches missing commits

'git submodule update' will fetch new commits from the submodule remote
if the SHA-1 recorded in the superproject is not found. This was not
mentioned in the documentation.
---
 Documentation/git-submodule.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

'git submodule update' will fetch new commits from the submodule remote if the SHA-1 recorded in the superproject is not found. This was not mentioned in the documentation.

Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 Documentation/git-submodule.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

Philippe Blain <levraiphilippeblain@gmail.com> writes:

The additional text may not be wrong per-se, but isn't it fairly obvious that there is no other way than to fetch, in order to "update the registered submodules to match what the superproject expects", aka "if the commit object name recorded in the superproject is not found". How else would the subcommand come up with the missing commit out of thin air?

IOW, I have to wonder if this is worth saying, or if these new words are just adding more things the readers need to scan on the page without adding that much information.

Hi Junio,

First off, sorry for not answering this summer. Dscho suggested [1] I try to convince you.

Well, that’s true, but I think that it is important in the documentation to be thorough as to what git commands talk to a remote in what circumstances, and which don’t (this is something that is sometimes not obvious to new users in my opinion). Since by default ‘git pull’ will fetch missing submodule commits, it may not be obvious that ‘git submodule update’ will also fetch from a remote if need be. 

Since 'git pull’ will fetch submodules changes, and is usually run first, the commits are usually already there, but I think it’s worth mentioning that they will be fetched if they need to.

I like thoroughness in software documentation :) 

Philippe.

[1] https://github.com/git/git/pull/596

Philippe Blain <levraiphilippeblain@gmail.com> writes:

Where to draw the line between being thorough and being overly verbose with trivial things is subjective, so I generally tend to side with status quo. But after re-reading the updated text, I do not think it is so bad, so let's apply it with a bit of tweak.

The lines prefixed with "++" are with my tweak, "- " are your original changes and " -" are what was in the version before your patch (I CC'ed Pratyush to show this as an example of what I meant by using combined diff to express an amended commit):

$ git diff -c HEAD HEAD@{1} HEAD^ diff --combined Documentation/git-submodule.txt index 16c765cbfa,0ed5c24dc1..4beb569ae5

'git submodule update' will fetch new commits from the submodule remote if the SHA-1 recorded in the superproject is not found. This was not mentioned in the documentation.

Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
Changes since v1 [4]:
- Added my signed-off, corrected my email address
  and shortened the title of the commit message
  (I had actually done that when I resent my patch in [1] using submitGit, 
  but this dit not add the "v2" prefix)
- Added Junio's suggestion [2] (which was applied in [3] on top of the original 
  submission [4] instead of the revised one [1]), and squashed
- Added Helped-by trailers
- Rebased on v2.23.0 (as was done for [3])

[1] https://public-inbox.org/git/0102016b72a55a7d-fb4ecdb7-9f2b-4204-b888-0000f209c3ff-000000@eu-west-1.amazonses.com/ [2] https://public-inbox.org/git/xmqq8sobdzul.fsf@gitster-ct.c.googlers.com/ [3] https://github.com/gitster/git/commits/pb/submodule-update-fetches [4] https://public-inbox.org/git/0102016a2274c90f-3dbf792f-5b0a-4da4-ada0-9a163a14e68d-000000@eu-west-1.amazonses.com/

 Documentation/git-submodule.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

Philippe Blain <levraiphilippeblain@gmail.com> writes:

Thanks, will replace. This should be ready for 'next', I would think.