Git submodules

Last week I was talking to a colleague about how a certain problem that could be solved using git submodule bascically mounting a git repository into another git repository. As an example I showed how this blog uses it for the theme. The colleague asked me if I could blog about this. So here goes.

setup of this blog

I have the ronsmits.org for many years and for most of that time it has been self hosted. Even for a long time using the excellent pebble blog software. the software alas broke a few times and this is actually how I met Simon Brown. When I moved house and internet provider mainting the blog became harder and I was not in the headspace of blogging or maintaining the blog. When I finally decided to start blogging again, I had 3 things that I wanted

• not self hosted anymore
• application agnostic blog format(and I really wanted markdown)
• version controlled.

Not self hosting gives you two options, renting something like digitalocean’s pods and run wordpress, pebble or something like that. The other option is to just host static html. At the end of the day that is what a blogpost is, a static html page with the words I put on it. Investigating (read googling around) at that time it was either yekyll or hugo. I chose hugo you can actually read me first post here.

Hugo uses a very good theming engine and loads of people are making awesome themes. On the go hugo site you can find links and examples of hundreds of themes. You have to use a theme with hugo. If you run hugo without a theme this is what you will get:

Building sites … WARN 2021/05/08 14:23:03 found no layout file for "HTML" for kind "home": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

There are the commands I used to make the blog setup:

• $ hugo new site blog
• $ cd blog
• $ git init
• $ cd themes
• $ git submodule add https://github.com/htr3n/hyde-hyde.git

Only focussing on the git submodule command, this is what happened

• the hyde-hyde theme repository is cloned into the theme directory. You can do an ls -lR themes and the whole theme is there.
• in the top directory of the blog is a hidden file now, called .gitmodules. the content of this is

  [submodule "themes/hyde-hyde"]
    path = themes/hyde-hyde
    url = https://github.com/htr3n/hyde-hyde.git
  

So the working git repository(blog) that has been made has everything that’s needed. But what happens when you check it in, after the infamous git commit -am "initial release" and the git push? How is this stored?

The theme directory is not stored in your repository, but a link to the hash of the commit that was pointing to the head of the theme repository that was added to your blog repository. I push my blog to gitlab.com.

The last piece of the puzzle is how to set this up and clone this to another computer? Simple:

• $ git clone <your repository>
• cd into your cloned repository
• $ git submodule init
• $ git submodule update

The complete them repo pointing to the hash commit (d0b58642) has been closed into the themes directory again.

Where does the blog run?

I started this with some choices and one of them was to not self host again. The blog runs as a gitlab pages with ronsmits.org having a CNAME pointing to it. The pipeline implentation of gitlab is awesome and it will automatically build and publish my blog :)