bad git pull

bad git pull

[Don Zickus]

Hello,

I notice if I create a branch (and switch to it) in the linux kernel
off of say version 2.6.14, then later do a git pull, things get ugly. 
It seems like all the upstream changes are being merged into the
2.6.14 branch (instead of the latest kernel tag).

Is this a user error because the tool is still fragile?

Thanks,
Don

Re: bad git pull

[Junio C Hamano]

Don Zickus <dzickus@gmail.com> writes:

> I notice if I create a branch (and switch to it) in the linux kernel
> off of say version 2.6.14, then later do a git pull, things get ugly. 
> It seems like all the upstream changes are being merged into the
> 2.6.14 branch (instead of the latest kernel tag).
>
> Is this a user error because the tool is still fragile?

I do not understand the question.

The user wanted all the good developments from the mainline into
the fork he created starting at 2.6.14, and the tool did what
was asked.  Why would you want to forbid that from happening,
and what did you want to happen instead?

Re: bad git pull

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

> Don Zickus <dzickus@gmail.com> writes:
>
>> I notice if I create a branch (and switch to it) in the linux kernel
>> off of say version 2.6.14, then later do a git pull, things get ugly. 
>> It seems like all the upstream changes are being merged into the
>> 2.6.14 branch (instead of the latest kernel tag).
>>
>> Is this a user error because the tool is still fragile?
>
> I do not understand the question.
>
> The user wanted all the good developments from the mainline into
> the fork he created starting at 2.6.14, and the tool did what
> was asked.  Why would you want to forbid that from happening,
> and what did you want to happen instead?

Actually I think I do understand the question.  You have a clone
of linux-2.6 repository, and your "origin" branch tracks the
bleeding edge from Linus.  You also have "myhack" branch that
was forked off from 2.6.14, and wanted to see what new things
Linus has by updating "origin", and perhaps merge those changes
into your "master" which keeps track of your hacks based on
Linus tip, but unfortunately you were on "myhack" branch.

Ouch.

So what you wanted to do was probably:

	$ git fetch ;# this updates "origin" to Linus tip

instead of

	$ git pull ;# this updates "origin" to Linus tip *and*
                    # merges that into the current branch

As you may probably know, you can recover by

	$ git reset --hard

While I am sympathetic, this "Oops, I said pull when I meant
fetch" sounds remotely similar to "oops, I said 'rm -r' when I
meant to say 'ls -r'".  Is it that the tool is too fragile?

Re: bad git pull

[Don Zickus]

> While I am sympathetic, this "Oops, I said pull when I meant
> fetch" sounds remotely similar to "oops, I said 'rm -r' when I
> meant to say 'ls -r'".  Is it that the tool is too fragile?
>

Sorry, wrong choice of words.  Didn't mean to imply anything negative.
Though, I am still learning the tool and its features, I do appreciate
your feedback and your last email was correct in understanding the
mess I created.  I'll go read up on the differences between 'fetch'
and 'pull'.

Cheers,
Don

Re: bad git pull

[Junio C Hamano]

Don Zickus <dzickus@gmail.com> writes:

>> While I am sympathetic, this "Oops, I said pull when I meant
>> fetch" sounds remotely similar to "oops, I said 'rm -r' when I
>> meant to say 'ls -r'".  Is it that the tool is too fragile?
>
> Sorry, wrong choice of words.  Didn't mean to imply anything negative.
> Though, I am still learning the tool and its features, I do appreciate
> your feedback and your last email was correct in understanding the
> mess I created.  I'll go read up on the differences between 'fetch'
> and 'pull'.

I too was a bit too defensive, and I agree the tool is prone to
easy errors; the worst part is that there is no "rm -i"
equivalent to be extra careful [*1*].  On the other hand, we
have "git reset" to recover from, so it is not as bad as
a mistake with "rm" ;-).

