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