review

- Add tests
- [P2] Disable lazy fetching during no-fetch updates — git/objects/submodule/base.py:865-866
  For a partial-cloned submodule (for example, using `--filter=blob:none`), the
  target commit can be cached while its blobs are missing. Skipping `Remote.fetch`
  does not prevent the later checkout/reset from implicitly fetching those blobs.
  I reproduced `update(no_fetch=True)` spawning `git fetch origin ... --stdin`
  despite this guard. This violates the documented local-only behavior. Disable
  Git's lazy fetching for commands executed in this mode, including checkout and
  restoration.
- [P2] Propagate no_fetch to recursive root-module updates — git/objects/submodule/root.py:442-442
  For repositories with nested submodules,
  `Repo.submodule_update(no_fetch=True)` still fetches nested remotes. The flag
  reaches this immediate `sm.update(recursive=False, ...)`, but the subsequent
  `type(self)(sm.module()).update(...)` call omits it and defaults to `False`.
  Since root updates recurse by default, offline updates fail even when all
  required objects are cached. Forward the flag to the recursive call too.

- [P2] Skip the branch-change fetch loop when no_fetch is set — git/objects/submodule/root.py:90-90
  When `.gitmodules` changes a submodule's configured branch, the branch-change
  handler still unconditionally calls `remote.fetch(...)` for every remote.
  Consequently, even `submodule_update(recursive=False, no_fetch=True)` accesses
  remotes and fails offline, including when the target remote-tracking branch
  already exists locally. Guard that fetch loop with this flag as well.

- [P2] Handle URL changes without requiring freshly fetched refs — git/objects/submodule/root.py:282-283
  When a submodule's URL changes with `no_fetch=True`, the newly created
  `__new_origin__` remote has no refs, so the following `smr.refs` branch check
  raises `ValueError`. This occurs even when switching to an identical mirror with
  all required history cached locally, and leaves the temporary remote behind. The
  no-fetch path must handle the fetch-dependent validation and remote replacement,
  not merely skip this fetch.

- [P2] Allow restoring retained repositories without fetching — git/objects/submodule/base.py:893-896
  After `git submodule deinit`, the retained repository under
`.git/modules/<name>` can already contain the requested commit. This branch has
  validated that repository but now rejects `update(init=True, no_fetch=True)`
  merely because its checkout is empty. Reconnecting the repository and restoring
  cached contents requires no network access; native `git submodule update --init
  --no-fetch` succeeds in this case. Allow restoration and conditionally skip the
  later `fetch_remotes(mrepo)` instead.

Assisted-by: GPT 6.0
Co-authored-by: GPT 6.0 <codex@openai.com>

Author: Byron

git/objects/submodule/base.py

@@ -4,17 +4,32 @@
 __all__ = ["Submodule", "UpdateProgress"]
 
 import gc
-from io import BytesIO
 import logging
 import ntpath
 import os
 import os.path as osp
-from pathlib import Path
 import shlex
 import stat
 import sys
-import uuid
 import urllib.parse
+import uuid
+from io import BytesIO
+from pathlib import Path
+
+# typing ----------------------------------------------------------------------
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    Iterator,
+    List,
+    Literal,
+    Mapping,
+    Sequence,
+    Union,
+    cast,
+)
 
 import git
 from git.cmd import Git
@@ -46,23 +61,7 @@
     sm_section,
 )
 
-# typing ----------------------------------------------------------------------
-
-from typing import (
-    Any,
-    Callable,
-    Dict,
-    Iterator,
-    List,
-    Literal,
-    Mapping,
-    Sequence,
-    TYPE_CHECKING,
-    Union,
-    cast,
-)
-
-from git.types import Commit_ish, PathLike, TBD
+from git.types import TBD, Commit_ish, PathLike
 
 if TYPE_CHECKING:
     from git.index import IndexFile
