git-add: Skip submodules with ignore=all unless --force and explicit path used

[bicschneider]

The ignore=all configuration for submodules is currently honored by
status and diff, but not by add. This inconsistency causes friction
when working with submodules:

• Developers unintentionally stage submodule updates, leading to conflicts
  and unnecessary changes.
• Tracking branches in submodule configs causes friction as updates
  to the submodule SHA1 are added without intent.

This patch aligns git add with the behavior of status and diff:

• Submodules marked ignore=all are skipped by default.
• Attempting to add such a submodule explicitly now requires --force.

A submodule can frictionless track a branch in the configuration or
manually switched to and use update --update --remote without
unintentionally add the changes to the super-project.

Tests that previously added submodules without --force have been updated
accordingly. A new test is added to test the behavior of git add with and
without --force.

CC: Ævar Arnfjörð Bjarmason [email protected]
CC: Junio C Hamano [email protected]
CC: Brandon Williams [email protected]
cc: Phillip Wood [email protected]
cc: Claus Schneider [email protected]
cc: Ben Knoble [email protected]
cc: "Kristoffer Haugsbakk" [email protected]

[gitgitgadget]

Welcome to GitGitGadget

Hi @bicschneider, and welcome to GitGitGadget, the GitHub App to send patch series to the Git mailing list from GitHub Pull Requests.

Please make sure that either:

• Your Pull Request has a good description, if it consists of multiple commits, as it will be used as cover letter.
• Your Pull Request description is empty, if it consists of a single commit, as the commit message should be descriptive enough by itself.

You can CC potential reviewers by adding a footer to the PR description with the following syntax:

CC: Revi Ewer <[email protected]>, Ill Takalook <[email protected]>

NOTE: DO NOT copy/paste your CC list from a previous GGG PR's description,
because it will result in a malformed CC list on the mailing list. See
example.

Also, it is a good idea to review the commit messages one last time, as the Git project expects them in a quite specific form:

• the lines should not exceed 76 columns,
• the first line should be like a header and typically start with a prefix like "tests:" or "revisions:" to state which subsystem the change is about, and
• the commit messages' body should be describing the "why?" of the change.
• Finally, the commit messages should end in a Signed-off-by: line matching the commits' author.

It is in general a good idea to await the automated test ("Checks") in this Pull Request before contributing the patches, e.g. to avoid trivial issues such as unportable code.

Contributing the patches

Before you can contribute the patches, your GitHub username needs to be added to the list of permitted users. Any already-permitted user can do that, by adding a comment to your PR of the form /allow. A good way to find other contributors is to locate recent pull requests where someone has been /allowed:

• Search: is:pr is:open "/allow"

Both the person who commented /allow and the PR author are able to /allow you.

An alternative is the channel #git-devel on the Libera Chat IRC network:

<newcontributor> I've just created my first PR, could someone please /allow me? https://github.com/gitgitgadget/git/pull/12345
<veteran> newcontributor: it is done
<newcontributor> thanks!

Once on the list of permitted usernames, you can contribute the patches to the Git mailing list by adding a PR comment /submit.

If you want to see what email(s) would be sent for a /submit request, add a PR comment /preview to have the email(s) sent to you. You must have a public GitHub email address for this. Note that any reviewers CC'd via the list in the PR description will not actually be sent emails.

After you submit, GitGitGadget will respond with another comment that contains the link to the cover letter mail in the Git mailing list archive. Please make sure to monitor the discussion in that thread and to address comments and suggestions (while the comments and suggestions will be mirrored into the PR by GitGitGadget, you will still want to reply via mail).

If you do not want to subscribe to the Git mailing list just to be able to respond to a mail, you can download the mbox from the Git mailing list archive (click the (raw) link), then import it into your mail program. If you use GMail, you can do this via:

curl -g --user "<EMailAddress>:<Password>" \
    --url "imaps://imap.gmail.com/INBOX" -T /path/to/raw.txt

To iterate on your change, i.e. send a revised patch or patch series, you will first want to (force-)push to the same branch. You probably also want to modify your Pull Request description (or title). It is a good idea to summarize the revision by adding something like this to the cover letter (read: by editing the first comment on the PR, i.e. the PR description):

Changes since v1:
- Fixed a typo in the commit message (found by ...)
- Added a code comment to ... as suggested by ...
...

To send a new iteration, just add another PR comment with the contents: /submit.

Need help?

New contributors who want advice are encouraged to join [email protected], where volunteers who regularly contribute to Git are willing to answer newbie questions, give advice, or otherwise provide mentoring to interested contributors. You must join in order to post or view messages, but anyone can join.

You may also be able to find help in real time in the developer IRC channel, #git-devel on Libera Chat. Remember that IRC does not support offline messaging, so if you send someone a private message and log out, they cannot respond to you. The scrollback of #git-devel is archived, though.

