Re: [PATCH] user-manual: Talk about tracking third-party snapshots

[Junio C Hamano <gitster@pobox.com>]

Michael Smith <msmith@cbnco.com> writes:

> +You can fix situations like these by doing a merge that isn't really a
> +merge, using the "ours" merge strategy. Look through the history on the
> +third-party branch and try to find the exact commit that matches the
> +last snapshot you imported. Often there's a tag close to the commit, or
> +on the commit, if you're lucky--but don't trust it blindly; check the
> +diffs. Check out your local branch and tell Git about the relationship:
> +
> +------------------------------------------------
> +$ git remote add upstreamgit git://upstream.org/project.git
> +$ git fetch upstreamgit
> +$ git tag
> +v1.0
> +v1.1
> +v1.2
> +$ git checkout master
> +$ git merge --strategy=ours \
> +    -m "Tie old v1.1 into our history by merging with strategy=ours." \
> +    v1.1
> +------------------------------------------------
> +
> +You'll see the branches merge together in `gitk --all` or `git
> +show-branch master upstreamgit/master`.  Now you'll be able to merge any
> +changes from the remote branch since v1.1 with `git merge
> +upstreamgit/master`.
> +

This would work only when your 'master' happens to be at v1.1
(and identical to it) isn't it?  Which means that as an example
it will be of very limited scope.

People would want to know "But my 'master' is _not_ at v1.1 but
is _based_ on v1.1.  How would I handle that case?" and the
above does not answer that question.

Even worse, most people are probably not careful enough to ask
the above question, but just say "Heh, my 'master' is based on
v1.1, so I'll blindly follow that example to bind the histories
together".

I did not find any technical problem in the other parts of your
description, but I did not read the resulting document from
cover to cover, so I do not know if your change fits in the
entire organization of the document very well.