Yesterday, someone I know forked my blog and was trying to generate a static blog site using the Hugo Framework. But when he forked my repository and tried to run it to modify my blog locally, he saw a few things missing, and it failed to run. The reason is that when you clone a repository with submodules, you’re essentially getting a reference to the submodule’s repository, not the actual code.

What is a Git submodule?

Git submodules are a powerful tool in the Git version control system that allow you to incorporate external repositories into your main project, maintaining a clear separation between the two while still enabling collaboration and dependency management.

Think of submodules as pointers to specific commits within other repositories. When you add a submodule to your project, a reference to the external repository’s commit is stored in your main repository’s .gitmodules file. This file acts as a configuration file, specifying the location of the submodule and its corresponding commit hash.

Solution

If you try to run the site locally by Hugo after recloning the repository, you need to use the following two commands to solve the error of the layout missing.

git submodule init
git submodule update

  • git submodule init:

    • Initializes the local configuration for each submodule, setting up the necessary files and directories.
    • Essentially, it tells Git, “Hey, I know about these submodules, and I’m ready to work with them.”

  • git submodule update:

    • Fetches and checks out the specified commit of each submodule.
    • This is where the actual code for the submodule is downloaded and placed into its designated directory within your main project.

Conclusion

Git submodules offer a flexible and efficient way to manage external dependencies within your Git projects. By understanding their purpose and how to properly initialize and update them, you can effectively incorporate third-party code into your own repositories.

Remember that submodules are powerful tools, but they require careful consideration and management. By following the steps outlined in this article, you can successfully work with submodules and ensure that your projects function as expected.