[gitgitgadget]

There are issues in commit a3105e7:
first working submodule ignore=all skipped in adding
Commit checks stopped - the message is too short
Commit not signed off

[gitgitgadget]

There are issues in commit b2d5354:
add --force for adding submodule even ignore=all is set
Commit checks stopped - the message is too short
Commit not signed off

[gitgitgadget]

There are issues in commit 8348a4a:
create tests for git add of submodule behavior for ignore=all
Commit checks stopped - the message is too short
Commit not signed off

[gitgitgadget]

There are issues in commit 6657438:
remove unnecassary trace print in read-cache.c
Commit checks stopped - the message is too short
Commit not signed off

[gitgitgadget]

There are issues in commit c2d703e:
update tests with explicit scenary around ignore=all and using --ignore-submodules option on log, status
Commit checks stopped - the message is too short
First line of commit message is too long (> 76 columns)
Commit not signed off

[gitgitgadget]

There are issues in commit a56d8b8:
add description per test-case
Commit checks stopped - the message is too short
Commit not signed off

[gitgitgadget]

There are issues in commit 79598c6:
update documentation for add and gitmodules
Commit checks stopped - the message is too short
Commit not signed off

[gitgitgadget]

There are issues in commit 1b8d93b:
Add required explicit pathspec in order to add
Commit checks stopped - the message is too short
Commit not signed off

[gitgitgadget]

There are issues in commit e45daed:
clean-up tailing spaces, traces, writings and shell spellcheck in test
Commit checks stopped - the message is too short
Commit not signed off

[dscho]

/allow

[gitgitgadget]

User bicschneider is now allowed to use GitGitGadget.

WARNING: bicschneider has no public email address set on GitHub; GitGitGadget needs an email address to Cc: you on your contribution, so that you receive any feedback on the Git mailing list. Go to https://github.com/settings/profile to make your preferred email public to let GitGitGadget know which email address to use.

[dscho]

@bicschneider the Git project is very particular about the form of the commit messages it accepts, and it is outright hostile towards contributors who send patches that introduce white-space problems even if those are fixed by later patches in the same patch series (they demand that the fixes are squashed into the appropriate patches, which I recommend you do before /submiting).

Further, they are adamant about the Signed-off-by trailer. You can fix it by calling git commit --amend --reset-author --signoff, or via git rebase --signoff.

Finally, you can increase the chances for a pleasant review on the Git mailing list dramatically by imitating the rather verbose style of Git's own commit messages. There is some really useful guidance here, in particular the part where it recommends to ensure that the following are covered by the commit message:

	What you’re doing	Why you’re doing it
High-level (strategic)	Intent (what does this accomplish?)	Context (why does the code do what it does now?)
Low-level (tactical)	Implementation (what did you do to accomplish your goal?)	Justification (why is this change being made?)

[gitgitgadget]

There are issues in commit fa7cf4e:
read-cache: let read-cache respect submodule ignore=all and bypass with --force
First line of commit message is too long (> 76 columns)
Lines in the body of the commit messages should be wrapped between 60 and 76 characters.
Indented lines, and lines without whitespace, are exempt

[gitgitgadget]

There are issues in commit 78c6a1a:
tests: Add new t2206-add-submodule-ignored.sh to test ignore=all scenario
Prefixed commit message must be in lower case

[gitgitgadget]

There are issues in commit d94d2d5:
Documentation: update add and submodule describing the ignore=all and --force
First line of commit message is too long (> 76 columns)
Lines in the body of the commit messages should be wrapped between 60 and 76 characters.
Indented lines, and lines without whitespace, are exempt

[dscho]

@bicschneider you needn't worry about the documentation and win+Meson breakages, they are broken in Git's own master branch, too, since Oct 10 and Oct 8, respectively.

[bicschneider]

/allow

[gitgitgadget]

User bicschneider already allowed to use GitGitGadget.

[bicschneider]

/preview

[gitgitgadget]

On the Git mailing list, Claus Schneider wrote (reply to this):

Thanks Junio - well received and noted. I have updated the PR
description accordingly, but I have not changed the "--force" in the
description even though I have implemented
''--include-ignored-submodules' as Philip had the input not to use
"--force". He suggested using a new option. Philips comment:

> I'm not convinced that the approach of using "--force" is a good idea as
> it conflates ignoring changes to tracked paths (which is what
> submodule.<name>.ignore" does) with ignoring untracked paths (which is
> what ".gitignore" does). If we're happy to break existing uses that rely
> on the current behavior then having a new option to override
> submodule.<name>.ignore strikes me as a better way forward. I don't have
> much experience of using submodules so I can't comment on whether
> changing the behavior is a good idea or not.

