Git Submodule Tutorial: Changing Your Hexo Blog Theme

502 字

3 分钟

Git Submodule Tutorial: Changing Your Hexo Blog Theme

2024-05-13

blog

Hexo

/

Github

/

Git

/

Submodule

中文版

0. Background#

The blog I wrote long ago was built with Hexo (portal). Unlike other tutorials, I advocate putting the entire repository on GitHub as a private repository. The advantages include not needing to use the machine where hexo was installed to write posts — you can just upload an md file directly via the GitHub web interface. Also, the original approach is troublesome to migrate, because it compiles locally and you have to download a bunch of libraries every time you migrate. With my approach, you only need to clone the repository (a Serverless platform compiles it into static files).

Changing the theme with my approach is different from other methods — the theme needs to be handled as a submodule. The theme I use is an independent repository forked from someone else’s, making it easy to update to later versions directly on the GitHub web interface. Other people’s deploy method clones the theme directly into the themes folder, which makes direct updates impossible.

So here I’m documenting how to change the theme using git submodule.

1. Find a theme, then fork it#

2. Set up the submodule#

Method 1: Set up directly#

Zhihu submodule tutorial

Add a remote repository project https://github.com/iphysresearch/GWToolkit.git as a submodule to an existing main repository project. The command form is git submodule add <repo_name>, as in the example below: git submodule add https://github.com/iphysresearch/GWToolkit.git GWToolkit If you’re using an older version of Git, you’ll find that the ./GWToolkit directory is empty; you still need to run an extra step, “update submodules”, to download the contents of the remote repository project. $ git submodule update --init --recursive

Method 2: Manual setup (recommended)#

Clone the theme repository you forked into the theme folder. In the main repository directory (the directory at the same level as .git), create a .gitmodules file with the following content:

1
[submodule "themes/hexo-theme-matery"]
2
  path = themes/hexo-theme-matery
3
  url = https://github.com/Tokisaki-Galaxy/hexo-theme-matery.git

Enter the .git folder under the main repository directory, modify the config file, and add the following content:

1
[submodule "themes/hexo-theme-matery"]
2
  url = https://github.com/Tokisaki-Galaxy/hexo-theme-matery.git

Finally, use git submodule status to check whether it’s set up correctly.

Troubleshooting#

Generally, as long as you use the manual setup, there won’t be any problems. If you can’t use Method 1, just use Method 2 to add it manually.

Checklist:

Check whether the .gitmodules file exists in the main repository directory.
Check whether the config file under the .git directory of the main repository contains a [submodules] section.
Run git submodule status; if it shows No submodule mapping found, it means the submodule’s repository hasn’t been cloned locally. You can use the git submodule update --init command to clone the submodule’s repository locally.

3. Verify it’s set as a submodule#

Commit all local changes to the main repository, then push to GitHub. Open your repository on the GitHub website and check whether the theme folder has a different icon and a version number like @xxxx after its name. If not, set it up manually. (Usually the .gitmodules file is missing.) Also, click into the submodule with the @xxxx after its name to check that you can enter it and that it has files.