What is the point of 'git submodule init'?

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.

Here are a couple example workflows where this might be useful.

Workflow 1: 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 as below, with four submodules in the project (named lib1 - lib4) and three files which reference some of them (named code1 - code3).

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

This style of project is referred to as a monorepo.

You clone "main-project".

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

And the surface of its structure is like below, where there are four projects ("sub-project1" -"sub project4") and a single "shared", all their own submodules:

Projects (e.g. sub-project3) in this workflow are separate from each other, and may optionally leverage the libraries stored in the "shared" submodule.

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 above in Workflow 1, you need to run the command below to clone and check them out:

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.

If you want to combine the two commands:

git submodule update --init --recursive

This git submodule init and git submodule update including and submodule submodules.

As far as I understand this is what the commands do & hence the order required:

# - git submodule init initializes your local configuration file to track the submodules your repository uses, it just sets up the configuration so that you can use the git submodule update command to clone and update the submodules. git submodule init # - git submodule update --init initializes your local configuration file and clones the submodules for you, using the commit specified in the main repository. # note, command bellow will not pull the right branch -- even if it's in your .gitmodules file, for that you need remote. Likely because it looks at the origin (pointer to remote) in github for the available branches. # note, bellow pulls the submodules if you didn't specify them when cloning parent project, ref: https://youtu.be/wTGIDDg0tK8?t=119 git submodule update --init # - The --remote option tells Git to update the submodule to the commit specified in the upstream repository, rather than the commit specified in the main repository. #git submodule update --init --remote git submodule update --init --recursive --remote meta-dataset