@@ -793,8 +792,9 @@ def update(
             Allow unsafe options to be used, like ``--upload-pack``.
 
         :param no_fetch:
-            If ``True``, submodule updating will be attempted without fetching
-            new changes from remotes.
+            If ``True``, update using locally available objects and remote-tracking
+            refs without fetching or cloning. Repositories retained after
+            :meth:`deinit` can be restored without fetching.
 
         :note:
             Does nothing in bare repositories.
@@ -886,15 +886,12 @@ def fetch_remotes(module_repo: "Repo") -> None:
                             raise OSError(
                                 "Module directory at %r does already exist and is non-empty" % checkout_module_abspath
                             )
-                        elif no_fetch:
-                            raise ValueError(
-                                "Module directory at %r is empty but fetching is disabled" % checkout_module_abspath
-                            )
                         os.makedirs(checkout_module_abspath, exist_ok=True)
                         self._write_git_file_and_module_config(checkout_module_abspath, module_abspath)
                         mrepo = git.Repo(checkout_module_abspath)
                         mrepo.head.reset(mrepo.head.commit, index=True, working_tree=True)
-                        fetch_remotes(mrepo)
+                        if not no_fetch:
+                            fetch_remotes(mrepo)
                         with self.repo.config_writer() as writer:
                             writer.set_value(sm_section(self.name), "url", self.url)
 

git/objects/submodule/root.py

@@ -5,19 +5,17 @@
 
 import logging
 
+# typing -------------------------------------------------------------------
+from typing import TYPE_CHECKING, Union
+
 import git
 from git.exc import InvalidGitRepositoryError
+from git.types import Commit_ish
 from git.util import IterableList
 
 from .base import Submodule, UpdateProgress
 from .util import find_first_remote_branch
 
-# typing -------------------------------------------------------------------
-
-from typing import TYPE_CHECKING, Union
-
-from git.types import Commit_ish
-
 if TYPE_CHECKING:
     from git.repo import Repo
 
@@ -148,8 +146,9 @@ def update(  # type: ignore[override]
             when updating submodules.
 
         :param no_fetch:
-            If ``True``, submodule updating will be attempted without fetching
-            new changes from remotes.
+            If ``True``, update using locally available objects and remote-tracking
+            refs without fetching or cloning. Cached refs are preserved and used even
+            when a submodule's URL changes.
 
         :return:
             self
@@ -259,7 +258,7 @@ def update(  # type: ignore[override]
                     # HANDLE URL CHANGE
                     ###################
                     if sm.url != psm.url:
-                        # Add the new remote, remove the old one.
+                        # When fetching, add the new remote and remove the old one.
                         # This way, if the url just changes, the commits will not have
                         # to be re-retrieved.
                         nn = "__new_origin__"
@@ -277,34 +276,19 @@ def update(  # type: ignore[override]
                             )
 
                             if not dry_run:
-                                assert nn not in [r.name for r in rmts]
-                                smr = smm.create_remote(nn, sm.url)
-                                if not no_fetch:
-                                    smr.fetch(progress=progress)
-
-                                # If we have a tracking branch, it should be available
-                                # in the new remote as well.
-                                if len([r for r in smr.refs if r.remote_head == sm.branch_name]) == 0:
-                                    raise ValueError(
-                                        "Submodule branch named %r was not available in new submodule remote at %r"
-                                        % (sm.branch_name, sm.url)
-                                    )
-                                # END head is not detached
-
-                                # Now delete the changed one.
-                                rmt_for_deletion = None
+                                previous_remote = None
                                 for remote in rmts:
                                     if remote.url == psm.url:
-                                        rmt_for_deletion = remote
+                                        previous_remote = remote
                                         break
                                     # END if urls match
                                 # END for each remote
 
                                 # If we didn't find a matching remote, but have exactly
                                 # one, we can safely use this one.
-                                if rmt_for_deletion is None:
+                                if previous_remote is None:
                                     if len(rmts) == 1:
-                                        rmt_for_deletion = rmts[0]
+                                        previous_remote = rmts[0]
                                     else:
                                         # If we have not found any remote with the
                                         # original URL we may not have a name. This is a
@@ -317,45 +301,64 @@ def update(  # type: ignore[override]
                                     # END handle one single remote
                                 # END handle check we found a remote
 
-                                orig_name = rmt_for_deletion.name
-                                smm.delete_remote(rmt_for_deletion)
-                                # NOTE: Currently we leave tags from the deleted remotes
-                                # as well as separate tracking branches in the possibly
-                                # totally changed repository (someone could have changed
-                                # the url to another project). At some point, one might
-                                # want to clean it up, but the danger is high to remove
-                                # stuff the user has added explicitly.
-
-                                # Rename the new remote back to what it was.
-                                smr.rename(orig_name)
-
-                                # Early on, we verified that the our current tracking
-                                # branch exists in the remote. Now we have to ensure
-                                # that the sha we point to is still contained in the new
-                                # remote tracking branch.
-                                smsha = sm.binsha
-                                found = False
-                                rref = smr.refs[self.branch_name]
-                                for c in rref.commit.traverse():
-                                    if c.binsha == smsha:
-                                        found = True
-                                        break
-                                    # END traverse all commits in search for sha
-                                # END for each commit
-
-                                if not found:
-                                    # Adjust our internal binsha to use the one of the
-                                    # remote this way, it will be checked out in the
-                                    # next step. This will change the submodule relative
-                                    # to us, so the user will be able to commit the
-                                    # change easily.
-                                    _logger.warning(
-                                        "Current sha %s was not contained in the tracking\
+                                if no_fetch:
+                                    # A new remote would have no cached refs. Preserve
+                                    # the existing refs and tracking configuration for
+                                    # offline updates instead of replacing the remote.
+                                    previous_remote.set_url(git.Git.polish_url(sm.url, expand_vars=False))
+                                else:
+                                    assert nn not in [r.name for r in rmts]
+                                    smr = smm.create_remote(nn, sm.url)
+                                    smr.fetch(progress=progress)
+
+                                    # If we have a tracking branch, it should be available
+                                    # in the new remote as well.
+                                    if len([r for r in smr.refs if r.remote_head == sm.branch_name]) == 0:
+                                        raise ValueError(
+                                            "Submodule branch named %r was not available in new submodule remote at %r"
+                                            % (sm.branch_name, sm.url)
+                                        )
+                                    # END head is not detached
+
+                                    orig_name = previous_remote.name
+                                    smm.delete_remote(previous_remote)
+                                    # NOTE: Currently we leave tags from the deleted remotes
+                                    # as well as separate tracking branches in the possibly
+                                    # totally changed repository (someone could have changed
+                                    # the url to another project). At some point, one might
+                                    # want to clean it up, but the danger is high to remove
+                                    # stuff the user has added explicitly.
+
+                                    # Rename the new remote back to what it was.
+                                    smr.rename(orig_name)
+
+                                    # Early on, we verified that the our current tracking
+                                    # branch exists in the remote. Now we have to ensure
+                                    # that the sha we point to is still contained in the new
+                                    # remote tracking branch.
+                                    smsha = sm.binsha
+                                    found = False
+                                    rref = smr.refs[self.branch_name]
+                                    for c in rref.commit.traverse():
+                                        if c.binsha == smsha:
+                                            found = True
+                                            break
+                                        # END traverse all commits in search for sha
+                                    # END for each commit
+
+                                    if not found:
+                                        # Adjust our internal binsha to use the one of the
+                                        # remote this way, it will be checked out in the
+                                        # next step. This will change the submodule relative
+                                        # to us, so the user will be able to commit the
+                                        # change easily.
+                                        _logger.warning(
+                                            "Current sha %s was not contained in the tracking\
              branch at the new remote, setting it the the remote's tracking branch",
-                                        sm.hexsha,
-                                    )
-                                    sm.binsha = rref.commit.binsha
-                                # END reset binsha
+                                            sm.hexsha,
+                                        )
+                                        sm.binsha = rref.commit.binsha
+                                    # END reset binsha
 
                                 # NOTE: All checkout is performed by the base
                                 # implementation of update.
@@ -385,11 +388,12 @@ def update(  # type: ignore[override]
                         if not dry_run:
                             smm = sm.module()
                             smmr = smm.remotes
-                            # As the branch might not exist yet, we will have to fetch
-                            # all remotes to be sure...
-                            for remote in smmr:
-                                remote.fetch(progress=progress)
-                            # END for each remote
+                            # As the branch might not exist yet, fetch all remotes
+                            # unless restricted to locally cached refs.
+                            if not no_fetch:
+                                for remote in smmr:
+                                    remote.fetch(progress=progress)
+                                # END for each remote
 
                             try:
                                 tbr = git.Head.create(
@@ -458,6 +462,7 @@ def update(  # type: ignore[override]
                         dry_run=dry_run,
                         force_reset=force_reset,
                         keep_going=keep_going,
+                        no_fetch=no_fetch,
                     )
                 # END handle dry_run
             # END handle recursive