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?

Backed

It means the same as with a non-submodule: "dirty" means the index differs from HEAD and/or the work-tree differs from the index. Each submodule is its own repository, so to test if a submodule is dirty, "cd" into the submodule and test whether the repository is dirty. – Rawdin

Incidentally, I'm still not sure what your actual question is. What command(s) are you running and what do they do that you don't expect, vs what you do expect? – Rawdin

My question is about a feature not about a command. Its just to understand when would a submodule be called 'dirty' – Backed

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).

Merrilee

Answer 2

In my case, I had 4 files that got auto-formatted-on-save in vscode, and while the content was no different, the formatting caused them to be seen as modified and not committed. Found those files, undid the formatting and the "dirty" reference went away.

Annmarieannnora

That was a good reason to use ignore = dirty in the .gitmodule file. – Garner