-------
<file>...::
Files to remove. Fileglobs (e.g. `*.c`) can be given to
- remove all matching files. If you want git to expand
+ remove all matching files. If you want Git to expand
file glob characters, you may need to shell-escape them.
A leading directory name
(e.g. `dir` to remove `dir/file1` and `dir/file2`) can be
The <file> list given to the command can be exact pathnames,
file glob patterns, or leading directory names. The command
-removes only the paths that are known to git. Giving the name of
-a file that you have not told git about does not remove that file.
+removes only the paths that are known to Git. Giving the name of
+a file that you have not told Git about does not remove that file.
File globbing matches across directory boundaries. Thus, given
two directories `d` and `d2`, there is a difference between
git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached
----------------
-Submodules
-~~~~~~~~~~
+SUBMODULES
+----------
Only submodules using a gitfile (which means they were cloned
-with a git version 1.7.8 or newer) will be removed from the work
+with a Git version 1.7.8 or newer) will be removed from the work
tree, as their repository lives inside the .git directory of the
superproject. If a submodule (or one of those nested inside it)
-still uses a .git directory, `git rm` will fail - no matter if forced
-or not - to protect the submodule's history.
+still uses a .git directory, `git rm` will move the submodules
+git directory into the superprojects git directory to protect
+the submodule's history. If it exists the submodule.<name> section
+in the linkgit:gitmodules[5] file will also be removed and that file
+will be staged (unless --cached or -n are used).
-A submodule is considered up-to-date when the HEAD is the same as
+A submodule is considered up to date when the HEAD is the same as
recorded in the index, no tracked files are modified and no untracked
files that aren't ignored are present in the submodules work tree.
Ignored files are deemed expendable and won't stop a submodule's work
tree from being removed.
+If you only want to remove the local checkout of a submodule from your
+work tree without committing the removal, use linkgit:git-submodule[1] `deinit`
+instead. Also see linkgit:gitsubmodules[7] for details on submodule removal.
+
EXAMPLES
--------
`git rm Documentation/\*.txt`::
`Documentation` directory and any of its subdirectories.
+
Note that the asterisk `*` is quoted from the shell in this
-example; this lets git, and not the shell, expand the pathnames
+example; this lets Git, and not the shell, expand the pathnames
of files and subdirectories under the `Documentation/` directory.
`git rm -f git-*.sh`::
(i.e. you are listing the files explicitly), it
does not remove `subdir/git-foo.sh`.
+BUGS
+----
+Each time a superproject update removes a populated submodule
+(e.g. when switching between commits before and after the removal) a
+stale submodule checkout will remain in the old location. Removing the
+old directory is only safe when it uses a gitfile, as otherwise the
+history of the submodule will be deleted too. This step will be
+obsolete when recursive submodule update has been implemented.
+
SEE ALSO
--------
linkgit:git-add[1]