Unable to check out submodules

[killermoehre]

Hi,

after a fresh clone I hit following error for checking out the submodules

$ LANG=C git clone https://github.com/google/docsy.git
$ LANG=C git submodule update --init --recursive --remote --force
Submodule 'assets/vendor/Font-Awesome' (https://github.com/FortAwesome/Font-Awesome.git) registered for path 'assets/vendor/Font-Awesome'
Submodule 'assets/vendor/bootstrap' (https://github.com/twbs/bootstrap.git) registered for path 'assets/vendor/bootstrap'
Submodule path 'assets/vendor/Font-Awesome': checked out '7cbd7f9951be31f9d06b6ac97739a700320b9130'
fatal: Needed a single revision
fatal: Unable to find current origin/v4-dev revision in submodule path 'assets/vendor/bootstrap'

As we use docsy as submodule in our own Hugo repo, this is quite annoying as we can't build our site.

[deining]

Hi,
...

$ LANG=C git submodule update --init --recursive --remote --force

Why are you using the --remote option?

Simply omit this option and it will work:

git submodule update --init --recursive

[killermoehre]

I require the --remote option to actually update some other repository where docsy itself is a submodule of.

[deining]

You can overwrite the branch in your .git/config, the settings there take precedence over the settings given in .gitmodules. (either use branch = main or branch = HEAD).

[submodule "assets/vendor/bootstrap"]
	active = true
	url = https://github.com/twbs/bootstrap.git
	branch = HEAD

Be aware however, since docsy pulls in bootstrap version 4.6.1, your submodule will be out of sync.

[killermoehre]

Well, docsy doesn't find the v4-dev branch it is pointing to. I don't even want HEAD, I just want docsy to pull from the current v4-dev branch as stated in the .gitmodule.

[killermoehre]

My bad, the PR #823 is not yet merged.

[deining]

Can you please try:

git submodule sync

Does this resolve your problem?

[killermoehre]

I'm switching to proper hugo modules with

[module]
[[module.imports]]
  disable = false
  ignoreConfig = false
  ignoreImports = false
  path = 'github.com/google/docsy'

So, if this works, I think this issue can be closed.

[killermoehre]

Hmm … this doesn't work. How am I supposed to use docsy as a module?

[deining]

Hmm … this doesn't work. How am I supposed to use docsy as a module?

Please note that using docsy as hugo module is work in progress currently it will not work with HEAD of docsy repo.
In order to make it work, PR #801 needs to be merged into master.

I just reworked and rebased #801, IMHO it is ready to merge and won't break anything. Once #801 were merged, you could immediately test it and report your findings back to us.

Meanwhile, you may have a look at the preliminary documentation for docsy as Hugo Module, submitted with PR #802, especially the chapter on Installation.

Note: In case #801 gets merged into master you have to enable module imports in config.toml, on two places, otherwise it will not work for you.

[killermoehre]

So, #801 is merged. What do I need to use docsy as a module?

[deining]

So, #801 is merged. What do I need to use docsy as a module?

You need to convert your existing site to a Hugo module. Detailed instructions are authored already. Good luck, please let me know if conversion worked for you!

[chalin]

I'm going to close this issue since there isn't a problem with Docsy submodules (but rather the particular nature of the context in which you are using docsy) and, in any case, you've decided to give docsy-as-a-hugo-module a try. Thanks for doing that, and as @deining says, do give us feedback either by opening another issue or a discussion.

[killermoehre]

@deining @chalin docsy as module works. Instructions on how to convert the site to a module are well written as well.