If for example there were a way to say "this `origin' shortcut
is to be pulled into `master' branch and nothing else", we could
have caught the "git pull" you had trouble with.  There was a
discussion on the list in the past to extend remotes/ files to
allow such restriction of the patchflow to be expressed, but
back then I felt the kind of restriction the proposal could
express was too limiting, and the discussion was a bit premature
because we did not have recommended patterns yet.

We might want to revive the discussion post 1.0.  Taking the
example of the topic-branch workflow by Tony, the "patch flow"
language needs to be able to express something at least this:

 - topic branches -- branched from 'origin' somewhere in the
   past; commits accumulated but usually nothing is merged
   into them.

 - 'test' -- branched from 'origin' somewhere in the past; used
   solely to merge topic branches into it and no commits are
   made into it directly; branches that are regularly merged
   into it are:

   - topic branches
   - 'origin'
   - 'release'

 - 'release' -- branched from 'origin' somewhere in the
   past; trivial/obviously correct commits are made into it
   directly; proven to be good topic branches are merged into it
   for consumption by others; branches that are regularly merged
   into it are:

   - topic branches
   - 'origin'
   - never 'test' 



[Footnote]

*1* IMHO "rm -i" is not that safe, though.  If one overuses it,
it trains one's fingers to say "y" without much thinking.

Re: bad git pull

[Carl Baldwin]

Hello,

Here are my two cents.  I'll try my best to make a case for those poor
souls who get into this sort of mess.

Whenever I give a colleage an introduction to git I emphatically
recommend that they start with using git fetch and git merge
independantly of each other and stay away for git pull at least until
they know what they're doing.  This is because I have found that people
are really surprised at what happens when they type git pull until it
really sinks in that 'pull = fetch + merge to current branch, whatever
that may be'.

The difference between the words fetch and pull is much more subtle than
the difference between remove and list which are the basis for the
commands rm and ls.  I see nothing in the English dictionary to suggest
that pull means fetch + merge.  This is a gitism.  Even after reading
documentation clearly and even using git for a while the difference
really takes some time to sink in.

I think a great degree of understanding should be shown toward those who
dig themselves into this kind of thing.  I also recommend that some
extra care should be taken in the tutorials and documentation to warn
about this difference up front and possibly suggest avoiding the use of
pull for those new to git.

Carl

PS The issue was exacerbated when cogito and git were inconsistent on
their respective usages of pull and fetch.  I think this has gone away,
hasn't it?  I haven't used cogito in some time so I really don't know.

On Thu, Dec 15, 2005 at 03:53:38PM -0800, Junio C Hamano wrote:
> Junio C Hamano <junkio@cox.net> writes:
> 
> > Don Zickus <dzickus@gmail.com> writes:
> >
> >> I notice if I create a branch (and switch to it) in the linux kernel
> >> off of say version 2.6.14, then later do a git pull, things get ugly. 
> >> It seems like all the upstream changes are being merged into the
> >> 2.6.14 branch (instead of the latest kernel tag).
> >>
> >> Is this a user error because the tool is still fragile?
> >
> > I do not understand the question.
> >
> > The user wanted all the good developments from the mainline into
> > the fork he created starting at 2.6.14, and the tool did what
> > was asked.  Why would you want to forbid that from happening,
> > and what did you want to happen instead?
> 
> Actually I think I do understand the question.  You have a clone
> of linux-2.6 repository, and your "origin" branch tracks the
> bleeding edge from Linus.  You also have "myhack" branch that
> was forked off from 2.6.14, and wanted to see what new things
> Linus has by updating "origin", and perhaps merge those changes
> into your "master" which keeps track of your hacks based on
> Linus tip, but unfortunately you were on "myhack" branch.
> 
> Ouch.
> 
> So what you wanted to do was probably:
> 
> 	$ git fetch ;# this updates "origin" to Linus tip
> 
> instead of
> 
> 	$ git pull ;# this updates "origin" to Linus tip *and*
>                     # merges that into the current branch
> 
> As you may probably know, you can recover by
> 
> 	$ git reset --hard
> 
> While I am sympathetic, this "Oops, I said pull when I meant
> fetch" sounds remotely similar to "oops, I said 'rm -r' when I
> meant to say 'ls -r'".  Is it that the tool is too fragile?
> 
> 
> -
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

-- 
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 Carl Baldwin                        Systems VLSI Laboratory
 Hewlett Packard Company
 MS 88                               work: 970 898-1523
 3404 E. Harmony Rd.                 work: Carl.N.Baldwin@hp.com
 Fort Collins, CO 80525              home: Carl@ecBaldwin.net
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Re: bad git pull

[Junio C Hamano]

Carl Baldwin <cnb@fc.hp.com> writes:

> Whenever I give a colleage an introduction to git I emphatically
> recommend that they start with using git fetch and git merge
> independantly of each other and stay away for git pull at least until
> they know what they're doing.

You "reduced" this sequence:

	$ git symbolic-ref HEAD ;# to make sure you are on the branch
                                 # you think you are on
	$ git pull

to this sequence:

	$ git fetch origin      ;# would not damage the repository
	$ git symbolic-ref HEAD ;# to make sure you are on the branch
                                 # you think you are on
	$ git merge "Merge from frotz branch of git://..." HEAD FETCH_HEAD

The thing is, you need to make sure where you are, in either
case, before the actual merge happens.  Yours needs extra
typing, and in addition loses the merge message autogenerated by
"git pull".  Sorry, I fail to see how that is an improvement.

> I see nothing in the English dictionary to suggest that pull
> means fetch + merge.

I agree to this.  I have never used BK so this is just a
speculation, but I suspect what happened is that we inherited
"pull" terminology from there, needed to name the merge-less
part something, and we ended up calling it "fetch".  So the
history behind them might be expressed better by "fetch = pull -
merge" instead of saying "pull = fetch + merge" ;-).

> ...  I also recommend that some
> extra care should be taken in the tutorials and documentation to warn
> about this difference up front and possibly suggest avoiding the use of
> pull for those new to git.

Yup.  Thanks for the comments.  I am not a good writer, so a
patch is greatly appreciated.

BTW, I feel that setting Mail-Followup-To: to other people is
just plain rude.

    Mail-Followup-To: Junio C Hamano <junkio@cox.net>,
            Don Zickus <dzickus@gmail.com>, git@vger.kernel.org

I suspect you are trying to avoid receiving a duplicate message
because you subscribe to the list, but when I tell my MUA "I
want to say something to the author of this message in public" I
get Don Zickus on the To: line instead of you, and I had to edit
the To: line to point at you.  Aren't you forcing me (and other
people who might want to follow-up to your message) to do extra
work, and making Don's life harder [*1*], just to work around
the problem on your end, when you could just filter the incoming
duplicates yourself?

Removing yourself from CC: line when the CC: line already
contains the mailing list you subscribe to would be fine, but I
find this use of Mail-Followup-To: somewhat objectionable.

[Footnote]

*1* Don could have a mail sorter that prioritizes messages
addressed To: over Cc: him, and response meant to *you* goes
with To: Don --- which messes up such a mail sorting rule.

Re: bad git pull

[Morten Welinder]

> While I am sympathetic, this "Oops, I said pull when I meant
> fetch" sounds remotely similar to "oops, I said 'rm -r' when I
> meant to say 'ls -r'".  Is it that the tool is too fragile?

Didn't bk come with some kind of (one-level) undo pull?  It should not
be too hard to create something similar considering that one could
just leave new objects in the db orphaned.

M.

Re: bad git pull

[Junio C Hamano]

Morten Welinder <mwelinder@gmail.com> writes:

>> While I am sympathetic, this "Oops, I said pull when I meant
>> fetch" sounds remotely similar to "oops, I said 'rm -r' when I
>> meant to say 'ls -r'".  Is it that the tool is too fragile?
>
> Didn't bk come with some kind of (one-level) undo pull?  It should not
> be too hard to create something similar considering that one could
> just leave new objects in the db orphaned.

Yes, that is called "git reset".

Re: bad git pull

[Linus Torvalds]

On Fri, 16 Dec 2005, Junio C Hamano wrote:
>
> Morten Welinder <mwelinder@gmail.com> writes:
> 
> >> While I am sympathetic, this "Oops, I said pull when I meant
> >> fetch" sounds remotely similar to "oops, I said 'rm -r' when I
> >> meant to say 'ls -r'".  Is it that the tool is too fragile?
> >
> > Didn't bk come with some kind of (one-level) undo pull?  It should not
> > be too hard to create something similar considering that one could
> > just leave new objects in the db orphaned.
> 
> Yes, that is called "git reset".

Well, this is one area where BK and git differ a lot. BK didn't overload 
many things onto the same "reset" functionality, but had specific 
operations for specific cases.

Also BK would never leave a merge in the git kind of half-merged state, 
because BK refuses to have two branches open. Instead, BK had a special 
way of handling merges, which worked fine but quite frankly I have very 
little idea of how it worked (it was some kind of "shadow BK tree", it was 
called ".bk/RESOLVE/" or something like that - but because the tools 
were so nice, you never really had any reason to look into it, so I 
don't know what it did).

BK would never change the working tree itself until the merge was done, so 
you would never need to do what a plain "git reset --hard" (without any 
arguments) does.

In many ways the BK thing was very nice, although the git way is perhaps a 
bit more flexible (because git makes the intermediate tree visible you can 
easily edit the merge errors, and compile/test the result, before you 
decide to commit any manual merge).

I really do like the way git does merges now (especially after the last 
round of git-diff-tree fixes that allow comparing the different stages), 
but the BK way is in some ways cleaner and leaves less potential for 
confusion since it avoids ever exposing you to any half-merged state.

You may remember how I initially argued that we should always try to merge 
stuff outside of the normal working directory. And I still _like_ that 
approach, although I've since decided that I actually prefer the current 
git way is even better in practice.

But "git reset" is a lot more than the "revert to previous state". It 
_also_ does - without the error checking - what "bk fix" used to do 
(which is to undo the last commit, so that you can re-commit it), and it 
also does what "bk undo" used to do. It also does "bk unpull".

So "git reset" really does a whole lot of different and _mostly_ related 
things:

 - undo any half-way changes (very similar to just "git checkout -f"), and 
   just reset to the state of the last successful commit (ie "current 
   HEAD"):

	git reset --hard

   BK didn't need this, although if you just want to remove your edits 
   (which "git reset --hard" also does), you could - like with git - just 
   do a "checkout" operation, of course.

 - undo the last commit, but don't undo the working tree ("soft reset to
   parent of head").

	git reset HEAD^

   I think this was "bk fix -C".

 - undo the last commit entirely ("hard reset to previous state"):

	git reset --hard HEAD^

   This was "bk undo"

 - undo the last pull ("bk unpull"): "hard reset to ORIG_HEAD":

	git reset --hard ORIG_HEAD

   This was "bk unpull".

where the last two are obviously just special cases of a generic "undo to 
arbitrary previous commit state".

BK in many ways had more hand-holding (which I think is good, and "git" to 
some degree has an unnecessarily "hard core" approach to these things). 

For example, I think "bk undo" not only asked you about it, but it also 
only ever undid the last commit (and refused to undo a pull or merge). If 
you wanted to undo to some arbitrary state, you had to use the "-a" flag, 
iirc. 

Of course, under BK the "undo" operation was final, so BK _had_ to be more 
careful. With git, if you undo to some arbitrary state, you can still 
"re-do" all your commits if you just find the old head (and 
git-fsck-objects will help you do that), so in that sense git doesn't 
_need_ to be as careful as BK was.

		Linus

Re: bad git pull

[Morten Welinder]

>  - undo the last commit entirely ("hard reset to previous state"):
>
>         git reset --hard HEAD^
>
>    This was "bk undo"
>
>  - undo the last pull ("bk unpull"): "hard reset to ORIG_HEAD":
>
>         git reset --hard ORIG_HEAD
>
>    This was "bk unpull".

It would be outright peachy if Documentation/git-commit.txt and
Documentation/git-pull.txt mentioned these.  That is certainly
where I would look first to answer the "what if I screwed up?"
question.

Morten

Re: bad git pull

[Linus Torvalds]

On Fri, 16 Dec 2005, Morten Welinder wrote:
> 
> It would be outright peachy if Documentation/git-commit.txt and
> Documentation/git-pull.txt mentioned these.  That is certainly
> where I would look first to answer the "what if I screwed up?"
> question.

It might be even better to have some of the "safe" versions around. Ie 
something that refuses to "undo" a merge (you want to "unpull" it or 
"unmerge" it), and refuses to "undo" when there's a ORIG_HEAD around that 
implies that the last commit was a "pull" (in which case again "undo" may 
be the wrong thing to do, since it will only undo _one_ commit, even 
though the pull might have fast-forwarded a _lot_ of commits).

Of course, if we do that, we should also make sure that "git commit" 
removes ORIG_HEAD. 

Or maybe "git commit" should always _write_ ORIG_HEAD with the old head, 
so that we can always do an "undo" by doing "git reset --hard ORIG_HEAD" 
regardless of whether the last thing was a "git commit" or a "git pull".

Hmm?

		Linus

Re: bad git pull

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

> Or maybe "git commit" should always _write_ ORIG_HEAD with the old head, 
> so that we can always do an "undo" by doing "git reset --hard ORIG_HEAD" 
> regardless of whether the last thing was a "git commit" or a "git pull".
>
> Hmm?

If we define "git undo" as "Revert the tree to the state one
before the last successfull commit/pull", then overwriting
ORIG_HEAD as you say at the commit time and always using "git
reset --hard ORIG_HEAD" would make sense.

I fail to see the merit of "git undo/unpull/unmerge/..."; mostly
because I have never seen BK and do not benefit from the
familiarity factor at all.  To people without BK experience,
having too many synonyms (e.g. "git undo" does something magical
by feeding "git reset --hard" with ORIG_HEAD) might be just more
noise and confusion.  I can see them asking "why are there two
ways to do identical things?".

However, the reason I am maintaining git is not to make it
useful for _me_, but to make it useful for the kernel people, so
if these BK-like synonyms help them, I'm all for it.  If we are
going to do that, somebody needs to describe what should each
command do in each case in detail, because I do not know BK at
all.

You guys were on BK for how many months, and have been on git
for how many months now?  Do BK-familiarity factor matter, and
will it continue to matter for how long?

Re: bad git pull

[Linus Torvalds]

On Fri, 16 Dec 2005, Junio C Hamano wrote:
> 
> You guys were on BK for how many months, and have been on git
> for how many months now?  Do BK-familiarity factor matter, and
> will it continue to matter for how long?

I don't think it is a huge deal, I suspect that people who used BK have a 
much easier time with git if only because they already understand the 
whole distributed thing and about commits and merges.

That said, I think a lot of newbies might want to have a "git undo", and 
not because of any BK history. Even if it just ends up being nothing but 
shorthand for "git reset --hard ORIG_HEAD".

		Linus

Re: bad git pull

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

> That said, I think a lot of newbies might want to have a "git undo", and 
> not because of any BK history. Even if it just ends up being nothing but 
> shorthand for "git reset --hard ORIG_HEAD".

I agree to this in principle, but I am afraid "git undo" is too
generic and fuzzy a term.  Things you might possibly want to
undo depends on what you did last [*1*].  In most undoable
cases, "reset --hard" is almost right but most likely would
result in information loss.

If we want to really newbie-proof the "undo" command, I think
the hard ones are not the ones that can be approximated with
reset ORIG_HEAD, but other "No way to undo" ones and "Nothing to
undo" ones.

Earlier on the list I gave an overview on merge for an unnamed
person with only an e-mail address, and one thing struck me as
quite hard to explain was that there are two kinds of "merge
failures" --- ones that did not even start the merge and ones
that failed in the middle due to conflicts.  Somebody totally
new to git, after seeing "git pull" to fail in the first kind,
would get scared and type "git undo".  We could prevent doing
damage by making sure we remove ORIG_HEAD in "Nothing to undo"
situations, but if we say "Nothing to undo" when the user types
"git undo" in such a situation, we will surely hear "what do you
mean?  the command said failed to pull and I wanted to recover
from that!".

It also is not clear if it is wise to clear ORIG_HEAD for "No
way to undo" ones.  Doing so would rob useful undo information
from people who know git and expect "No way to undo" ones do not
muck with the existing ORIG_HEAD.

Even for the ones that we would do "reset --hard ORIG_HEAD",
many lose information, and "undo" to me implies "undo only what
the last command messed up", which is not what actually happens.

The word "reset" does not have that connotation -- it takes you
to some defined state, which may be close to what you had before
but may not be exactly the same if you had local changes in your
tree.  HEAD, ORIG_HEAD, and HEAD^ are such defined states you
can go, and the user gives where he wants to go explicitly.
"undo" does not really say where to go and hides halfway what we
do, without doing exactly what the user would expect (and cannot
be implemented fully unless we are willing to take a snapshot of
working tree, I suspect).

[Appendix]

*1* List of commands that a user might want to undo.

A merge or non-merge commit, cherry-pick, and revert::
	reset --hard HEAD^ ;# this can be helped by leaving ORIG_HEAD
                            # but "--hard" is not quite right;
                            # your working tree could have been
                            # dirty at irrelevant paths

A fetch fast-forwarding non-current branch::
	No way to undo -- we do not keep the old information.

A merge, that was fast-forward::
	reset ORIG_HEAD ;# never "--hard" -- your working tree could
                         # have been dirty and in this case
                         # there is no information loss.

A merge attempt, conflicted::
	reset --hard ORIG_HEAD
                         # again, "--hard" is not quite right --
			 # your working tree could have been
                         # dirty at irrelevant paths.

A merge attempt, did not even start because index or tree was dirty::
	Nothing to undo.

A successful checkout (switch branch)::
	No way to undo -- we do not keep the old information.

git-update-index and git-add::
	No way to really undo -- we do not keep the old
	information.  The closest is "git reset" but it reverts
	more than the last operation.

rebase::
	reset --hard ORIG_HEAD

am/applymbox::
        No way to undo -- we do not keep the old information.
			;# this can be helped by leaving ORIG_HEAD

Re: bad git pull

[Nicolas Pitre]

On Sat, 17 Dec 2005, Junio C Hamano wrote:

> Linus Torvalds <torvalds@osdl.org> writes:
> 
> > That said, I think a lot of newbies might want to have a "git undo", and 
> > not because of any BK history. Even if it just ends up being nothing but 
> > shorthand for "git reset --hard ORIG_HEAD".
> 
> I agree to this in principle, but I am afraid "git undo" is too
> generic and fuzzy a term.  Things you might possibly want to
> undo depends on what you did last [*1*].  In most undoable
> cases, "reset --hard" is almost right but most likely would
> result in information loss.

One observation is that ORIG_HEAD should probably be named PREV_HEAD in 
such context to make it more obvious what it is about.


Nicolas

Re: bad git pull

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> One observation is that ORIG_HEAD should probably be named PREV_HEAD in 
> such context to make it more obvious what it is about.

I do not see much difference either way, but I suspect ORIG_HEAD
is pretty much well established by now.

Re: bad git pull

[Nicolas Pitre]

On Sat, 17 Dec 2005, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > One observation is that ORIG_HEAD should probably be named PREV_HEAD in 
> > such context to make it more obvious what it is about.
> 
> I do not see much difference either way,

ORIG suggests "origin" to me, something that was there first, or before 
anything else.  If you want to undo something, you want its "previous" 
state restored relative to the current state, not the absolute previous 
(first) one.

> but I suspect ORIG_HEAD
> is pretty much well established by now.

Well, cogito for one doesn't care at all, and it even doesn't make for 
it to be created/updated.

But still it can remain for what it is now, and PREV_HEAD added for undo 
purpose.

Not a big deal in any case though.


Nicolas

Re: bad git pull

[Linus Torvalds]

On Sat, 17 Dec 2005, Nicolas Pitre wrote:
> 
> ORIG suggests "origin" to me

It's meant to be short for ORIGinal, not ORIGin. That's how I wrote it and 
have always read it ;)

		Linus

Re: bad git pull

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

>> I do not see much difference either way,
>
> ORIG suggests "origin" to me,...

Hmph.

I always thought it was original-head before the operation
happened, which is why I said it is no different from
previous-head.

Re: bad git pull

[Nicolas Pitre]

On Sat, 17 Dec 2005, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> >> I do not see much difference either way,
> >
> > ORIG suggests "origin" to me,...
> 
> Hmph.
> 
> I always thought it was original-head before the operation
> happened, which is why I said it is no different from
> previous-head.

OK I agree.


Nicolas

Re: bad git pull

[Junio C Hamano]

Morten Welinder <mwelinder@gmail.com> writes:

>>  - undo the last commit entirely ("hard reset to previous state"):
>>
>>  - undo the last pull ("bk unpull"): "hard reset to ORIG_HEAD":
>
> It would be outright peachy if Documentation/git-commit.txt and
> Documentation/git-pull.txt mentioned these.  That is certainly
> where I would look first to answer the "what if I screwed up?"
> question.

Yup.  Maybe one line comment at the bottom of these manual pages
pointing at git-reset manual page (which has nice examples
section) would be good enough?

-- >8 --
[PATCH] Examples of resetting.

Morten Welinder says examples of resetting is really about
recovering from botched commit/pulls.  I agree that pointers
from commands that cause a reset to be needed in the first place
would be very helpful.

Also reset examples did not mention "pull/merge" cases.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index b92cf48..8b91f22 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -66,6 +66,10 @@ OPTIONS
 	Update specified paths in the index file before committing.
 
 
+If you make a commit and then found a mistake immediately after
+that, you can recover from it with gitlink:git-reset[1].
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org> and
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 0cac563..4ce799b 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -37,6 +37,11 @@ include::merge-options.txt[]
 include::merge-strategies.txt[]
 
 
+If you tried a merge which resulted in a complex conflicts and
+would want to start over, you can recover with
+gitlink:git-reset[1].
+
+
 HOW MERGE WORKS
 ---------------
 
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index c65ca9a..3a7d385 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -104,6 +104,11 @@ merge the remote `origin` head into the 
 local `master` branch.
 
 
+If you tried a pull which resulted in a complex conflicts and
+would want to start over, you can recover with
+gitlink:git-reset[1].
+
+
 SEE ALSO
 --------
 gitlink:git-fetch[1], gitlink:git-merge[1]
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 0204891..c6a269b 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -111,6 +111,39 @@ remain there.
 changes still in the working tree.
 ------------
 
+Undo a merge or pull::
++
+------------
+$ git pull <1>
+Trying really trivial in-index merge...
+fatal: Merge requires file-level merging
+Nope.
+...
+Auto-merging nitfol
+CONFLICT (content): Merge conflict in nitfol
+Automatic merge failed/prevented; fix up by hand
+$ git reset --hard <2>
+
+<1> try to update from the upstream resulted in a lot of
+conflicts; you were not ready to spend a lot of time merging
+right now, so you decide to do that later.
+<2> "pull" has not made merge commit, so "git reset --hard"
+which is a synonym for "git reset --hard HEAD" clears the mess
+from the index file and the working tree.
+
+$ git pull . topic/branch <3>
+Updating from 41223... to 13134...
+Fast forward
+$ git reset --hard ORIG_HEAD <4>
+
+<3> merge a topic branch into the current branch, which resulted
+in a fast forward.
+<4> but you decided that the topic branch is not ready for public
+consumption yet.  "pull" or "merge" always leaves the original
+tip of the current branch in ORIG_HEAD, so resetting hard to it
+brings your index file and the working tree back to that state,
+and resets the tip of the branch to that commit.
+------------
 
 Author
 ------