Re: [PATCH] Re: push: point to 'git pull' and 'git push --force' in case of non-fast forward

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 6, 2009, 21:32 UTC
Message-ID: <7vprb8d3xe.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20090806211610.GB12924@vidovic>

Nicolas Sebrecht <nicolas.s.dev@gmx.fr> writes:

Show 16 quoted lines

>> +Note about fast-forwards
>> +------------------------
>> +
>> +When an update changes a branch (or more in general, a ref) that used to
>> +point at commit A to point at another commit B, it is called a
>> +fast-forward update if and only if B is a descendant of A.
>> +
>> +In a fast-forward update from A to B, the set of commits that the original
>> +commit A built on top of is a subset of the commits the new commit B
>> +builds on top of.  Hence, it does not lose any history.
>> +
>> +In contrast, a non-fast-forward update will lose history.
>
> I believe that this sentence a bit too much scaring for the beginner.
> There are two kinds of update (push and pull). We loose history only
> when pushing.

Three points that makes me think your suggested update is not appropriate are:

 (1) This patch is about git-push documentation;

 (2) The opposite of git-push is git-fetch, not git-pull; and a non
     fast-forward fetch does lose history if you start building on a
     now-rewound tip of the remote tracking branch; and

 (3) We _do_ want this section to be scary.  We want the readers to be
     fully aware of the implications before tempting them with the --force
     option.

Show 24 quoted lines

>> +Alternatively, you can rebase your change between X and B on top of A,
>> +with "git pull --rebase", and push the result back.  The rebase will
>> +create a new commit D that builds the change between X and B on top of
>> +A.
>> +
>> +----------------
>> +
>> +      B   D
>> +     /   /
>> + ---X---A
>> +
>> +----------------
>
> Wouldn't "git pull --rebase" loose B? Shouldn't we have this
>
>   ----------------
>   
>             D
>            /
>    ---X---A
>   
>   ----------------
>
> instead?

This makes B _loose_ (or, dangling), but does not _lose_ it. It is still reachable from the reflog.

We could choose to not draw it for simplicity, or we could annotate it like this for completeness (and to give a warm-fuzzy feeling to the reader that nothing is lost).

----------------

       branch@{1} (reachable from reflog)
             branch
      B      D
     /      /
 ---X------A

----------------

I don't know which is better. If we were printing in colours in the documentation, I would keep B but draw it in light gray.