`git submodule add` preferable to `git clone`?

[gershomtripp]

In the Hugo docs, git clone is used to add a theme in the section Install and Use Themes, while git submodule add is used in Quick Start. However, the docs for one theme I found state that git submodule add must be used to avoid certain deployment problems.

Two days ago I installed a different theme whose docs referred to the git clone method via Hugo’s Install and Use Themes. I added the theme this way and it worked, and I deployed my website. However, when I tried to serve the site locally today I only got a blank page. I tested the theme with a new site and also got a blank page. I only managed to fix my website by re-adding the theme with git submodule add.

Is it wrong to deduce that git submodule add is the better method, particularly for newbie-ish or programmer-but-not-web-developer people like myself who either don’t know, or don’t care, about the nuances of the two methods and simply want to deploy a simple, reliable website as quickly as possible? And shouldn’t this be noted somewhere in the official Hugo docs?

[zwbetz]

Hi there,

In short, if you are just copying your generated site files from your computer to a server somewhere, then either command is fine.

The real value of git submodule add comes in when you’re using a service such as Netlify, that will recursively clone your site repo (and theme repo), then build and deploy your site.

[mojoa]

@gershomtripp

simply want to deploy a simple, reliable website as quickly as possible?

Git is totally unnecessary in many cases and can confuse and complicate the process.

If you want to use git, and have the time to learn all the idiosyncrasies, and use it often enough to remember all the detail, and you need the multiuser version control it provides, great!

Otherwise, many people feel comfortable saving and backing up their data like any other data, and using a more traditional file transfer method like sftp or scp to transfer their site to their production environment.

You can use git to store your zip or tar files freely and effectively.

[gershomtripp]

Does that mean my issues serving the site locally on my laptop were just a fluke, or maybe confined to that one theme? I’m pretty confident that the switch from clone to submodule fixed it. Off the top of your head, is there any reason why this would be the case? The theme is learn, in case you want to try to replicate.

[gershomtripp]

Thanks for the explanation. It looks like something else might have been going on behind the scenes that caused my particular issue using clone vs. submodule.

[zwbetz]

Hard to say, without knowing the steps you did to get the error

[gershomtripp]

Just tried to replicate it myself using the exact same steps I used 10 hours ago, and now it works just fine. I upgraded to Mojave yesterday, which broke git and the developer tools. Maybe it broke Hugo too, but it “fixed itself” after a restart . At least I learned something new.

[lewisl]

I would say it is a very bad idea to use themes as git submodules.

In theory, it might be a good idea: you could pick up changes to the theme simply by going down to the top level of the theme (where there will be a .git folder) and then just do git fetch to pickup changes.

But, do you WANT those changes? Maybe, maybe not.

Don’t in any case modify anything from the gitsubmodule! Why? Because you can’t commit it (it’s not yours–you’d have to do a pull request and you probably never intended to do that…) and you’ll have uncommited changes in your own repo for the hugo website.

You can’t fix this by changing the working set. You’ll have to remove the gitsubmodule from your repo. It is not good enough to just edit the .gitsubmodule file with a text editor. You need to git rm it with a few other steps. You’d need to get a non-repo copy of the theme and then git add it to make it part of your repo. See this nice post: https://stackoverflow.com/questions/1759587/how-to-un-submodule-a-git-submodule

If you are saying, “huh? whah?” to any of this, you really don’t want to do it.

If you are saying, “Well, of course–that’s how git works” then you might do this. The only reason would be if you want to modify/maintain the theme you have as a submodule while being able to test what you are doing with a hugo site. I’d still say this is an overly risky way to do that.

And don’t even do the clone thing. Github and build services like netlify and render, etc. will still see the theme as git submodule because it is a nested repo. But, it won’t work right because the .gitsubmodule file or corrrect entries there will be missing. Now, you could fork the repo of the theme and then clone it or submodule it into your own hugo site repo. But, unless you really want to make a lot of changes to the theme not sure why you’d want to. But, you would not have any problem making commits to your site’s rep that include changes to the theme because you own the fork of the theme.

Only if you really, really trust the developer of the theme to maintain it with real testing and careful commits would you want your build/deploy service to grab the theme from the theme maintainer’s repo.

Far safer to make a “snapshot”–an unlinked copy of the theme–and use that in your site and it’s git repo.

It’s plenty easy with Hugo to update themes. Just don’t modify them in place. If you want to change a a layout or stylesheet, just put it in your hugo website’s folders for layouts or assets. These take precedence over the theme. It’s genius. You leave the theme untouched. You can override things from the theme selectively. You can update the theme without losing your overrides (of course, no guarantee your overrides will still work if you update the theme–but they might).

I think the recommendation in the documentation should be changed and the advice to theme authors should be to NOT recommend git clone or git add submodule as a way to install.

It can certainly work. It just has some risks. Nearly all of the risks are mitigated if you NEVER make a local change to a cloned or submodule theme. And this is what most people would do. But, if you DO make a change and your site is its own repo, then you have a bit of a mess to untangle. Very quick to untangle but will require some smart cmdline git work (most git clients might not have the commands to do the cleanup).