What is a 'dirty' Submodule?

Question

I see ignore = dirty in a .gitmodule file.

Example:

[submodule "docs/submodules/netvirt"]
    path = docs/submodules/netvirt
    url = ../netvirt
    branch = .
    ignore = dirty

The documentation states:

"dirty" will ignore all changes to the submodules work tree and takes only differences between the HEAD of the submodule and the commit recorded in the superproject into account.

I cant understand what this means. Can someone state this in a simple language?

What I understand is that say when I added the submodule to the super project, it was at state C (HEAD at C) and then later after sometime its now at state F (HEAD at F). ignore=dirty will only consider changes D, E, F ( which is what it should do! )

Clearly, I have misunderstood something. What is it?

Answer 1

The term "dirty" here means the same as it does elsewhere in Git: the repo in question has tracked files (files that have previously been committed) that have modifications that have not been committed, and/or there are new untracked files.

In the context of the ignore = dirty setting for submodules, this means that if the submodule is dirty (i.e. if it has tracked files with modifications that have not been committed, and/or new untracked files), such changes will be ignored. What will not be ignored is a difference in the checked-out commit, e.g. where the parent project points to commit C but the submodule currently has commit F checked out.

These are the possible states for the submodule, and the status in the parent project with the setting ignore = dirty:

1. Submodule has same commit checked out as recorded in parent project, working directory is clean (no modified or untracked files). The parent project shows the submodule as having no changes.
2. Submodule has same commit checked out as recorded in parent project, working directory is dirty (has modified or untracked files). The parent project shows the submodule as having no changes (since ignore = dirty).
3. Submodule has different commit checked out than recorded in parent project, working directory is clean. The parent project shows the submodule as having changes (visualized as a change in commit hashes).
4. Submodule has different commit checked out than recorded in parent project, working directory is dirty. The parent project shows the submodule as having changes (still visualized as a change in commit hashes, because ignore = dirty).