Git submodule operations

Using this example:

• Assume you have a foam vault repo named: repo-of-notes
• You have a Quartz repo, forked from https://github.com/jackyzha0/quartz.
• You want to add repo-of-notes as a submodule to Quartz to the content folder so that quartz site can render your notes.

Add submodule

In your Quartz repo, run:

git submodule add https://github.com/username/repo-of-notes.git content

Note that, content/ folder probably is already in your git index, so this command may fail with error. For this example of quartz, just delete the content/ folder and run the command again.

This command should create a .gitmodules file in your Quartz repo which specifies the git-submodule information. It should look like:

[submodule "content"]
    path = content
    url = git@github.com:qining/notes.git
	# You can add this to track a specific branch
	# branch = main

Then you need to:

# Add both the .gitmodules file and the 'content' folder to your index.
git add .gitmodules content
git commit -m "Add submodule as content"
# Just push as normal
git push

Always commit pined implicitly

git-submodule will always have the submodule pined to the specific commit of the submodule when you add it.

git submodule update --init --recursive won’t update the submodule to the latest commit, neither will git clone --recursive

Update submodule commit

Update all submodules to the latest commit:

git submodule update --remote

Note

This command does not mention --rebase or --merge options becaause we assume you don’t make change on submodules (e.g. foam vault repo here) in downstream repo (e.g. quartz repo here).

Remove submodule

deinit first:

# git submodule deinit -f path/to/submodule
git submodule deinit -f content

rm files next:

# git rm -f path/to/submodule
git rm -f content

Note

If you want to keep the files in the work tree: git rm --cached path/to/submodule