Subject: Re: [PATCH v3 5/5] Documentation: update add --force option + ignore=all config

From: Ben Knoble <[email-masked]>
Date: Wed, 14 Jan 2026 12:53:17 -0500

> Le 14 janv. 2026 à 02:48, Claus Schneider(Eficode) via GitGitGadget <[email-masked]> a écrit :
> 
> From: "Claus Schneider(Eficode)" <[email-masked]>
> 
> - git-add.adoc: Update the --force documentation for submodule behaviour
>  to be added even the given configuration ignore=all.
> - gitmodules.adoc and config/submodule.adoc: The submodule config
>  ignore=all now need --force in order to update the index.
> 
> Signed-off-by: Claus Schneider(Eficode) <[email-masked]>
> ---
> Documentation/config/submodule.adoc | 13 +++++++------
> Documentation/git-add.adoc          |  5 ++++-
> Documentation/gitmodules.adoc       |  5 ++++-
> 3 files changed, 15 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/config/submodule.adoc b/Documentation/config/submodule.adoc
> index 0672d99117..250a6133d8 100644
> --- a/Documentation/config/submodule.adoc
> +++ b/Documentation/config/submodule.adoc
> @@ -32,15 +32,16 @@ submodule.<name>.fetchRecurseSubmodules::
> 
> submodule.<name>.ignore::
>    Defines under what circumstances "git status" and the diff family show
> -    a submodule as modified. When set to "all", it will never be considered
> -    modified (but it will nonetheless show up in the output of status and
> -    commit when it has been staged), "dirty" will ignore all changes
> -    to the submodule's work tree and
> +    a submodule as modified.
> +    Set to "all" will never consider the

Throughout this patch, missing “When set to…” for idiomatic English. 

> submodule modified. It can
> +    nevertheless be staged using the option --force and it will then show up
> +    in the output of status.
> +    Set to "dirty" will ignore all changes to the submodule's work tree and
>    takes only differences between the HEAD of the submodule and the commit
>    recorded in the superproject into account. "untracked" will additionally
>    let submodules with modified tracked files in their work tree show up.
> -    Using "none" (the default when this option is not set) also shows
> -    submodules that have untracked files in their work tree as changed.
> +    Set to "none"(default) It is also shows submodules that have untracked
> +    files in their work tree as changed.
>    This setting overrides any setting made in .gitmodules for this submodule,
>    both settings can be overridden on the command line by using the
>    "--ignore-submodules" option. The 'git submodule' commands are not
> diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
> index 6192daeb03..941135dc63 100644
> --- a/Documentation/git-add.adoc
> +++ b/Documentation/git-add.adoc
> @@ -75,7 +75,10 @@ in linkgit:gitglossary[7].
> 
> `-f`::
> `--force`::
> -    Allow adding otherwise ignored files.
> +    Allow adding otherwise ignored files. The option is also used when
> +    `submodule.<name>.ignore=all` is set, but you want to stage an
> +    update of the submodule. The `path` to the submodule must be explicitly
> +    specified.
> 
> `--sparse`::
>    Allow updating index entries outside of the sparse-checkout cone.
> diff --git a/Documentation/gitmodules.adoc b/Documentation/gitmodules.adoc
> index d9bec8b187..3792da96aa 100644
> --- a/Documentation/gitmodules.adoc
> +++ b/Documentation/gitmodules.adoc
> @@ -70,7 +70,10 @@ submodule.<name>.ignore::
> --
>    all;; The submodule will never be considered modified (but will
>        nonetheless show up in the output of status and commit when it has
> -        been staged).
> +        been staged). Add `(new commits)` can be overruled using the
> +        `git add --force <submodule.path>`.
> +        The setting affects `status`, `update-index`, `diff` and `log`(due
> +        to underlaying `diff`).
> 
>    dirty;; All changes to the submodule's work tree will be ignored, only
>        committed differences between the `HEAD` of the submodule and its
> --
> gitgitgadget
>