One could do a submodule, or a clone, or just copy the files and not the repo…
What are the pros and cons of each option?
UPDATE: also subtree as shared by @bep
Looks like this is a repeat question of this previous post:
I use submodules. That way you can easily update your theme to the latest version, yet the version you have is fixed at a particular time (based on commit)
4 Likes
You can also add it as a git subtree – which I would only recommend in some special cases, but I thought I would add it for completeness. If you start in the hugo repo, you see it in action: hugo/docs is a sub tree which also has the theme as a subtree. One of the benefits of this is that we get a full source distribution incl. docs and theme when we do releases.
But in general, I would recommend submodules. Then you can pull in updates with:
git submodule update --remote --merge
```
1 Like
Thanks @bep and @budparr. What if you’ve made changes to your theme that you don’t want to push back to the theme as a PR and you don’t want your local changes to be overwritten by updating your theme (via a submodule)? And when you push your website repo to github you want your changes there along with the rest of the theme you were working with.
After some extensive duckduck-fu, I came across this as what I imagine would answer my question?:
From your question it seems that your submodule (say proj-dep) is technically an external library.
Let us say that the code of proj-dep is hosted at https://github.com/vendor/proj-dep and you have mapped this path to your submodule.
However, you are not simply using proj-dep as is, you are using a modified version of the same.
You should be creating your own fork of https://github.com/vendor/proj-dep to https://github.com/alex/proj-dep and map this second path to your submodule.
You will be able to push your own changes to this fork. Also, you can pull changes from vendor’s proj-dep as and when needed and merge/rebase your fork (eventually pulling them down to your submodule path).
Accurate? Sound like exactly what I’m talking about. Updating the fork with the master would have to happen in/on Github though right? Since the fork is a product of Github, not git or my local repo.
2 Likes
I don’t think so. It’s all Git - has nothing to do with Github, necessarily. Atlassian has some good material on submodules. If you have things you’ve done to the theme that would get overwritten updating the submodule, you’ll need to put those into your local root (or maybe oneday a second theme 
).
2 Likes
Is there any benefit or best practice between the following two methods:
- Forking a theme and adding your fork as a submodule, which you then edit directly as needed. If the upstream theme updates, you can pull in those changes to your fork.
or - Simply adding the theme directly as a submodule and any changes you want to make to the theme you do so by adding them to your hugo site’s own layout directory. This will take precedence over the submodule’s version.
1 keeps things all in their place but seems maybe a little overcomplicated. 2 means you have theme files in two places but simplifies the structure…
1 Like
One of the cool things about the inheritance model used by the lookup order is it may be combined with block layouts. Blocks give you the power to compose layouts so you can override specific pieces of content without carrying around a lot of custom-extended base theme code and makes it easier to pivot between the various possible update methods.
As for the best way, that’s fairly subjective. In my mind the best way would be the one with the least opinion and minimal amount of dependencies (read: git, the hidden dependency in some themes, which makes them less portable and harder to grok).
forgive me but i’m not sure I follow either paragraph. would you mind explaining just a bit more?
This allows you full control while maintaining backups for security. Remember that, while GitHub does not provide private repos on the free tier, others like GitLab do. So you can keep your amended theme private if you like but still get the benefits of a cloud backup.
True, and I see others who fork themes will add their own changes to their fork, which wouldn’t be visible if they were making their changes within the site’s layout folders.
1 Like