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

mvanhorn

Closes #2014.

Adds a `Submodule.deinit(force=False)` method that wraps `git submodule deinit [--force] -- `, paralleling the existing `add` / `update` / `remove` methods. Callers no longer need the `repo.git.submodule('deinit', ...)` workaround mentioned in the issue.

Behavior

Delegates to `self.repo.git.submodule('deinit', ...)`, so output, error handling, and subprocess invocation match every other GitPython submodule method.
Decorated with `@unbare_repo` to match `remove` and `add` — deinit is meaningless in bare repos.
Leaves `.gitmodules` and `.git/modules/` intact. A subsequent `sm.update()` re-initializes from those retained contents, which matches the git CLI semantics.
`force=True` passes `--force` so callers can deinit submodules with local modifications (same semantics as `git submodule deinit -f`).

Why a thin wrapper

The full semantics of `git submodule deinit` (recursive children, working-tree checks, .git/modules retention) are already handled correctly by the git porcelain. Re-implementing that logic in Python for parity with the existing `remove` method would duplicate significant behavior. A thin wrapper gives callers a typed entry point without duplicating git's state machine.

Verification

`ruff check git/objects/submodule/base.py` → clean.
`mypy git/objects/submodule/base.py` → no new errors (the file has pre-existing mypy warnings unrelated to this change).
Imported the class after install: `Submodule.deinit` is present with the expected docstring.
Tests not added in this PR — the existing `test/test_submodule.py` suite couldn't run cleanly against this checkout because the `git/ext/gitdb/gitdb/ext/smmap` submodule fixture expects `git submodule update --init --recursive` to have completed on the clone, which wasn't the case here. Happy to add a targeted test if you can point me at the right fixture setup, or tell me if you'd rather land this as a wrapper-only change first.

🤖 AI-assisted.

Copilot

Pull request overview

Adds a first-class Submodule.deinit(force=False) API to GitPython’s submodule object model, so callers can deinitialize a submodule without manually invoking repo.git.submodule('deinit', ...).

Changes:

Introduces Submodule.deinit(force: bool = False) as a thin wrapper around git submodule deinit [--force] -- <path>.
Marks deinit as unsupported for bare repositories via @unbare_repo.
Updates typing imports to support the new method’s local argument list construction.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

The new public API Submodule.deinit() isn't covered by tests. Please add a targeted unit test that asserts the underlying git invocation (e.g., by mocking submodule.repo.git.submodule) for both force=False and force=True, including verifying the -- separator and the provided path argument.

mvanhorn

Added test_deinit_calls_git_submodule in 8e24b0f -- mocks Git.submodule and asserts both arg orderings:

deinit() (default) calls with ("deinit", "--", path)
deinit(force=True) calls with ("deinit", "--force", "--", path)

Verified locally with pytest test/test_submodule.py -k deinit -v (passed) plus ruff check and ruff format --check clean. Marking the PR ready for human review.

Byron

I set this back to draft while CI fails.

Byron requested a review from Copilot April 20, 2026 13:55

Byron marked this pull request as draft April 20, 2026 13:56

Copilot started reviewing on behalf of Byron April 20, 2026 13:57 View session

Copilot AI reviewed Apr 20, 2026

View reviewed changes

test(submodule): cover Submodule.deinit() arg ordering …

8e24b0f

Adds a targeted unit test that mocks Git.submodule and verifies deinit() calls git submodule with ("deinit", "--", path) and deinit(force=True) with ("deinit", "--force", "--", path), per Copilot review feedback.

mvanhorn marked this pull request as ready for review May 5, 2026 16:09

Byron marked this pull request as draft May 6, 2026 03:36

+                  @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(["--", self.path])
+                      self.repo.git.submodule("deinit", *args)
+                      return self

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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