| 1 | git-reset(1) |
| 2 | ============ |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-reset - Set `HEAD` or the index to a known state |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | [synopsis] |
| 11 | git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>] |
| 12 | git reset [-q] [<tree-ish>] [--] <pathspec>... |
| 13 | git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>] |
| 14 | git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...] |
| 15 | |
| 16 | DESCRIPTION |
| 17 | ----------- |
| 18 | `git reset` does either of the following: |
| 19 | |
| 20 | 1. `git reset [<mode>] <commit>` changes which commit `HEAD` points to. This |
| 21 | makes it possible to undo various Git operations, for example commit, merge, |
| 22 | rebase, and pull. |
| 23 | 2. When you specify files or directories or pass `--patch`, `git reset` updates |
| 24 | the staged version of the specified files. |
| 25 | |
| 26 | `git reset [<mode>] [<commit>]`:: |
| 27 | Set the current branch head (`HEAD`) to point at _<commit>_. |
| 28 | Depending on _<mode>_, also update the working directory and/or index |
| 29 | to match the contents of _<commit>_. |
| 30 | _<commit>_ defaults to `HEAD`. |
| 31 | Before the operation, `ORIG_HEAD` is set to the tip of the current branch. |
| 32 | + |
| 33 | The _<mode>_ must be one of the following (default `--mixed`): |
| 34 | + |
| 35 | |
| 36 | -- |
| 37 | `--mixed`:: |
| 38 | Leave your working directory unchanged. |
| 39 | Update the index to match the new `HEAD`, so nothing will be staged. |
| 40 | + |
| 41 | If `-N` is specified, mark removed paths as intent-to-add (see |
| 42 | linkgit:git-add[1]). |
| 43 | |
| 44 | `--soft`:: |
| 45 | Leave your working tree files and the index unchanged. |
| 46 | For example, if you have no staged changes, you can use |
| 47 | `git reset --soft HEAD~5; git commit` |
| 48 | to combine the last 5 commits into 1 commit. This works even with |
| 49 | changes in the working tree, which are left untouched, but such usage |
| 50 | can lead to confusion. |
| 51 | |
| 52 | `--hard`:: |
| 53 | Overwrite all files and directories with the version from _<commit>_, |
| 54 | and may overwrite untracked files. Tracked files not in _<commit>_ are |
| 55 | removed so that the working tree matches _<commit>_. |
| 56 | Update the index to match the new `HEAD`, so nothing will be staged. |
| 57 | |
| 58 | `--merge`:: |
| 59 | Reset the index and update the files in the working tree that are |
| 60 | different between _<commit>_ and `HEAD`, but keep those which are |
| 61 | different between the index and working tree (i.e. which have changes |
| 62 | which have not been added). |
| 63 | Mainly exists to reset unmerged index entries, like those left behind by |
| 64 | `git am -3` or `git switch -m` in certain situations. |
| 65 | If a file that is different between _<commit>_ and the index has |
| 66 | unstaged changes, reset is aborted. |
| 67 | |
| 68 | `--keep`:: |
| 69 | Resets index entries and updates files in the working tree that are |
| 70 | different between _<commit>_ and `HEAD`. |
| 71 | If a file that is different between _<commit>_ and `HEAD` has local |
| 72 | changes, reset is aborted. |
| 73 | |
| 74 | `--recurse-submodules`:: |
| 75 | `--no-recurse-submodules`:: |
| 76 | When the working tree is updated, using `--recurse-submodules` will |
| 77 | also recursively reset the working tree of all active submodules |
| 78 | according to the commit recorded in the superproject, also setting |
| 79 | the submodules' `HEAD` to be detached at that commit. |
| 80 | -- |
| 81 | |
| 82 | `git reset [-q] [<tree-ish>] [--] <pathspec>...`:: |
| 83 | `git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`:: |
| 84 | For all specified files or directories, set the staged version to |
| 85 | the version from the given commit or tree (which defaults to `HEAD`). |
| 86 | + |
| 87 | This means that `git reset <pathspec>` is the opposite of `git add |
| 88 | <pathspec>`: it unstages all changes to the specified file(s) or |
| 89 | directories. This is equivalent to `git restore --staged <pathspec>...`. |
| 90 | + |
| 91 | In this mode, `git reset` updates only the index (without updating the `HEAD` or |
| 92 | working tree files). If you want to update the files as well as the index |
| 93 | entries, use linkgit:git-restore[1]. |
| 94 | |
| 95 | `git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`:: |
| 96 | Interactively select changes from the difference between the index |
| 97 | and the specified commit or tree (which defaults to `HEAD`). |
| 98 | The index is modified using the chosen changes. |
| 99 | + |
| 100 | This means that `git reset -p` is the opposite of `git add -p`, i.e. |
| 101 | you can use it to selectively unstage changes. See the "Interactive Mode" |
| 102 | section of linkgit:git-add[1] to learn how to use the `--patch` option. |
| 103 | |
| 104 | See "Reset, restore and revert" in linkgit:git[1] for the differences |
| 105 | between the three commands. |
| 106 | |
| 107 | |
| 108 | OPTIONS |
| 109 | ------- |
| 110 | |
| 111 | `-q`:: |
| 112 | `--quiet`:: |
| 113 | Be quiet, only report errors. |
| 114 | |
| 115 | `--refresh`:: |
| 116 | `--no-refresh`:: |
| 117 | Refresh the index after a mixed reset. Enabled by default. |
| 118 | |
| 119 | `--pathspec-from-file=<file>`:: |
| 120 | Pathspec is passed in _<file>_ instead of commandline args. If |
| 121 | _<file>_ is exactly `-` then standard input is used. Pathspec |
| 122 | elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be |
| 123 | quoted as explained for the configuration variable `core.quotePath` |
| 124 | (see linkgit:git-config[1]). See also `--pathspec-file-nul` and |
| 125 | global `--literal-pathspecs`. |
| 126 | |
| 127 | `--pathspec-file-nul`:: |
| 128 | Only meaningful with `--pathspec-from-file`. Pathspec elements are |
| 129 | separated with _NUL_ character and all other characters are taken |
| 130 | literally (including newlines and quotes). |
| 131 | |
| 132 | include::diff-context-options.adoc[] |
| 133 | |
| 134 | `--`:: |
| 135 | Do not interpret any more arguments as options. |
| 136 | |
| 137 | `<pathspec>...`:: |
| 138 | Limits the paths affected by the operation. |
| 139 | + |
| 140 | For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. |
| 141 | |
| 142 | EXAMPLES |
| 143 | -------- |
| 144 | |
| 145 | Undo add:: |
| 146 | + |
| 147 | ------------ |
| 148 | $ edit <1> |
| 149 | $ git add frotz.c filfre.c |
| 150 | $ mailx <2> |
| 151 | $ git reset <3> |
| 152 | $ git pull git://info.example.com/ nitfol <4> |
| 153 | ------------ |
| 154 | + |
| 155 | <1> You are happily working on something, and find the changes |
| 156 | in these files are in good order. You do not want to see them |
| 157 | when you run `git diff`, because you plan to work on other files |
| 158 | and changes with these files are distracting. |
| 159 | <2> Somebody asks you to pull, and the changes sound worthy of merging. |
| 160 | <3> However, you already dirtied the index (i.e. your index does |
| 161 | not match the `HEAD` commit). But you know the pull you are going |
| 162 | to make does not affect `frotz.c` or `filfre.c`, so you revert the |
| 163 | index changes for these two files. Your changes in working tree |
| 164 | remain there. |
| 165 | <4> Then you can pull and merge, leaving `frotz.c` and `filfre.c` |
| 166 | changes still in the working tree. |
| 167 | |
| 168 | Undo a commit and redo:: |
| 169 | + |
| 170 | ------------ |
| 171 | $ git commit ... |
| 172 | $ git reset --soft HEAD^ <1> |
| 173 | $ edit <2> |
| 174 | $ git commit -a -c ORIG_HEAD <3> |
| 175 | ------------ |
| 176 | + |
| 177 | <1> This is most often done when you remembered what you |
| 178 | just committed is incomplete, or you misspelled your commit |
| 179 | message, or both. Leaves working tree as it was before "reset". |
| 180 | <2> Make corrections to working tree files. |
| 181 | <3> "reset" copies the old head to `.git/ORIG_HEAD`; redo the |
| 182 | commit by starting with its log message. If you do not need to |
| 183 | edit the message further, you can give `-C` option instead. |
| 184 | + |
| 185 | See also the `--amend` option to linkgit:git-commit[1]. |
| 186 | |
| 187 | Undo a commit, making it a topic branch:: |
| 188 | + |
| 189 | ------------ |
| 190 | $ git branch topic/wip <1> |
| 191 | $ git reset --hard HEAD~3 <2> |
| 192 | $ git switch topic/wip <3> |
| 193 | ------------ |
| 194 | + |
| 195 | <1> You have made some commits, but realize they were premature |
| 196 | to be in the `master` branch. You want to continue polishing |
| 197 | them in a topic branch, so create `topic/wip` branch off of the |
| 198 | current `HEAD`. |
| 199 | <2> Rewind the master branch to get rid of those three commits. |
| 200 | <3> Switch to `topic/wip` branch and keep working. |
| 201 | |
| 202 | Undo commits permanently:: |
| 203 | + |
| 204 | ------------ |
| 205 | $ git commit ... |
| 206 | $ git reset --hard HEAD~3 <1> |
| 207 | ------------ |
| 208 | + |
| 209 | <1> The last three commits (`HEAD`, `HEAD^`, and `HEAD~2`) were bad |
| 210 | and you do not want to ever see them again. Do *not* do this if |
| 211 | you have already given these commits to somebody else. (See the |
| 212 | "RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1] |
| 213 | for the implications of doing so.) |
| 214 | |
| 215 | Undo a merge or pull:: |
| 216 | + |
| 217 | ------------ |
| 218 | $ git pull <1> |
| 219 | Auto-merging nitfol |
| 220 | CONFLICT (content): Merge conflict in nitfol |
| 221 | Automatic merge failed; fix conflicts and then commit the result. |
| 222 | $ git reset --hard <2> |
| 223 | $ git pull . topic/branch <3> |
| 224 | Updating from 41223... to 13134... |
| 225 | Fast-forward |
| 226 | $ git reset --hard ORIG_HEAD <4> |
| 227 | ------------ |
| 228 | + |
| 229 | <1> Try to update from the upstream resulted in a lot of |
| 230 | conflicts; you were not ready to spend a lot of time merging |
| 231 | right now, so you decide to do that later. |
| 232 | <2> "pull" has not made merge commit, so `git reset --hard` |
| 233 | which is a synonym for `git reset --hard HEAD` clears the mess |
| 234 | from the index file and the working tree. |
| 235 | <3> Merge a topic branch into the current branch, which resulted |
| 236 | in a fast-forward. |
| 237 | <4> But you decided that the topic branch is not ready for public |
| 238 | consumption yet. "pull" or "merge" always leaves the original |
| 239 | tip of the current branch in `ORIG_HEAD`, so resetting hard to it |
| 240 | brings your index file and the working tree back to that state, |
| 241 | and resets the tip of the branch to that commit. |
| 242 | |
| 243 | Undo a merge or pull inside a dirty working tree:: |
| 244 | + |
| 245 | ------------ |
| 246 | $ git pull <1> |
| 247 | Auto-merging nitfol |
| 248 | Merge made by recursive. |
| 249 | nitfol | 20 +++++---- |
| 250 | ... |
| 251 | $ git reset --merge ORIG_HEAD <2> |
| 252 | ------------ |
| 253 | + |
| 254 | <1> Even if you may have local modifications in your |
| 255 | working tree, you can safely say `git pull` when you know |
| 256 | that the change in the other branch does not overlap with |
| 257 | them. |
| 258 | <2> After inspecting the result of the merge, you may find |
| 259 | that the change in the other branch is unsatisfactory. Running |
| 260 | `git reset --hard ORIG_HEAD` will let you go back to where you |
| 261 | were, but it will discard your local changes, which you do not |
| 262 | want. `git reset --merge` keeps your local changes. |
| 263 | |
| 264 | |
| 265 | Interrupted workflow:: |
| 266 | + |
| 267 | Suppose you are interrupted by an urgent fix request while you |
| 268 | are in the middle of a large change. The files in your |
| 269 | working tree are not in any shape to be committed yet, but you |
| 270 | need to get to the other branch for a quick bugfix. |
| 271 | + |
| 272 | ------------ |
| 273 | $ git switch feature ;# you were working in "feature" branch and |
| 274 | $ work work work ;# got interrupted |
| 275 | $ git commit -a -m "snapshot WIP" <1> |
| 276 | $ git switch master |
| 277 | $ fix fix fix |
| 278 | $ git commit ;# commit with real log |
| 279 | $ git switch feature |
| 280 | $ git reset --soft HEAD^ ;# go back to WIP state <2> |
| 281 | $ git reset <3> |
| 282 | ------------ |
| 283 | + |
| 284 | <1> This commit will get blown away so a throw-away log message is OK. |
| 285 | <2> This removes the 'WIP' commit from the commit history, and sets |
| 286 | your working tree to the state just before you made that snapshot. |
| 287 | <3> At this point the index file still has all the WIP changes you |
| 288 | committed as 'snapshot WIP'. This updates the index to show your |
| 289 | WIP files as uncommitted. |
| 290 | + |
| 291 | See also linkgit:git-stash[1]. |
| 292 | |
| 293 | Reset a single file in the index:: |
| 294 | + |
| 295 | Suppose you have added a file to your index, but later decide you do not |
| 296 | want to add it to your commit. You can remove the file from the index |
| 297 | while keeping your changes with git reset. |
| 298 | + |
| 299 | ------------ |
| 300 | $ git reset -- frotz.c <1> |
| 301 | $ git commit -m "Commit files in index" <2> |
| 302 | $ git add frotz.c <3> |
| 303 | ------------ |
| 304 | + |
| 305 | <1> This removes the file from the index while keeping it in the working |
| 306 | directory. |
| 307 | <2> This commits all other changes in the index. |
| 308 | <3> Adds the file to the index again. |
| 309 | |
| 310 | Keep changes in working tree while discarding some previous commits:: |
| 311 | + |
| 312 | Suppose you are working on something and you commit it, and then you |
| 313 | continue working a bit more, but now you think that what you have in |
| 314 | your working tree should be in another branch that has nothing to do |
| 315 | with what you committed previously. You can start a new branch and |
| 316 | reset it while keeping the changes in your working tree. |
| 317 | + |
| 318 | ------------ |
| 319 | $ git tag start |
| 320 | $ git switch -c branch1 |
| 321 | $ edit |
| 322 | $ git commit ... <1> |
| 323 | $ edit |
| 324 | $ git switch -c branch2 <2> |
| 325 | $ git reset --keep start <3> |
| 326 | ------------ |
| 327 | + |
| 328 | <1> This commits your first edits in `branch1`. |
| 329 | <2> In the ideal world, you could have realized that the earlier |
| 330 | commit did not belong to the new topic when you created and switched |
| 331 | to `branch2` (i.e. `git switch -c branch2 start`), but nobody is |
| 332 | perfect. |
| 333 | <3> But you can use `reset --keep` to remove the unwanted commit after |
| 334 | you switched to `branch2`. |
| 335 | |
| 336 | Split a commit apart into a sequence of commits:: |
| 337 | + |
| 338 | Suppose that you have created lots of logically separate changes and committed |
| 339 | them together. Then, later you decide that it might be better to have each |
| 340 | logical chunk associated with its own commit. You can use git reset to rewind |
| 341 | history without changing the contents of your local files, and then successively |
| 342 | use `git add -p` to interactively select which hunks to include into each commit, |
| 343 | using `git commit -c` to pre-populate the commit message. |
| 344 | + |
| 345 | ------------ |
| 346 | $ git reset -N HEAD^ <1> |
| 347 | $ git add -p <2> |
| 348 | $ git diff --cached <3> |
| 349 | $ git commit -c HEAD@{1} <4> |
| 350 | ... <5> |
| 351 | $ git add ... <6> |
| 352 | $ git diff --cached <7> |
| 353 | $ git commit ... <8> |
| 354 | ------------ |
| 355 | + |
| 356 | <1> First, reset the history back one commit so that we remove the original |
| 357 | commit, but leave the working tree with all the changes. The `-N` ensures |
| 358 | that any new files added with `HEAD` are still marked so that `git add -p` |
| 359 | will find them. |
| 360 | <2> Next, we interactively select diff hunks to add using the `git add -p` |
| 361 | facility. This will ask you about each diff hunk in sequence and you can |
| 362 | use simple commands such as "yes, include this", "No don't include this" |
| 363 | or even the very powerful "edit" facility. |
| 364 | <3> Once satisfied with the hunks you want to include, you should verify what |
| 365 | has been prepared for the first commit by using `git diff --cached`. This |
| 366 | shows all the changes that have been moved into the index and are about |
| 367 | to be committed. |
| 368 | <4> Next, commit the changes stored in the index. The `-c` option specifies to |
| 369 | pre-populate the commit message from the original message that you started |
| 370 | with in the first commit. This is helpful to avoid retyping it. The |
| 371 | `HEAD@{1}` is a special notation for the commit that `HEAD` used to be at |
| 372 | prior to the original reset commit (1 change ago). |
| 373 | See linkgit:git-reflog[1] for more details. You may also use any other |
| 374 | valid commit reference. |
| 375 | <5> You can repeat steps 2-4 multiple times to break the original code into |
| 376 | any number of commits. |
| 377 | <6> Now you've split out many of the changes into their own commits, and might |
| 378 | no longer use the patch mode of `git add`, in order to select all remaining |
| 379 | uncommitted changes. |
| 380 | <7> Once again, check to verify that you've included what you want to. You may |
| 381 | also wish to verify that git diff doesn't show any remaining changes to be |
| 382 | committed later. |
| 383 | <8> And finally create the final commit. |
| 384 | |
| 385 | |
| 386 | DISCUSSION |
| 387 | ---------- |
| 388 | |
| 389 | The tables below show what happens when running: |
| 390 | |
| 391 | ---------- |
| 392 | git reset --option target |
| 393 | ---------- |
| 394 | |
| 395 | to reset the `HEAD` to another commit (`target`) with the different |
| 396 | reset options depending on the state of the files. |
| 397 | |
| 398 | In these tables, `A`, `B`, `C` and `D` are some different states of a |
| 399 | file. For example, the first line of the first table means that if a |
| 400 | file is in state `A` in the working tree, in state `B` in the index, in |
| 401 | state `C` in `HEAD` and in state `D` in the target, then `git reset --soft |
| 402 | target` will leave the file in the working tree in state `A` and in the |
| 403 | index in state `B`. It resets (i.e. moves) the `HEAD` (i.e. the tip of |
| 404 | the current branch, if you are on one) to `target` (which has the file |
| 405 | in state `D`). |
| 406 | |
| 407 | .... |
| 408 | working index HEAD target working index HEAD |
| 409 | ---------------------------------------------------- |
| 410 | A B C D --soft A B D |
| 411 | --mixed A D D |
| 412 | --hard D D D |
| 413 | --merge (disallowed) |
| 414 | --keep (disallowed) |
| 415 | .... |
| 416 | |
| 417 | .... |
| 418 | working index HEAD target working index HEAD |
| 419 | ---------------------------------------------------- |
| 420 | A B C C --soft A B C |
| 421 | --mixed A C C |
| 422 | --hard C C C |
| 423 | --merge (disallowed) |
| 424 | --keep A C C |
| 425 | .... |
| 426 | |
| 427 | .... |
| 428 | working index HEAD target working index HEAD |
| 429 | ---------------------------------------------------- |
| 430 | B B C D --soft B B D |
| 431 | --mixed B D D |
| 432 | --hard D D D |
| 433 | --merge D D D |
| 434 | --keep (disallowed) |
| 435 | .... |
| 436 | |
| 437 | .... |
| 438 | working index HEAD target working index HEAD |
| 439 | ---------------------------------------------------- |
| 440 | B B C C --soft B B C |
| 441 | --mixed B C C |
| 442 | --hard C C C |
| 443 | --merge C C C |
| 444 | --keep B C C |
| 445 | .... |
| 446 | |
| 447 | .... |
| 448 | working index HEAD target working index HEAD |
| 449 | ---------------------------------------------------- |
| 450 | B C C D --soft B C D |
| 451 | --mixed B D D |
| 452 | --hard D D D |
| 453 | --merge (disallowed) |
| 454 | --keep (disallowed) |
| 455 | .... |
| 456 | |
| 457 | .... |
| 458 | working index HEAD target working index HEAD |
| 459 | ---------------------------------------------------- |
| 460 | B C C C --soft B C C |
| 461 | --mixed B C C |
| 462 | --hard C C C |
| 463 | --merge B C C |
| 464 | --keep B C C |
| 465 | .... |
| 466 | |
| 467 | `git reset --merge` is meant to be used when resetting out of a conflicted |
| 468 | merge. Any mergy operation guarantees that the working tree file that is |
| 469 | involved in the merge does not have a local change with respect to the index |
| 470 | before it starts, and that it writes the result out to the working tree. So if |
| 471 | we see some difference between the index and the target and also |
| 472 | between the index and the working tree, then it means that we are not |
| 473 | resetting out from a state that a mergy operation left after failing |
| 474 | with a conflict. That is why we disallow `--merge` option in this case. |
| 475 | |
| 476 | `git reset --keep` is meant to be used when removing some of the last |
| 477 | commits in the current branch while keeping changes in the working |
| 478 | tree. If there could be conflicts between the changes in the commit we |
| 479 | want to remove and the changes in the working tree we want to keep, |
| 480 | the reset is disallowed. That's why it is disallowed if there are both |
| 481 | changes between the working tree and `HEAD`, and between `HEAD` and the |
| 482 | target. To be safe, it is also disallowed when there are unmerged |
| 483 | entries. |
| 484 | |
| 485 | The following tables show what happens when there are unmerged |
| 486 | entries: |
| 487 | |
| 488 | .... |
| 489 | working index HEAD target working index HEAD |
| 490 | ---------------------------------------------------- |
| 491 | X U A B --soft (disallowed) |
| 492 | --mixed X B B |
| 493 | --hard B B B |
| 494 | --merge B B B |
| 495 | --keep (disallowed) |
| 496 | .... |
| 497 | |
| 498 | .... |
| 499 | working index HEAD target working index HEAD |
| 500 | ---------------------------------------------------- |
| 501 | X U A A --soft (disallowed) |
| 502 | --mixed X A A |
| 503 | --hard A A A |
| 504 | --merge A A A |
| 505 | --keep (disallowed) |
| 506 | .... |
| 507 | |
| 508 | `X` means any state and `U` means an unmerged index. |
| 509 | |
| 510 | GIT |
| 511 | --- |
| 512 | Part of the linkgit:git[1] suite |