Documentation: "git reset <tree-ish> <pathspec>" takes a tree-ish, not tree-sh
[git/git.git] / Documentation / git-reset.txt
CommitLineData
215a7ad1
JH
1git-reset(1)
2============
7fc9d69f
JH
3
4NAME
5----
7bd7f280 6git-reset - Reset current HEAD to the specified state
7fc9d69f
JH
7
8SYNOPSIS
9--------
6934dec8 10[verse]
bf44142f 11'git reset' [-q] [<tree-ish>] [--] <paths>...
debecc55 12'git reset' (--patch | -p) [<tree-ish>] [--] [<paths>...]
d505865b 13'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>]
7fc9d69f
JH
14
15DESCRIPTION
16-----------
bf44142f 17In the first and second form, copy entries from <tree-ish> to the index.
d537c749 18In the third form, set the current branch head (HEAD) to <commit>, optionally
bf44142f
MZ
19modifying index and working tree to match. The <tree-ish>/<commit> defaults
20to HEAD in all forms.
7b8cd49d 21
bf44142f 22'git reset' [-q] [<tree-ish>] [--] <paths>...::
7b8cd49d 23 This form resets the index entries for all <paths> to their
bf44142f 24 state at <tree-ish>. (It does not affect the working tree, nor
7b8cd49d
TR
25 the current branch.)
26+
27This means that `git reset <paths>` is the opposite of `git add
28<paths>`.
9980d7de
MG
29+
30After running `git reset <paths>` to update the index entry, you can
31use linkgit:git-checkout[1] to check the contents out of the index to
32the working tree.
33Alternatively, using linkgit:git-checkout[1] and specifying a commit, you
34can copy the contents of a path out of a commit to the index and to the
35working tree in one go.
6934dec8 36
bf44142f 37'git reset' (--patch | -p) [<tree-ish>] [--] [<paths>...]::
7b8cd49d 38 Interactively select hunks in the difference between the index
bf44142f 39 and <tree-ish> (defaults to HEAD). The chosen hunks are applied
7b8cd49d
TR
40 in reverse to the index.
41+
6086ff65
VH
42This means that `git reset -p` is the opposite of `git add -p`, i.e.
43you can use it to selectively reset hunks. See the ``Interactive Mode''
6cf378f0 44section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
6934dec8 45
d505865b 46'git reset' [<mode>] [<commit>]::
d537c749
MG
47 This form resets the current branch head to <commit> and
48 possibly updates the index (resetting it to the tree of <commit>) and
d505865b
KM
49 the working tree depending on <mode>. If <mode> is omitted,
50 defaults to "--mixed". The <mode> must be one of the following:
7b8cd49d
TR
51+
52--
f67545ea 53--soft::
cca5d0b0
MG
54 Does not touch the index file nor the working tree at all (but
55 resets the head to <commit>, just like all modes do). This leaves
56 all your changed files "Changes to be committed", as 'git status'
57 would put it.
7fc9d69f 58
bb59b7ff
TR
59--mixed::
60 Resets the index but not the working tree (i.e., the changed files
61 are preserved but not marked for commit) and reports what has not
62 been updated. This is the default action.
63
f67545ea 64--hard::
d537c749
MG
65 Resets the index and working tree. Any changes to tracked files in the
66 working tree since <commit> are discarded.
7fc9d69f 67
1b5b465f 68--merge::
d537c749
MG
69 Resets the index and updates the files in the working tree that are
70 different between <commit> and HEAD, but keeps those which are
71 different between the index and working tree (i.e. which have changes
72 which have not been added).
73 If a file that is different between <commit> and the index has unstaged
74 changes, reset is aborted.
75+
76In other words, --merge does something like a 'git read-tree -u -m <commit>',
77but carries forward unmerged index entries.
1b5b465f 78
7349df11 79--keep::
8c0db6fd
JN
80 Resets index entries and updates files in the working tree that are
81 different between <commit> and HEAD.
d537c749
MG
82 If a file that is different between <commit> and HEAD has local changes,
83 reset is aborted.
7b8cd49d 84--
7349df11 85
7b8cd49d
TR
86If you want to undo a commit other than the latest on a branch,
87linkgit:git-revert[1] is your friend.
88
89
90OPTIONS
91-------
d002ef4d 92
521b53e5 93-q::
5d2dcc42 94--quiet::
521b53e5
GP
95 Be quiet, only report errors.
96
7fc9d69f 97
28bb4b27 98EXAMPLES
2b5f3ed3 99--------
1e2ccd3a 100
8bb95bbc
TR
101Undo add::
102+
103------------
104$ edit <1>
105$ git add frotz.c filfre.c
106$ mailx <2>
107$ git reset <3>
108$ git pull git://info.example.com/ nitfol <4>
109------------
110+
111<1> You are happily working on something, and find the changes
112in these files are in good order. You do not want to see them
113when you run "git diff", because you plan to work on other files
114and changes with these files are distracting.
115<2> Somebody asks you to pull, and the changes sounds worthy of merging.
116<3> However, you already dirtied the index (i.e. your index does
117not match the HEAD commit). But you know the pull you are going
118to make does not affect frotz.c nor filfre.c, so you revert the
119index changes for these two files. Your changes in working tree
120remain there.
121<4> Then you can pull and merge, leaving frotz.c and filfre.c
122changes still in the working tree.
123
1e2ccd3a
JH
124Undo a commit and redo::
125+
126------------
127$ git commit ...
48aeecdc
SE
128$ git reset --soft HEAD^ <1>
129$ edit <2>
130$ git commit -a -c ORIG_HEAD <3>
131------------
132+
1e2ccd3a
JH
133<1> This is most often done when you remembered what you
134just committed is incomplete, or you misspelled your commit
135message, or both. Leaves working tree as it was before "reset".
434e6ef8 136<2> Make corrections to working tree files.
1e2ccd3a
JH
137<3> "reset" copies the old head to .git/ORIG_HEAD; redo the
138commit by starting with its log message. If you do not need to
139edit the message further, you can give -C option instead.
41728d69 140+
5162e697 141See also the --amend option to linkgit:git-commit[1].
1e2ccd3a 142
1e2ccd3a
JH
143Undo a commit, making it a topic branch::
144+
145------------
48aeecdc
SE
146$ git branch topic/wip <1>
147$ git reset --hard HEAD~3 <2>
148$ git checkout topic/wip <3>
149------------
150+
1e2ccd3a
JH
151<1> You have made some commits, but realize they were premature
152to be in the "master" branch. You want to continue polishing
153them in a topic branch, so create "topic/wip" branch off of the
154current HEAD.
155<2> Rewind the master branch to get rid of those three commits.
156<3> Switch to "topic/wip" branch and keep working.
1e2ccd3a 157
6e90f7b8
TR
158Undo commits permanently::
159+
160------------
161$ git commit ...
162$ git reset --hard HEAD~3 <1>
163------------
164+
165<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad
166and you do not want to ever see them again. Do *not* do this if
167you have already given these commits to somebody else. (See the
168"RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1] for
169the implications of doing so.)
170
3ae854c3
JH
171Undo a merge or pull::
172+
173------------
48aeecdc 174$ git pull <1>
3ae854c3
JH
175Auto-merging nitfol
176CONFLICT (content): Merge conflict in nitfol
ec9f0ea3 177Automatic merge failed; fix conflicts and then commit the result.
48aeecdc
SE
178$ git reset --hard <2>
179$ git pull . topic/branch <3>
180Updating from 41223... to 13134...
a75d7b54 181Fast-forward
48aeecdc
SE
182$ git reset --hard ORIG_HEAD <4>
183------------
184+
434e6ef8 185<1> Try to update from the upstream resulted in a lot of
3ae854c3
JH
186conflicts; you were not ready to spend a lot of time merging
187right now, so you decide to do that later.
188<2> "pull" has not made merge commit, so "git reset --hard"
189which is a synonym for "git reset --hard HEAD" clears the mess
190from the index file and the working tree.
434e6ef8 191<3> Merge a topic branch into the current branch, which resulted
a75d7b54 192in a fast-forward.
434e6ef8 193<4> But you decided that the topic branch is not ready for public
3ae854c3
JH
194consumption yet. "pull" or "merge" always leaves the original
195tip of the current branch in ORIG_HEAD, so resetting hard to it
196brings your index file and the working tree back to that state,
197and resets the tip of the branch to that commit.
1e2ccd3a 198
06cdac5a 199Undo a merge or pull inside a dirty working tree::
1b5b465f
JH
200+
201------------
202$ git pull <1>
203Auto-merging nitfol
204Merge made by recursive.
205 nitfol | 20 +++++----
206 ...
207$ git reset --merge ORIG_HEAD <2>
208------------
209+
210<1> Even if you may have local modifications in your
211working tree, you can safely say "git pull" when you know
212that the change in the other branch does not overlap with
213them.
214<2> After inspecting the result of the merge, you may find
215that the change in the other branch is unsatisfactory. Running
216"git reset --hard ORIG_HEAD" will let you go back to where you
217were, but it will discard your local changes, which you do not
218want. "git reset --merge" keeps your local changes.
219
220
a0dfb48a
JH
221Interrupted workflow::
222+
8278ac2f
BF
223Suppose you are interrupted by an urgent fix request while you
224are in the middle of a large change. The files in your
a0dfb48a
JH
225working tree are not in any shape to be committed yet, but you
226need to get to the other branch for a quick bugfix.
227+
228------------
229$ git checkout feature ;# you were working in "feature" branch and
230$ work work work ;# got interrupted
d336fc09 231$ git commit -a -m "snapshot WIP" <1>
a0dfb48a
JH
232$ git checkout master
233$ fix fix fix
234$ git commit ;# commit with real log
235$ git checkout feature
48aeecdc
SE
236$ git reset --soft HEAD^ ;# go back to WIP state <2>
237$ git reset <3>
238------------
239+
a0dfb48a 240<1> This commit will get blown away so a throw-away log message is OK.
8278ac2f
BF
241<2> This removes the 'WIP' commit from the commit history, and sets
242 your working tree to the state just before you made that snapshot.
48aeecdc
SE
243<3> At this point the index file still has all the WIP changes you
244 committed as 'snapshot WIP'. This updates the index to show your
245 WIP files as uncommitted.
53682f0c
MH
246+
247See also linkgit:git-stash[1].
a0dfb48a 248
965053b0
PB
249Reset a single file in the index::
250+
251Suppose you have added a file to your index, but later decide you do not
252want to add it to your commit. You can remove the file from the index
253while keeping your changes with git reset.
254+
255------------
256$ git reset -- frotz.c <1>
257$ git commit -m "Commit files in index" <2>
258$ git add frotz.c <3>
259------------
260+
261<1> This removes the file from the index while keeping it in the working
262 directory.
263<2> This commits all other changes in the index.
264<3> Adds the file to the index again.
265
7349df11
CC
266Keep changes in working tree while discarding some previous commits::
267+
268Suppose you are working on something and you commit it, and then you
269continue working a bit more, but now you think that what you have in
270your working tree should be in another branch that has nothing to do
6b677a28 271with what you committed previously. You can start a new branch and
06cdac5a 272reset it while keeping the changes in your working tree.
7349df11
CC
273+
274------------
275$ git tag start
276$ git checkout -b branch1
277$ edit
278$ git commit ... <1>
279$ edit
280$ git checkout -b branch2 <2>
281$ git reset --keep start <3>
282------------
283+
284<1> This commits your first edits in branch1.
285<2> In the ideal world, you could have realized that the earlier
286 commit did not belong to the new topic when you created and switched
287 to branch2 (i.e. "git checkout -b branch2 start"), but nobody is
288 perfect.
289<3> But you can use "reset --keep" to remove the unwanted commit after
290 you switched to "branch2".
291
28bb4b27
TR
292
293DISCUSSION
294----------
295
296The tables below show what happens when running:
297
298----------
299git reset --option target
300----------
301
302to reset the HEAD to another commit (`target`) with the different
303reset options depending on the state of the files.
304
305In these tables, A, B, C and D are some different states of a
306file. For example, the first line of the first table means that if a
307file is in state A in the working tree, in state B in the index, in
308state C in HEAD and in state D in the target, then "git reset --soft
aad84414
MG
309target" will leave the file in the working tree in state A and in the
310index in state B. It resets (i.e. moves) the HEAD (i.e. the tip of
311the current branch, if you are on one) to "target" (which has the file
312in state D).
28bb4b27
TR
313
314 working index HEAD target working index HEAD
315 ----------------------------------------------------
316 A B C D --soft A B D
317 --mixed A D D
318 --hard D D D
319 --merge (disallowed)
320 --keep (disallowed)
321
322 working index HEAD target working index HEAD
323 ----------------------------------------------------
324 A B C C --soft A B C
325 --mixed A C C
326 --hard C C C
327 --merge (disallowed)
328 --keep A C C
329
330 working index HEAD target working index HEAD
331 ----------------------------------------------------
332 B B C D --soft B B D
333 --mixed B D D
334 --hard D D D
335 --merge D D D
336 --keep (disallowed)
337
338 working index HEAD target working index HEAD
339 ----------------------------------------------------
340 B B C C --soft B B C
341 --mixed B C C
342 --hard C C C
343 --merge C C C
344 --keep B C C
345
346 working index HEAD target working index HEAD
347 ----------------------------------------------------
348 B C C D --soft B C D
349 --mixed B D D
350 --hard D D D
351 --merge (disallowed)
352 --keep (disallowed)
353
354 working index HEAD target working index HEAD
355 ----------------------------------------------------
356 B C C C --soft B C C
357 --mixed B C C
358 --hard C C C
359 --merge B C C
360 --keep B C C
361
362"reset --merge" is meant to be used when resetting out of a conflicted
06cdac5a 363merge. Any mergy operation guarantees that the working tree file that is
28bb4b27 364involved in the merge does not have local change wrt the index before
06cdac5a 365it starts, and that it writes the result out to the working tree. So if
28bb4b27 366we see some difference between the index and the target and also
06cdac5a 367between the index and the working tree, then it means that we are not
28bb4b27
TR
368resetting out from a state that a mergy operation left after failing
369with a conflict. That is why we disallow --merge option in this case.
370
371"reset --keep" is meant to be used when removing some of the last
372commits in the current branch while keeping changes in the working
373tree. If there could be conflicts between the changes in the commit we
374want to remove and the changes in the working tree we want to keep,
375the reset is disallowed. That's why it is disallowed if there are both
376changes between the working tree and HEAD, and between HEAD and the
377target. To be safe, it is also disallowed when there are unmerged
378entries.
379
380The following tables show what happens when there are unmerged
381entries:
382
383 working index HEAD target working index HEAD
384 ----------------------------------------------------
385 X U A B --soft (disallowed)
386 --mixed X B B
387 --hard B B B
388 --merge B B B
389 --keep (disallowed)
390
391 working index HEAD target working index HEAD
392 ----------------------------------------------------
393 X U A A --soft (disallowed)
394 --mixed X A A
395 --hard A A A
396 --merge A A A
397 --keep (disallowed)
398
399X means any state and U means an unmerged index.
400
7fc9d69f
JH
401GIT
402---
9e1f0a85 403Part of the linkgit:git[1] suite