Submodule.remove module parameter doc is unclear or incomplete · Issue #1712 · gitpython-developers/GitPython (original) (raw)
The docstring for Submodule.remove documents the module parameter this way:
| :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.