Submodule.update() not working as expected

[claradaia]

I did spend a long time trying to figure out whether this was actually an issue or just a misunderstanding of the documentation. Please let me know if I should be using another method.

I am looping through my main module submodules and checking whether the current head is the reference commit (the one registered on the main module). If it's not, I call update() on the submodule. I expected it to have the same effect of running git submodule update <path>, but it's not always the case, especially in the situation I'm trying to handle - when someone has changed branches inside the submodule and eventually decides to deploy the main module.

• Let's call my main module M and the submodule I'm handling S.
• The reference commit for S, registered on M, is the latest commit on the master branch.

Initially, I have S updated through command line, currently on reference commit in detached HEAD state, as expected.
If I run, for example

$ cd <path_to_S>
$ git status
HEAD detached at 0a3f3c5 # latest commit on master branch
nothing to commit, working directory clean
$ git checkout HEAD~5
Previous HEAD position was 0a3f3c5... Some message'
HEAD is now at 42372c8... Another message.

And then run my script in the main module, which is something like:

    repo_M = Repo(M_path)
    for sub in repo_M.submodules:
        # Check if submodule is cloned
        try:
            sub_repo = sub.module()
        except exc.InvalidGitRepositoryError:
            [...]
            continue

        # Check if submodule has local changes
        if sub_repo.is_dirty():
            [...]

        # Check if submodule is in reference commit
        if sub.hexsha != sub_repo.head.commit.hexsha:
            print(sub.name + ': currently on commit \'' + str(sub_repo.head.commit.hexsha)
                      + '\'. Checking out reference commit \'' + str(sub.hexsha) + '\'...')
            try:
                sub.update()
                print(sub.name + ': now on commit \'' + str(sub_repo.head.commit.hexsha))

            except:
               [...]

It correctly checks out the latest commit in master branch.
However, If I run, instead:

$ cd <path_to_S>
$ git status
HEAD detached at 0a3f3c5 # latest commit on master branch
nothing to commit, working directory clean
$ git checkout development
Previous HEAD position was 0a3f3c5... Some message'
Switched to branch 'development'
Your branch is up-to-date with 'origin/development'.

And then execute the script on the main module, it does not check out the reference branch. The hexsha printed on the last message is still the same as before, referencing the latest commit on the development branch. Verifying from the command line, S is also still on development.

I had a look at the code and think it might be due to the bit that checks that it's updating to a newer commit than the current one.

Also, git submodule update works if there are untracked files in the submodule, while sub.update() raises a RepositoryDirtyError exception. I know I could probably handle this some other way, but as above I'm coming from the assumption both should have similar behavior.

Again, I may have misunderstood what the method is for. If that is the case, I appreciate advice on what is the recommended way to check out the reference commit.

[Byron]

Thanks for taking the time to write all this down, and thus help others to reproduce and possibly fix it. I can only say that the submodule implementation is quite a mess, and I am not surprised it's the cause of plenty of issues :/.