Dealing with `resources/_gen/assets`

[mathieucaroff]

Is this a BUG REPORT or FEATURE REQUEST?:
bug

Issue description

The syna-start repository contains generated files, in ressources/_gen/assets/. These files appear to be needed for the build to work. However, Hugo sometimes write to these files. This has at least one of the following consequences:

• (C1) (If the Syna users decides not to add the resources/_gen/assets/* files to their commits) Merging changes made in simultaneously on the repository always require manual arbitration to pick one of the two versions of the file, hoping that Hugo and Syna will run fine with it.
• (C2) (If the Syna users leaves the resources/_gen/assets/* files out of their commits) The user has to deal with this files reported as modified by git, even though they should not be committed. They may sometimes need to reset the files using a command like git checkout HEAD -- resources/_gen/assets, to be able to run the git commands which require a clean repository.

Solution proposal

I see two options to deal with the files at resources/_gen/assets/*:

• (A) Syna's documentation warns about these files, and provide the git command to use to have git ignore changes these files, even if they are still part of git source control.
• (B) These files are made part of syna, instead of syna-starter, and /ressources/_gen is added to syna-starter's .gitignore. There are various ways the files may be brought back into the build lifecycle, one of them being to be copied to resources/_gen/assets at the beginning of the hugo build.

Note: I'm new to Hugo, and Syna is the first and only theme I've looked at so far. I'm reporting this bug in Syna's bug tracker, but it may belong to the Hugo bug tracker, in case this issue is not specific to Syna.

[stp-ip]

Thanks for bringing this up. Not sure what the best way to handle is. From Syna's point of view we would keep the generated resources in .gitignore and don't commit those. It leads to merge conflicts and increases check-out size of the repo etc.
The issue is that Hugo makes this mandatory for a theme to add. The reason behind this is that not everyone uses Hugo extended meaning that they would not be able to generate all assets. Due to them being committed they don't need to be generated and therefore it also works with the plain Hugo version.

But you are correct, that might be a fully theme specific thing and recommitting those within Syna start might not be necessary. We'll check it out (no pun intended).

[mathieucaroff]

If the distribution of the resources/_gen/ files is a requirement of Hugo, this issue should be brought to them. I couldn't find any similar issue on their bug tracker. I don't have all the elements to open the issue there. I'll let you open it, if you feel like it.

Meanwhile, I suggest syna-start takes the least-effort path and go with solution (A). I figured what the git commands to run was:

git update-index --assume-unchanged resources/_gen/assets/js/scripts/*
git update-index --assume-unchanged resources/_gen/assets/scss/styles/*

---

Edit: Here's the link to the doc for --assume-unchanged

[stp-ip]

The submission guidelines for Hugo themes: https://github.com/gohugoio/hugoThemes#resources
This was discussed and from Hugo's point of view working as expected.

The problem with the --assume-unchanged is that someone using the resources and deploying it with a non extended Hugo version will pull old generated state. That is at first a breaking change and needs a few more thoughts unfortunately.

[mathieucaroff]

The problem with the --assume-unchanged is that someone using the resources and deploying it with a non extended Hugo version will pull old generated state. That is at first a breaking change and needs a few more thoughts unfortunately.

This seems weird. Does it mean that I need to run hugo server before any commit I make to generate an updated version of the resources/_gen files, because the build system wouldn't be able to generate it? -- This definitely feels like a shortfall of the build system (Hugo).

[stp-ip]

It's mostly about backwards compatability and in that sense yes it is a shortfall. Previously plain Hugo worked so not all build systems run hugo extended etc. Not saying this is perfect or we shouldn't change it from the syna start side at least, but it needs a few thoughts first.