What is the point of 'git submodule init'?

Reading the git submodule documentation, there is a use-case that ostensibly justifies the existence of git submodule init as a standalone command.

If a user who has cloned a repository wishes to use a different URL for a submodule than is specified by the upstream repository, then that user can:

git submodule init
vim .git/config # Alter submodule URL as desired, without changing .gitmodules
                # or polluting history.
git submodule update

Imagine the repository has 10 submodules and you are interested in only two submodules of these. In such a case, you may want to get updates from only these two submodules from the remote repository from time to time. git init works well for this, because once you execute the command git init for these two submodules, git submodule update --remote applies only to them.

---

Appended two workflows demo.

Workflow1: Submodules are libraries which several projects use.

I think this is one of the common use cases.

You just cloned "my-project".

git clone https://example.com/demo/my-project

And the surface of its structure is like below.

The contents of .gitmodules

[submodule "lib1"]
    path = lib1
    url = https://example.com/demo/lib1
[submodule "lib2"]
    path = lib2
    url = https://example.com/demo/lib2
[submodule "lib3"]
    path = lib3
    url = https://example.com/demo/lib3
[submodule "lib4"]
    path = lib4
    url = https://example.com/demo/lib4

You want to refactor the code code1.js which references lib1 and lib2 which means you don't need to clone and checkout lib3 and lib4. So you just run the below command.

git submodule init lib1 lib2

Now let's see the contents of .git/config

...
[submodule "lib1"]
    active = true
    url = https://example.com/demo/lib1
[submodule "lib2"]
    active = true
    url = https://example.com/demo/lib2

This means something like "Ready to update lib1 and lib2 from example.com/demo".

At this point, lib1 and lib2 directories are empty. You can clone and checkout lib1 and lib2 with one command:

git submodule update

Now you are able to refactor code1.js without import errors.

Submodules are just references to certain commits. So when you want to update libraries to new versions, you have to update the references. You can do it by the below command.

git submodule update --remote

Now you can see how useful it is to only initialize the submodules you need.

Workflow 2: Each submodule is a project and one big top project includes them.

I'm a fan of this.

You clone "main-project".

git clone https://example.com/demo/main-project

And the surface of its structure is like below.

You can see a directory named "shared". There is a rule in this workflow: if you want to use shared codes of main-project in your project, you have to create the project as a submodule of main-project.

I like to put entity classes in shared directory like below.

Back to the submodule workflow, the contents of .gitmodules is like the following.

[submodule "sub-project1"]
    path = sub-project1
    url = https://example.com/demo/sub-project1
[submodule "sub-project2"]
    path = sub-project2
    url = https://example.com/demo/sub-project2
[submodule "sub-project3"]
    path = sub-project3
    url = https://example.com/demo/sub-project3
[submodule "sub-project4"]
    path = sub-project4
    url = https://example.com/demo/sub-project4

This time you want to refactor some code in the shared directory of the main-project and you know that only sub-project1 and sub-project2 reference shared code, which means you don't need to clone and checkout sub-project3 and sub-project4. So you just run the command below.

git submodule init sub-project1 sub-project2

And like I mentioned in workflow1, you need to run the command below to clone and checkout them.

git submodule update

Would I do git submodule update --remote in this case? Or do I even have to init and update submodules to refactor code in the shared directory? Yes, because you have to run tests in submodules after refactoring the shared code and if any update of submodules is committed and pushed to the remote repository while you are refactoring, then you need to get it by git submodule update --remote.