Documentation/git-rm.txt

   1 git-rm(1)
   2 =========
   3
   4 NAME
   5 ----
   6 git-rm - Remove files from the working tree and from the index
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]
  12           [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]]
  13           [--] [<pathspec>...]
  14
  15 DESCRIPTION
  16 -----------
  17 Remove files matching pathspec from the index, or from the working tree
  18 and the index. `git rm` will not remove a file from just your working
  19 directory. (There is no option to remove a file only from the working
  20 tree and yet keep it in the index; use `/bin/rm` if you want to do
  21 that.) The files being removed have to be identical to the tip of the
  22 branch, and no updates to their contents can be staged in the index,
  23 though that default behavior can be overridden with the `-f` option.
  24 When `--cached` is given, the staged content has to
  25 match either the tip of the branch or the file on disk,
  26 allowing the file to be removed from just the index.
  27
  28
  29 OPTIONS
  30 -------
  31 <pathspec>...::
  32         Files to remove.  A leading directory name (e.g. `dir` to remove
  33         `dir/file1` and `dir/file2`) can be given to remove all files in
  34         the directory, and recursively all sub-directories, but this
  35         requires the `-r` option to be explicitly given.
  36 +
  37 The command removes only the paths that are known to Git.
  38 +
  39 File globbing matches across directory boundaries.  Thus, given two
  40 directories `d` and `d2`, there is a difference between using
  41 `git rm 'd*'` and `git rm 'd/*'`, as the former will also remove all
  42 of directory `d2`.
  43 +
  44 For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
  45
  46 -f::
  47 --force::
  48         Override the up-to-date check.
  49
  50 -n::
  51 --dry-run::
  52         Don't actually remove any file(s).  Instead, just show
  53         if they exist in the index and would otherwise be removed
  54         by the command.
  55
  56 -r::
  57         Allow recursive removal when a leading directory name is
  58         given.
  59
  60 \--::
  61         This option can be used to separate command-line options from
  62         the list of files, (useful when filenames might be mistaken
  63         for command-line options).
  64
  65 --cached::
  66         Use this option to unstage and remove paths only from the index.
  67         Working tree files, whether modified or not, will be
  68         left alone.
  69
  70 --ignore-unmatch::
  71         Exit with a zero status even if no files matched.
  72
  73 -q::
  74 --quiet::
  75         `git rm` normally outputs one line (in the form of an `rm` command)
  76         for each file removed. This option suppresses that output.
  77
  78 --pathspec-from-file=<file>::
  79         Pathspec is passed in `<file>` instead of commandline args. If
  80         `<file>` is exactly `-` then standard input is used. Pathspec
  81         elements are separated by LF or CR/LF. Pathspec elements can be
  82         quoted as explained for the configuration variable `core.quotePath`
  83         (see linkgit:git-config[1]). See also `--pathspec-file-nul` and
  84         global `--literal-pathspecs`.
  85
  86 --pathspec-file-nul::
  87         Only meaningful with `--pathspec-from-file`. Pathspec elements are
  88         separated with NUL character and all other characters are taken
  89         literally (including newlines and quotes).
  90
  91
  92 REMOVING FILES THAT HAVE DISAPPEARED FROM THE FILESYSTEM
  93 --------------------------------------------------------
  94 There is no option for `git rm` to remove from the index only
  95 the paths that have disappeared from the filesystem. However,
  96 depending on the use case, there are several ways that can be
  97 done.
  98
  99 Using ``git commit -a''
 100 ~~~~~~~~~~~~~~~~~~~~~~~
 101 If you intend that your next commit should record all modifications
 102 of tracked files in the working tree and record all removals of
 103 files that have been removed from the working tree with `rm`
 104 (as opposed to `git rm`), use `git commit -a`, as it will
 105 automatically notice and record all removals.  You can also have a
 106 similar effect without committing by using `git add -u`.
 107
 108 Using ``git add -A''
 109 ~~~~~~~~~~~~~~~~~~~~
 110 When accepting a new code drop for a vendor branch, you probably
 111 want to record both the removal of paths and additions of new paths
 112 as well as modifications of existing paths.
 113
 114 Typically you would first remove all tracked files from the working
 115 tree using this command:
 116
 117 ----------------
 118 git ls-files -z | xargs -0 rm -f
 119 ----------------
 120
 121 and then untar the new code in the working tree. Alternately
 122 you could 'rsync' the changes into the working tree.
 123
 124 After that, the easiest way to record all removals, additions, and
 125 modifications in the working tree is:
 126
 127 ----------------
 128 git add -A
 129 ----------------
 130
 131 See linkgit:git-add[1].
 132
 133 Other ways
 134 ~~~~~~~~~~
 135 If all you really want to do is to remove from the index the files
 136 that are no longer present in the working tree (perhaps because
 137 your working tree is dirty so that you cannot use `git commit -a`),
 138 use the following command:
 139
 140 ----------------
 141 git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached
 142 ----------------
 143
 144 SUBMODULES
 145 ----------
 146 Only submodules using a gitfile (which means they were cloned
 147 with a Git version 1.7.8 or newer) will be removed from the work
 148 tree, as their repository lives inside the .git directory of the
 149 superproject. If a submodule (or one of those nested inside it)
 150 still uses a .git directory, `git rm` will move the submodules
 151 git directory into the superprojects git directory to protect
 152 the submodule's history. If it exists the submodule.<name> section
 153 in the linkgit:gitmodules[5] file will also be removed and that file
 154 will be staged (unless --cached or -n are used).
 155
 156 A submodule is considered up to date when the HEAD is the same as
 157 recorded in the index, no tracked files are modified and no untracked
 158 files that aren't ignored are present in the submodules work tree.
 159 Ignored files are deemed expendable and won't stop a submodule's work
 160 tree from being removed.
 161
 162 If you only want to remove the local checkout of a submodule from your
 163 work tree without committing the removal, use linkgit:git-submodule[1] `deinit`
 164 instead. Also see linkgit:gitsubmodules[7] for details on submodule removal.
 165
 166 EXAMPLES
 167 --------
 168 `git rm Documentation/\*.txt`::
 169         Removes all `*.txt` files from the index that are under the
 170         `Documentation` directory and any of its subdirectories.
 171 +
 172 Note that the asterisk `*` is quoted from the shell in this
 173 example; this lets Git, and not the shell, expand the pathnames
 174 of files and subdirectories under the `Documentation/` directory.
 175
 176 `git rm -f git-*.sh`::
 177         Because this example lets the shell expand the asterisk
 178         (i.e. you are listing the files explicitly), it
 179         does not remove `subdir/git-foo.sh`.
 180
 181 BUGS
 182 ----
 183 Each time a superproject update removes a populated submodule
 184 (e.g. when switching between commits before and after the removal) a
 185 stale submodule checkout will remain in the old location. Removing the
 186 old directory is only safe when it uses a gitfile, as otherwise the
 187 history of the submodule will be deleted too. This step will be
 188 obsolete when recursive submodule update has been implemented.
 189
 190 SEE ALSO
 191 --------
 192 linkgit:git-add[1]
 193
 194 GIT
 195 ---
 196 Part of the linkgit:git[1] suite