I think it will be more simple to use the '--force' option though and
keep the amount of options lower and less to remember. Given your
comments about more usages of bytes for option also becomes obsolete
if we stick to "--force". I am happy to do so.

I am investigating your other comments on the patches in the meantime.

On Thu, Nov 13, 2025 at 8:58 PM Junio C Hamano <[email protected]> wrote:
>
> "Claus Schneider via GitGitGadget" <[email protected]> writes:
>
> > The feature of configuring a submodule to "ignore=all" is nicely respected
> > in commands "status" and "diff".
>
> "nicely respected" is not very informative for those who do not know
> what the setting does.  Saying something like
>
>     "git status" and "git diff" will not report modified submodules
>     with submodule.<name>.ignore set to "all".
>
> would not waste significantly more bytes than what you wrote, and is
> more helpful.
>
> > However the "add" command does not respect
> > the configuration the same way.
>
> Again, "does not respect" and then what?  Running "git add" on a
> submodule with submodule.<name>.ignore set to "all" does what?
> Complains that it has changes but because .ignore is set it won't
> add?  Adds it silently?  Something else?
>
> > The behavior is problematic for the logic
> > between status/diff and add.
>
> After this sentence, "because ..." is missing.  Please help readers
> understand the issue you perceive as problematic more easily.
>
> I am guessing that you are assuming that an "add", after "diff" or
> "status" said there is no change, is expected to be a no-op, but I
> cannot be sure if that is what you are referring to here with the
> reason left unsaid like the above.
>
> > Secondly it makes it problematic to track
> > branches in the submodule configuration as developers unintentionally keeps
> > add submodule updates and get conflicts for no intentional reason. Both adds
> > unnecessary friction to the usage of submodules.
> >
> > The patches implement the same logical behavior for ignore=all submodules as
> > regular ignored files. The status now does not show any diff - nor will the
> > add command update the reference submodule reference. If you add the
> > submodule path which is ignore=all then you are presented with a message
> > that you need to use the --force option.
>
> I vaguely recall that an earlier discussion between you and Phillip
> were concluding against "--force"?  I personally feel it is in line
> with "git add foo.o" (when '*.o' is in .gitignore) gets rejected and
> "git add -f foo.o" is a way to override it, but in the list of
> patches below, I see --include-ignored-submodules (no, our command
> line option names do not use underscore for inter-word-gaps), so I
> suspect the description in the cover letter around here is stale?
>
>
> > The branch=, ignore=all (and
> > update=none) now works great with update --remote,
>
> Again, "great" is not very informative, and as bad as "nicely
> respected".  Avoid using these adjectives loaded with unnecessary
> value judgements, and instead trust your readers.  They are
> intelligent to judge if the updated behaviour is great or not for
> themselves.  Try to use the same bytes on helping readers understand
> what actually happens.
>
> > but developers does not
>
> "do not".
>
> > have to consider changes in the updates of the submodule sha1. The
> > implementation removes a friction of working with submodules and can be used
> > like the repo tool with branches configured. The submodule status report
> > could be used for build/release documentation for reproduction of a setup.
> >
> > A few tests used the adding of submodules without --force, hence they have
> > been updated to use the --force option.
> >
> > Claus Schneider(Eficode) (5):
> >   read-cache: update add_files_to_cache take param
> >     include_ignored_submodules
> >   read-cache: add/read-cache respect submodule ignore=all
> >   tests: add new t2206-add-submodule-ignored.sh to test ignore=all
> >     scenario
> >   tests: fix existing tests when add an ignore=all submodule
> >   Documentation: add --include_ignored_submodules + ignore=all config
> >
> >  .devcontainer/Dockerfile            |  70 +++++++++++++++
> >  .devcontainer/Dockerfile.standalone |  76 ++++++++++++++++
> >  .devcontainer/devcontainer.json     |  25 ++++++
> >  Documentation/config/submodule.adoc |  13 +--
> >  Documentation/git-add.adoc          |   5 ++
> >  Documentation/gitmodules.adoc       |   5 +-
> >  builtin/add.c                       |   4 +-
> >  builtin/checkout.c                  |   2 +-
> >  builtin/commit.c                    |   2 +-
> >  read-cache-ll.h                     |   2 +-
> >  read-cache.c                        |  54 ++++++++++-
> >  t/lib-submodule-update.sh           |   6 +-
> >  t/meson.build                       |   1 +
> >  t/t2206-add-submodule-ignored.sh    | 134 ++++++++++++++++++++++++++++
> >  t/t7508-status.sh                   |   2 +-
> >  15 files changed, 384 insertions(+), 17 deletions(-)
> >  create mode 100644 .devcontainer/Dockerfile
> >  create mode 100644 .devcontainer/Dockerfile.standalone
> >  create mode 100644 .devcontainer/devcontainer.json
> >  create mode 100755 t/t2206-add-submodule-ignored.sh
> >
> >
> > base-commit: 81f86aacc4eb74cdb9c2c8082d36d2070c666045
> > Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1987%2FPraqma%2Frespect-submodule-ignore-v2
> > Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1987/Praqma/respect-submodule-ignore-v2
> > Pull-Request: https://github.com/gitgitgadget/git/pull/1987
> >
> > Range-diff vs v1:
> >
> >  1:  d98cca698d ! 1:  5796009122 read-cache: update add_files_to_cache to take param ignored_too(--force)
> >      @@ Metadata
> >       Author: Claus Schneider(Eficode) <[email protected]>
> >
> >        ## Commit message ##
> >      -    read-cache: update add_files_to_cache to take param ignored_too(--force)
> >      +    read-cache: update add_files_to_cache take param include_ignored_submodules
> >
> >      -    The ignored_too parameter is added to the function add_files_to_cache for
> >      -    usage of explicit updating the index for the updated submodule using the
> >      -    explicit patchspec to the submodule.
> >      +    The include_ignored_submodules parameter is added to the function
> >      +    add_files_to_cache for usage of explicit updating the index for the updated
> >      +    submodule using the explicit patchspec to the submodule.
> >
> >           Signed-off-by: Claus Schneider(Eficode) <[email protected]>
> >
> >        ## builtin/add.c ##
> >      +@@ builtin/add.c: N_("The following paths are ignored by one of your .gitignore files:\n");
> >      + static int verbose, show_only, ignored_too, refresh_only;
> >      + static int ignore_add_errors, intent_to_add, ignore_missing;
> >      + static int warn_on_embedded_repo = 1;
> >      ++static int include_ignored_submodules;
> >      +
> >      + #define ADDREMOVE_DEFAULT 1
> >      + static int addremove = ADDREMOVE_DEFAULT;
> >      +@@ builtin/add.c: static struct option builtin_add_options[] = {
> >      +        OPT_BOOL( 0 , "ignore-errors", &ignore_add_errors, N_("just skip files which cannot be added because of errors")),
> >      +        OPT_BOOL( 0 , "ignore-missing", &ignore_missing, N_("check if - even missing - files are ignored in dry run")),
> >      +        OPT_BOOL(0, "sparse", &include_sparse, N_("allow updating entries outside of the sparse-checkout cone")),
> >      ++    OPT_BOOL(0, "include-ignored-submodules", &include_ignored_submodules, N_("add submodules even if they has configuration ignore=all")),
> >      +        OPT_STRING(0, "chmod", &chmod_arg, "(+|-)x",
> >      +                   N_("override the executable bit of the listed files")),
> >      +        OPT_HIDDEN_BOOL(0, "warn-embedded-repo", &warn_on_embedded_repo,
> >       @@ builtin/add.c: int cmd_add(int argc,
> >               else
> >                       exit_status |= add_files_to_cache(repo, prefix,
> >                                                         &pathspec, ps_matched,
> >       -                                                 include_sparse, flags);
> >      -+                                                 include_sparse, flags, ignored_too);
> >      ++                                                 include_sparse, flags, include_ignored_submodules);
> >
> >               if (take_worktree_changes && !add_renormalize && !ignore_add_errors &&
> >                   report_path_error(ps_matched, &pathspec))
> >      @@ read-cache.c: void overlay_tree_on_index(struct index_state *istate,
> >               int include_sparse;
> >               int flags;
> >               int add_errors;
> >      -+       int ignored_too;
> >      ++       int include_ignored_submodules;
> >        };
> >
> >        static int fix_unmerged_status(struct diff_filepair *p,
> >       @@ read-cache.c: static void update_callback(struct diff_queue_struct *q,
> >      +                default:
> >      +                        die(_("unexpected diff status %c"), p->status);
> >      +                case DIFF_STATUS_MODIFIED:
> >      +-               case DIFF_STATUS_TYPE_CHANGED:
> >      ++               case DIFF_STATUS_TYPE_CHANGED: {
> >      ++                       struct stat st;
> >      ++                       if (!lstat(path, &st) && S_ISDIR(st.st_mode)) { // only consider submodule if it is a directory
> >      ++                               const struct submodule *sub = submodule_from_path(data->repo, null_oid(the_hash_algo), path);
> >      ++                               if (sub && sub->name && sub->ignore && !strcmp(sub->ignore, "all")) {
> >      ++                                       int pathspec_matches = 0;
> >      ++                                       char *norm_pathspec = NULL;
> >      ++                                       int ps_i;
> >      ++                                       trace_printf("ignore=all %s\n", path);
> >      ++                                       trace_printf("pathspec %s\n",
> >      ++                                                       (data->pathspec && data->pathspec->nr) ? "has pathspec" : "no pathspec");
> >      ++                                       /* Safely scan all pathspec items (q->nr may exceed pathspec->nr). */
> >      ++                                       if (data->pathspec) {
> >      ++                                               for (ps_i = 0; ps_i < data->pathspec->nr; ps_i++) {
> >      ++                                                       const char *m = data->pathspec->items[ps_i].match;
> >      ++                                                       if (!m)
> >      ++                                                               continue;
> >      ++                                                       norm_pathspec = xstrdup(m);
> >      ++                                                       strip_dir_trailing_slashes(norm_pathspec);
> >      ++                                                       if (!strcmp(path, norm_pathspec)) {
> >      ++                                                               pathspec_matches = 1;
> >      ++                                                               FREE_AND_NULL(norm_pathspec);
> >      ++                                                               break;
> >      ++                                                       }
> >      ++                                                       FREE_AND_NULL(norm_pathspec);
> >      ++                                               }
> >      ++                                       }
> >      ++                                       if (pathspec_matches) {
> >      ++                                               if (data->include_ignored_submodules && data->include_ignored_submodules > 0) {
> >      ++                                                       trace_printf("Add ignored=all submodule due to --include_ignored_submodules: %s\n", path);
> >      ++                                               } else {
> >      ++                                                       printf(_("Skipping submodule due to ignore=all: %s"), path);
> >      ++                                                       printf(_("Use --include_ignored_submodules, if you really want to add them.") );
> >      ++                                                       continue;
> >      ++                                               }
> >      ++                                       } else {
> >      ++                                               /* No explicit pathspec match -> skip silently (or with trace). */
> >      ++                                               trace_printf("pathspec does not match %s\n", path);
> >      ++                                               continue;
> >      ++                                       }
> >      ++                               }
> >      ++                       }
> >      +                        if (add_file_to_index(data->index, path, data->flags)) {
> >      +                                if (!(data->flags & ADD_CACHE_IGNORE_ERRORS))
> >      +                                        die(_("updating files failed"));
> >      +@@ read-cache.c: static void update_callback(struct diff_queue_struct *q,
> >
> >        int add_files_to_cache(struct repository *repo, const char *prefix,
> >                              const struct pathspec *pathspec, char *ps_matched,
> >       -                      int include_sparse, int flags)
> >      -+                      int include_sparse, int flags, int ignored_too )
> >      ++                      int include_sparse, int flags, int include_ignored_submodules )
> >        {
> >               struct update_callback_data data;
> >               struct rev_info rev;
> >      @@ read-cache.c: int add_files_to_cache(struct repository *repo, const char *prefix
> >               data.include_sparse = include_sparse;
> >               data.flags = flags;
> >       +       data.repo = repo;
> >      -+       data.ignored_too = ignored_too;
> >      ++       data.include_ignored_submodules = include_ignored_submodules;
> >       +       data.pathspec = (struct pathspec *)pathspec;
> >
> >               repo_init_revisions(repo, &rev, prefix);
> >  2:  d1b02617e6 ! 2:  9ec79b9a11 read-cache: let read-cache respect submodule ignore=all and --force
> >      @@ Metadata
> >       Author: Claus Schneider(Eficode) <[email protected]>
> >
> >        ## Commit message ##
> >      -    read-cache: let read-cache respect submodule ignore=all and --force
> >      +    read-cache: add/read-cache respect submodule ignore=all
> >
> >      -    Given the submdule configuration is ignore=all then only update the
> >      -    submdule if the --force option is given and the submodule is explicit
> >      -    given in the pathspec.
> >      +    Submodules configured with ignore=all are now skipped during add operations
> >      +    unless overridden by --include-ignored-submodules and the submodule path is
> >      +    explicitly specified.
> >
> >           A message is printed (like ignored files) guiding the user to use the
> >      -    --force flag if the user has explicitely want to update the submodule
> >      -    reference.
> >      +    --include-ignored-submodules flag if the user has explicitely want to update
> >      +    the submodule reference.
> >
> >           The reason for the change is support submodule branch tracking or
> >           similar and git status state nothing and git add should not add either.
> >      @@ Commit message
> >           the submodule is already tracked.
> >
> >           The change opens up a lot of possibilities for submodules to be used
> >      -    more freely and a like the repo tool. A submodule can be added for many
> >      +    more freely and simular to the repo tool. A submodule can be added for many
> >           more reason and loosely coupled dependencies to the super repo which often
> >           gives the friction of handle the explicit commits and updates without
> >           the need for tracking the submodule sha1 by sha1.
> >      @@ read-cache.c
> >        /* Mask for the name length in ce_flags in the on-disk index */
> >
> >       @@ read-cache.c: static void update_callback(struct diff_queue_struct *q,
> >      -                default:
> >      -                        die(_("unexpected diff status %c"), p->status);
> >      -                case DIFF_STATUS_MODIFIED:
> >      --               case DIFF_STATUS_TYPE_CHANGED:
> >      -+               case DIFF_STATUS_TYPE_CHANGED: {
> >      -+                       struct stat st;
> >      -+                       if (!lstat(path, &st) && S_ISDIR(st.st_mode)) { // only consider submodule if it is a directory
> >      -+                               const struct submodule *sub = submodule_from_path(data->repo, null_oid(the_hash_algo), path);
> >      -+                               if (sub && sub->name && sub->ignore && !strcmp(sub->ignore, "all")) {
> >      -+                                       int pathspec_matches = 0;
> >      -+                                       char *norm_pathspec = NULL;
> >      -+                                       int ps_i;
> >      -+                                       trace_printf("ignore=all %s\n", path);
> >      -+                                       trace_printf("pathspec %s\n",
> >      -+                                                       (data->pathspec && data->pathspec->nr) ? "has pathspec" : "no pathspec");
> >      -+                                       /* Safely scan all pathspec items (q->nr may exceed pathspec->nr). */
> >      -+                                       if (data->pathspec) {
> >      -+                                               for (ps_i = 0; ps_i < data->pathspec->nr; ps_i++) {
> >      -+                                                       const char *m = data->pathspec->items[ps_i].match;
> >      -+                                                       if (!m)
> >      -+                                                               continue;
> >      -+                                                       norm_pathspec = xstrdup(m);
> >      -+                                                       strip_dir_trailing_slashes(norm_pathspec);
> >      -+                                                       if (!strcmp(path, norm_pathspec)) {
> >      -+                                                               pathspec_matches = 1;
> >      -+                                                               FREE_AND_NULL(norm_pathspec);
> >      -+                                                               break;
> >      -+                                                       }
> >      -+                                                       FREE_AND_NULL(norm_pathspec);
> >      -+                                               }
> >      -+                                       }
> >      -+                                       if (pathspec_matches) {
> >      -+                                               if (data->ignored_too && data->ignored_too > 0) {
> >      -+                                                       trace_printf("Forcing add of submodule ignored=all due to --force: %s\n", path);
> >      -+                                               } else {
> >      -+                                                       printf(_("Skipping submodule due to ignore=all: %s"), path);
> >      -+                                                       printf(_("Use -f if you really want to add them.") );
> >      -+                                                       continue;
> >      -+                                               }
> >      -+                                       } else {
> >      -+                                               /* No explicit pathspec match -> skip silently (or with trace). */
> >      -+                                               trace_printf("pathspec does not match %s\n", path);
> >      -+                                               continue;
> >      -+                                       }
> >      -+                               }
> >      -+                       }
> >      -                        if (add_file_to_index(data->index, path, data->flags)) {
> >      -                                if (!(data->flags & ADD_CACHE_IGNORE_ERRORS))
> >      -                                        die(_("updating files failed"));
> >      +                                        }
> >      +                                        if (pathspec_matches) {
> >      +                                                if (data->include_ignored_submodules && data->include_ignored_submodules > 0) {
> >      +-                                                       trace_printf("Add ignored=all submodule due to --include_ignored_submodules: %s\n", path);
> >      ++                                                       trace_printf("Add submodule due to --include_ignored_submodules: %s\n", path);
> >      +                                                } else {
> >      +                                                        printf(_("Skipping submodule due to ignore=all: %s"), path);
> >      +                                                        printf(_("Use --include_ignored_submodules, if you really want to add them.") );
> >      +@@ read-cache.c: static void update_callback(struct diff_queue_struct *q,
> >      +                                                }
> >      +                                        } else {
> >      +                                                /* No explicit pathspec match -> skip silently (or with trace). */
> >      +-                                               trace_printf("pathspec does not match %s\n", path);
> >      ++                                               trace_printf("Pathspec to submodule does not match explicitly: %s\n", path);
> >      +                                                continue;
> >      +                                        }
> >      +                                }
> >      +@@ read-cache.c: static void update_callback(struct diff_queue_struct *q,
> >                                       data->add_errors++;
> >                               }
> >                               break;
> >  3:  8f3d5f7ec1 ! 3:  399a153b95 tests: add new t2206-add-submodule-ignored.sh to test ignore=all scenario
> >      @@ Commit message
> >           config with ignore=all also behaves as intended with configuration in
> >           .gitmodules and configuration given on the command line.
> >
> >      -    Testfile is added to meson.build for execution.
> >      +    The usage of --include_ignored_submodules is showcased and tested in the
> >      +    test suite.
> >      +
> >      +    The test file is added to meson.build for execution.
> >
> >           Signed-off-by: Claus Schneider(Eficode) <[email protected]>
> >
> >      @@ t/t2206-add-submodule-ignored.sh (new)
> >       +# This test covers the behavior of "git add", "git status" and "git log" when
> >       +# dealing with submodules that have the ignore=all setting in
> >       +# .gitmodules. It ensures that changes in such submodules are
> >      -+# ignored by default, but can be staged with "git add --force".
> >      ++# ignored by default, but can be staged with "git add --include-ignored-submodules".
> >       +
> >       +# shellcheck disable=SC1091
> >       +. ./test-lib.sh
> >      @@ t/t2206-add-submodule-ignored.sh (new)
> >       +'
> >       +
> >       +#6
> >      -+# check that 'git add --force .' does not stage the change in the submodule
> >      ++# check that 'git add --include-ignored-submodules .' does not stage the change in the submodule
> >       +# and that 'git status' does not show it as modified
> >      -+test_expect_success 'main: check --force add . and status'  '
> >      ++test_expect_success 'main: check --include-ignored-submodules add . and status'  '
> >       +       cd "${base_path}" &&
> >       +       cd main &&
> >      -+       GIT_TRACE=1 git add --force . &&
> >      ++       GIT_TRACE=1 git add --include-ignored-submodules . &&
> >       +       ! git status --porcelain | grep "^M  sub$" &&
> >       +       echo
> >       +'
> >      @@ t/t2206-add-submodule-ignored.sh (new)
> >       +'
> >       +
> >       +#8
> >      -+# check that 'git add --force sub' does stage the change in the submodule
> >      -+# check that 'git add --force ./sub/' does stage the change in the submodule
> >      ++# check that 'git add --include-ignored-submodules sub' does stage the change in the submodule
> >      ++# check that 'git add --include-ignored-submodules ./sub/' does stage the change in the submodule
> >       +# and that 'git status --porcelain' does show it as modified
> >       +# commit it..
> >       +# check that 'git log --ignore-submodules=none' shows the submodule change
> >      @@ t/t2206-add-submodule-ignored.sh (new)
> >       +test_expect_success 'main: check force add sub and ./sub/ and status'  '
> >       +       cd "${base_path}" &&
> >       +       cd main &&
> >      -+       echo "Adding with --force should work: git add --force sub" &&
> >      -+       GIT_TRACE=1 git add --force sub &&
> >      ++       echo "Adding with --include-ignored-submodules should work: git add --include-ignored-submodules sub" &&
> >      ++       GIT_TRACE=1 git add --include-ignored-submodules sub &&
> >       +       git status --porcelain | grep "^M  sub$" &&
> >       +       git restore --staged sub &&
> >       +       ! git status --porcelain | grep "^M  sub$" &&
> >      -+       echo "Adding with --force should work: git add --force ./sub/" &&
> >      -+       GIT_TRACE=1 git add --force ./sub/ &&
> >      ++       echo "Adding with --include-ignored-submodules should work: git add --include-ignored-submodules ./sub/" &&
> >      ++       GIT_TRACE=1 git add --include-ignored-submodules ./sub/ &&
> >       +       git status --porcelain | grep "^M  sub$" &&
> >       +       git commit -m "update submodule pointer" &&
> >       +       ! git status --porcelain | grep "^ M sub$" &&
> >  4:  58563a7b90 ! 4:  93c95954f1 tests: fix existing tests when add an ignore=all submodule
> >      @@ Metadata
> >        ## Commit message ##
> >           tests: fix existing tests when add an ignore=all submodule
> >
> >      -    There are tests that rely on "git add <submodule>" also adds it. A --force
> >      -    is needed with this enhancement hence they are added accordingly in these
> >      -    tests.
> >      +    There are tests that rely on "git add <submodule>" to add updates in the
> >      +    parent repository. A new option --include-ignored-submodules is introduced
> >      +    as it is now needed with this enhancement.
> >
> >           Updated tests:
> >           - t1013-read-tree-submodule.sh ( fixed in: t/lib-submodule-update.sh )
> >      +    - t2013-checkout-submodule.sh ( fixed in: t/lib-submodule-update.sh )
> >           - t7406-submodule-update.sh
> >           - t7508-status.sh
> >
> >      @@ t/lib-submodule-update.sh: create_lib_submodule_repo () {
> >                               git push origin modifications
> >                       ) &&
> >       -               git add sub1 &&
> >      -+               git add --force sub1 &&
> >      ++               git add --include-ignored-submodules sub1 &&
> >                       git commit -m "Modify sub1" &&
> >
> >                       git checkout -b add_nested_sub modify_sub1 &&
> >      @@ t/lib-submodule-update.sh: create_lib_submodule_repo () {
> >                       git -C sub1 submodule add --branch no_submodule ../submodule_update_sub2 sub2 &&
> >                       git -C sub1 commit -a -m "add a nested submodule" &&
> >       -               git add sub1 &&
> >      -+               git add --force sub1 &&
> >      ++               git add --include-ignored-submodules sub1 &&
> >                       git commit -a -m "update submodule, that updates a nested submodule" &&
> >                       git checkout -b modify_sub1_recursively &&
> >                       git -C sub1 checkout -b modify_sub1_recursively &&
> >      @@ t/lib-submodule-update.sh: create_lib_submodule_repo () {
> >                       git -C sub1 add sub2 &&
> >                       git -C sub1 commit -m "update nested sub" &&
> >       -               git add sub1 &&
> >      -+               git add --force sub1 &&
> >      ++               git add --include-ignored-submodules sub1 &&
> >                       git commit -m "update sub1, that updates nested sub" &&
> >                       git -C sub1 push origin modify_sub1_recursively &&
> >                       git -C sub1/sub2 push origin modify_sub1_recursively &&
> >      @@ t/t7508-status.sh: test_expect_success 'git commit will commit a staged but igno
> >        test_expect_success 'git commit --dry-run will show a staged but ignored submodule' '
> >               git reset HEAD^ &&
> >       -       git add sm &&
> >      -+       git add --force sm &&
> >      ++       git add --include-ignored-submodules sm &&
> >               cat >expect << EOF &&
> >        On branch main
> >        Your branch and '\''upstream'\'' have diverged,
> >  5:  416695f439 < -:  ---------- Documentation: update add --force and submodule ignore=all config
> >  -:  ---------- > 5:  ee84190cd8 Documentation: add --include_ignored_submodules + ignore=all config

[gitgitgadget]

There are issues in commit aca2c81:
tests: add new t2206-add-submodule-ignored : ignore=all and --force scenario
First line of commit message is too long (> 76 columns)
Lines in the body of the commit messages should be wrapped between 60 and 76 characters.
Indented lines, and lines without whitespace, are exempt

[gitgitgadget]

There are issues in commit aca2c81:
tests: add new t2206-add-submodule-ignored : ignore=all and --force scenario
First line of commit message is too long (> 76 columns)
Lines in the body of the commit messages should be wrapped between 60 and 76 characters.
Indented lines, and lines without whitespace, are exempt

[bicschneider]

/submit

[gitgitgadget]

Submitted as [email protected]

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1987/Praqma/respect-submodule-ignore-v3

To fetch this version to local tag pr-1987/Praqma/respect-submodule-ignore-v3:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1987/Praqma/respect-submodule-ignore-v3

[gitgitgadget]

Ben Knoble wrote on the Git mailing list (how to reply to this email):

> Le 14 janv. 2026 à 02:48, Claus Schneider(Eficode) via GitGitGadget <[email protected]> a écrit :
> 
> From: "Claus Schneider(Eficode)" <[email protected]>
> 
> - 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 protected]>
> ---
> 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
> 

[gitgitgadget]

User Ben Knoble <[email protected]> has been added to the cc: list.

[gitgitgadget]

"Kristoffer Haugsbakk" wrote on the Git mailing list (how to reply to this email):

On Wed, Jan 14, 2026, at 08:47, Claus Schneider(Eficode) via GitGitGadget wrote:
> From: "Claus Schneider(Eficode)" <[email protected]>
>
> Submodules configured with ignore=all are now skipped during add operations
> unless overridden by --force and the submodule path is explicitly specified.
>
> A message is printed (like ignored files) guiding the user to use the
> --force flag if the user has explicitely want to update the submodule
> reference.
>
> The reason for the change is support submodule branch tracking or
> similar and git status states nothing and git add should not add either
> as a default behaviour. The workflow is more logic and similar to regular
> ignored files even the submodule is already tracked.
>
> The change opens up a lot of possibilities for submodules to be used
> more freely and simular to the repo tool. A submodule can be added for many

s/simular/similar/ ? Although the sentence doesn’t quite make sense to
me. Well I’m unfamiliar with the domain anyway. ;)

> more reason and loosely coupled dependencies to the super repo which often

s/more reason/more reasons/ ?

> gives the friction of handle the explicit commits and updates without

s/handle/handling/

> the need for tracking the submodule sha1 by sha1.
>
> Signed-off-by: Claus Schneider(Eficode) <[email protected]>
> ---
>[snip]

[gitgitgadget]

User "Kristoffer Haugsbakk" <[email protected]> has been added to the cc: list.

[gitgitgadget]

This branch is now known as cs/add-skip-submodule-ignore-all.

[gitgitgadget]

This patch series was integrated into seen via git@c15ea74.