Chapter 8: wrong description for `git submodule update`

[phil-blain]

Hi @MikeMcQuaid,

In chapter 8, in section "Update and initialize all submodules: git submodule update --init", you write :

Sometimes at the same time as initializing a repository, you may want to also update it to the latest revision to incorporate any changes that were made in the upstream, submodule repository. Now that we’ve removed the submodule from our repository, we can initialize the submodule and update it to any later revision.

Then you show git submodule update --init and write :

Discussion

If there had been any changes to the GitInPracticeReduxSubmodule repository then the git submodule update --init command would initialize the submodule in the local repository and then update the stored submodule revision to the latest revision in the local repository.

This is not what git submodule update --init does. To quote the man page:

Update the registered submodules to match what the superproject expects by cloning missing submodules, fetching missing commits in submodules and updating the working tree of the submodules.

The behaviour you describe (updating the submodule to incorporate changes in the upstream, submodule repository, is done with git submodule update --remote :

Instead of using the superproject’s recorded SHA-1 to update the submodule, use the status of the submodule’s remote-tracking branch. [...] The only change is the source of the target SHA-1. For example, submodule update --remote --merge will merge upstream submodule changes into the submodules, while submodule update --merge will merge superproject gitlink changes into the submodules. [...] Use this option to integrate changes from the upstream subproject with your submodule’s current HEAD.

---

I see a few ways to resolve this:

• add --remote in that section of the text so that the command matches the text (I think that is not a good idea because git submodule update deserves its own section, it's important to know how to initialize submodules in a fresh clone when you did not clone with --recurse-submodules.)
  or
• remove the wrong description from the git submodule update --init section and explain that this git submodule update checks out the submodule at the commit recorded in the superproject (and initializes them when also using --init). (And maybe add a separate section about git submodule update --remote.)

I also understand that this book is already published and is in "maintenance" mode, so you might not want to do such big modifications to the content. In that case maybe adding an errata would work ? What do you think ?

[MikeMcQuaid]

Hey @phil-blain, sorry for the delay in responding, I've been thinking on how best to address this.

• remove the wrong description from the git submodule update --init section and explain that this git submodule update checks out the submodule at the commit recorded in the superproject (and initializes them when also using --init).

This seems better to me 👍

I also understand that this book is already published and is in "maintenance" mode, so you might not want to do such big modifications to the content. In that case maybe adding an errata would work ?

I'll probably do an errata if I (or another contributor such as yourself 😉) can't get round to this in the nearish future but I think updating the content would be ideal if possible.

I'll add you to a list of contributors in the README if you do make a change like this, I think.

Thanks for the great write-up!

[phil-blain]

I'd be glad to help, with an errata and updating the content.

[MikeMcQuaid]

@phil-blain That would be wonderful! Could you submit PRs? Thanks again!

[phil-blain]

The errata is done. I'll start working on updating the content.