git-delete-submodule

Delete a specific submodule

$ git delete-submodule [path/to/submodule]

git delete-submodule <submodule_path>

<submodule_path>
    The path to the submodule's directory within the main repository. This path should match how the submodule was originally added or how it appears in your .gitmodules file.

Removing a Git submodule manually involves a series of distinct steps: editing the .gitmodules file, removing the corresponding entry from the main repository's .git/config, ensuring the submodule's files are removed from the working directory and the Git index, and finally, committing these changes. This multi-step process can be cumbersome and prone to errors, potentially leaving behind orphaned files or inconsistent repository states.

The git-delete-submodule command automates this entire procedure, streamlining the removal of a submodule. It systematically updates the configuration files, removes the submodule's directory, and stages all necessary changes for commit. This command significantly simplifies submodule management, making the process less error-prone and more efficient for developers working with complex Git repositories.

git-delete-submodule is generally not a built-in Git command; it's commonly provided by external tools like git-extras. Therefore, its availability depends on whether such a utility package is installed on your system. Always verify its presence before attempting to use it. As this command makes permanent modifications to your repository's configuration and working directory, it is strongly advised to commit any outstanding changes or create a backup of your repository before execution to prevent unintended data loss or an unrecoverable state. While it cleans up references and the working directory, it typically does not prune the Git object database of the submodule's history; for that, further commands like git gc --prune=now might be necessary if disk space is a concern.

Before the advent of helpers like git-delete-submodule, users had to manually perform the following steps to remove a submodule:
1. Remove the submodule's entry from the .gitmodules file.
2. Remove the submodule's section from the .git/config file in the main repository.
3. Delete the submodule's directory from the working tree (e.g., using rm -rf <submodule_path>).
4. Unstage the submodule's directory from the index (e.g., git rm --cached <submodule_path>).
5. Stage and commit all these changes.
git-delete-submodule automates these often intricate and sequential steps, significantly reducing the potential for error and improving efficiency.

The git-delete-submodule command is not part of the core Git distribution. Its existence stems from the community's need for a more straightforward and automated way to manage submodule removal, a process that traditionally involves several manual steps across different Git commands and configuration files. It gained significant traction as a popular utility script, notably being included in community-driven projects like git-extras, which extends Git's capabilities with many useful, non-core functionalities. This command addresses a long-standing user experience challenge by simplifying a complex aspect of repository maintenance.

git-submodule(1), git-rm(1), git-config(1)