submodule: Reference at 'HEAD' does not exist

[creatormir]

I am following the tutorial for submodules. But I get an error.

  File "D:\test\gitpy.py", line 187, in <module>
    sm = cloned_repo.create_submodule("mysubrepo", "subrepo", url=bare_repo.git_dir, branch="master")
  File "D:\Python\Python312\Lib\site-packages\git\repo\base.py", line 496, in create_submodule
    return Submodule.add(self, *args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "D:\Python\Python312\Lib\site-packages\git\objects\submodule\base.py", line 629, in add
    sm.binsha = mrepo.head.commit.binsha
                ^^^^^^^^^^^^^^^^^
  File "D:\Python\Python312\Lib\site-packages\git\refs\symbolic.py", line 297, in _get_commit
    obj = self._get_object()
          ^^^^^^^^^^^^^^^^^^
  File "D:\Python\Python312\Lib\site-packages\git\refs\symbolic.py", line 288, in _get_object
    return Object.new_from_sha(self.repo, hex_to_bin(self.dereference_recursive(self.repo, self.path)))
                                                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "D:\Python\Python312\Lib\site-packages\git\refs\symbolic.py", line 168, in dereference_recursive
    hexsha, ref_path = cls._get_ref_info(repo, ref_path)
                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "D:\Python\Python312\Lib\site-packages\git\refs\symbolic.py", line 278, in _get_ref_info
    return cls._get_ref_info_helper(repo, ref_path)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "D:\Python\Python312\Lib\site-packages\git\refs\symbolic.py", line 257, in _get_ref_info_helper
    raise ValueError("Reference at %r does not exist" % ref_path)
ValueError: Reference at 'HEAD' does not exist

[Byron]

This would happen if the repository that is to be added has an unborn branch, i.e. right after git init before making a commit.

Following the tutorial might also not be too straightforward as some part of the necessary (or assumed) setup isn't necessarily shown.

For now I am closing this, but if you can figure out what could help to make the tutorial better, the issue can be reopened of course. Also, please feel free to submit a PR right away in case you know what to do and want to do it.

[creatormir]

I tried to commit, created a new branch and committed. It didn't work.

[Byron]

test_doc.py has all the code that is needed to setup the base repositories, even though that might be abstract enough to require an IDE to follow the code. It's what you see in the tutorial, itself it's just a test-file from where snippets are extracted, while also allowing these to be continually tested to assure they keep working.

If you choose to dive in, I am sure you will find out what can be improved to prevent such confusion in the future.