feat(submodule): add deinit method to Submodule (#2014)

Mirrors the pattern of `Submodule.add`, `Submodule.update`, and
`Submodule.remove` by exposing `git submodule deinit` as a first-class
method, so callers no longer need the `repo.git.submodule('deinit', ...)`
workaround noted in the issue.

The method delegates to `git submodule deinit [--force] -- <path>` via
`self.repo.git.submodule`, decorated with `@unbare_repo` to match the
other mutating Submodule methods. It unregisters the submodule from
`.git/config` and clears the working-tree directory while leaving
`.gitmodules` and `.git/modules/<name>` intact, so a later `update()`
can re-initialize.

Author: mvanhorn

git/objects/submodule/base.py

@@ -49,6 +49,7 @@
     Callable,
     Dict,
     Iterator,
+    List,
     Mapping,
     Sequence,
     TYPE_CHECKING,
@@ -1267,6 +1268,36 @@ def remove(
 
         return self
 
+    @unbare_repo
+    def deinit(self, force: bool = False) -> "Submodule":
+        """Run ``git submodule deinit`` on this submodule.
+
+        This is a thin wrapper around ``git submodule deinit <path>``, paralleling
+        :meth:`add`, :meth:`update`, and :meth:`remove`. It unregisters the
+        submodule (removes its entry from ``.git/config`` and empties the
+        working-tree directory) without deleting the submodule from
+        ``.gitmodules`` or its checked-out repository under ``.git/modules/``.
+        A subsequent :meth:`update` will re-initialize the submodule from the
+        retained contents.
+
+        :param force:
+            If ``True``, pass ``--force`` to ``git submodule deinit``. This
+            allows deinitialization even when the submodule's working tree has
+            local modifications that would otherwise block the command.
+
+        :return:
+            self
+
+        :note:
+            Doesn't work in bare repositories.
+        """
+        args: List[str] = []
+        if force:
+            args.append("--force")
+        args.extend(["--", str(self.path)])
+        self.repo.git.submodule("deinit", *args)
+        return self
+
     def set_parent_commit(self, commit: Union[Commit_ish, str, None], check: bool = True) -> "Submodule":
         """Set this instance to use the given commit whose tree is supposed to
         contain the ``.gitmodules`` blob.

test/test_submodule.py

@@ -718,6 +718,21 @@ def test_iter_items_from_invalid_hash(self):
             next(it)
         self.assertIsNone(ctx.exception.value)
 
+    @with_rw_directory
+    def test_deinit_calls_git_submodule(self, rwdir):
+        repo = git.Repo.init(rwdir)
+        submodule = Submodule(repo, b"\0" * 20, name="module", path="module")
+
+        with mock.patch.object(Git, "submodule", create=True) as git_submodule:
+            submodule.deinit()
+
+            git_submodule.assert_called_once_with("deinit", "--", submodule.path)
+            git_submodule.reset_mock()
+
+            submodule.deinit(force=True)
+
+            git_submodule.assert_called_once_with("deinit", "--force", "--", submodule.path)
+
     @with_rw_repo(k_no_subm_tag, bare=False)
     def test_first_submodule(self, rwrepo):
         assert len(list(rwrepo.iter_submodules())) == 0