Submodule.remove module parameter doc is unclear or incomplete

[EliahKagan]

The docstring for Submodule.remove documents the module parameter this way:

GitPython/git/objects/submodule/base.py

Lines 951 to 959 in 6f765a2

	:param module: If True, the module checkout we point to will be deleted
	as well. If the module is currently on a commit which is not part
	of any branch in the remote, if the currently checked out branch
	working tree, or untracked files,
	is ahead of its tracking branch, if you have modifications in the
	In case the removal of the repository fails for these reasons, the
	submodule status will not have been altered.
	If this submodule has child - modules on its own, these will be deleted
	prior to touching the own module.

A sentence trails off in "if you have modifications in the" and it appears material is missing. This should be revised, but it is is unclear exactly what the intended meaning is, so I don't know for sure how to fix it.

The current phrasing appears to be the effect of an unsuccessful or incomplete attempt, in 8e0e315, to fix a similar misphrasing. Compared to the original wording in 3d061a1, the change was:

         :param module: If True, the module we point to will be deleted 
             as well. If the module is currently on a commit which is not part 
             of any branch in the remote, if the currently checked out branch 
-            is ahead of its tracking branch,  if you have modifications in the
             working tree, or untracked files,
+            is ahead of its tracking branch,  if you have modifications in the
             In case the removal of the repository fails for these reasons, the 
             submodule status will not have been altered.
             If this submodule has child-modules on its own, these will be deleted

So the original wording also trailed off in mid-sentence, but differently, with "working tree, or untracked files,".

I can guess the intended meaning:

If True, the module checkout we point to will be deleted as well. If the module is currently on a commit which is not part of any branch in the remote, if the currently checked out branch is ahead of its tracking branch, or if there are modifications to the working tree or untracked files, then the removal will fail.

If that revision is correct, it could be clarified by a small amount of further rewording:

If True, the checked out module we point to will be deleted as well. If that module is currently on a commit outside any branch in the remote, or if it is ahead of its tracking branch, or if there are modified or untracked files in its working tree, then the removal will fail.

However, I am not sure enough that this is the intended meaning to have put either of those changes in a PR at this time.

[Byron]

Thanks for bringing this up.

I am also not sure and I suppose the tests or the code itself could reveal more of the story. In the meantime, I think it's OK to go with the second version of the proposed correction as seemingly correct seems better than incomplete and nonsensical.

The submodule implementation is another wart of the project, unfortunately, as it's a half-baked attempt to improve git submodules which has many, many issues.

[EliahKagan]

In the meantime, I think it's OK to go with the second version

Sounds good. I've done this in #1714.