ancestor and descendant ~ clarification needed

ancestor and descendant ~ clarification needed

[Xue Fuqiao]

Hi,

In Documentation/user-manual.txt:

   In the following, we say that commit X is "reachable" from commit Y
   if commit X is an ancestor of commit Y.  Equivalently, you could say
   that Y is a descendant of X, or that there is a chain of parents
   leading from commit Y to commit X.
[...]
   However, if the current branch is a descendant of the other--so every
   commit present in the one is already contained in the other--then Git
   just performs a "fast-forward"; the head of the current branch is
   moved forward to point at the head of the merged-in branch, without
   any new commits being created.

I'm a Git newbie.  According to my understanding, the "descendant" in
the second paragraph above should be "ancestor".  I attempt to represent
my understanding using the following diagram (please see it in a
monospaced font):

................................................

         o--o--o <-- Branch A
        /
 o--o--o <-- master

................................................

"master" is the current branch, and (as I understand it) it is an
ancestor of "Branch A", because there is a chain of parents leading from
"Branch A" to master.  So "Branch A" (i.e., "the other" branch, or the
"merged-in" branch) is a descendant of master.  I even set up a test
repository and attempted to test the above diagram with "git merge-base
--is-ancestor" (and "echo $?"), but it seems to me that the master
branch is *not* a descendant of "Branch A".

I hope you can understand my words here (English is not my native
language).  Can anyone point me in the right direction (what am I
missing)?

Re: ancestor and descendant ~ clarification needed

[Etienne Girard]

Hello,

I think you're right, branch A is a descendant of master. We could
change the misleading sentence to "However, if the current branch is a
descendant of the other - if its head is a descendant of the other's
head - [...]", to link back to the definition of descendant for
commits.

2015-10-22 11:06 GMT+02:00 Xue Fuqiao <xfq.free@gmail.com>:
> Hi,
>
> In Documentation/user-manual.txt:
>
>    In the following, we say that commit X is "reachable" from commit Y
>    if commit X is an ancestor of commit Y.  Equivalently, you could say
>    that Y is a descendant of X, or that there is a chain of parents
>    leading from commit Y to commit X.
> [...]
>    However, if the current branch is a descendant of the other--so every
>    commit present in the one is already contained in the other--then Git
>    just performs a "fast-forward"; the head of the current branch is
>    moved forward to point at the head of the merged-in branch, without
>    any new commits being created.
>
> I'm a Git newbie.  According to my understanding, the "descendant" in
> the second paragraph above should be "ancestor".  I attempt to represent
> my understanding using the following diagram (please see it in a
> monospaced font):
>
> ................................................
>
>          o--o--o <-- Branch A
>         /
>  o--o--o <-- master
>
> ................................................
>
> "master" is the current branch, and (as I understand it) it is an
> ancestor of "Branch A", because there is a chain of parents leading from
> "Branch A" to master.  So "Branch A" (i.e., "the other" branch, or the
> "merged-in" branch) is a descendant of master.  I even set up a test
> repository and attempted to test the above diagram with "git merge-base
> --is-ancestor" (and "echo $?"), but it seems to me that the master
> branch is *not* a descendant of "Branch A".
>
> I hope you can understand my words here (English is not my native
> language).  Can anyone point me in the right direction (what am I
> missing)?
> --
> 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

Re: ancestor and descendant ~ clarification needed

[Junio C Hamano]

Xue Fuqiao <xfq.free@gmail.com> writes:

> In Documentation/user-manual.txt:
>
>    In the following, we say that commit X is "reachable" from commit Y
>    if commit X is an ancestor of commit Y.  Equivalently, you could say
>    that Y is a descendant of X, or that there is a chain of parents
>    leading from commit Y to commit X.
> [...]
>    However, if the current branch is a descendant of the other--so every
>    commit present in the one is already contained in the other--then Git
>    just performs a "fast-forward"; the head of the current branch is
>    moved forward to point at the head of the merged-in branch, without
>    any new commits being created.

Yeah, that is the other way around.

 (1) If the current branch is a descendant of the other--so every
     commit present in the other branch is already contained in the
     current branch--then merging the other branch into the current
     branch is a no-op "Already up-to-date!".

 (2) If the current branch is an ancestor of the other--so every
     commit present in the current branch is already contained in
     the other branch--then merging the other branch into the
     current branch can be fast-forwarded, by moving the tip of the
     current branch to point at the commit at the tip of the other
     branch, and by default Git does so, instead of creating an
     unnecessary merge.

Re: ancestor and descendant ~ clarification needed

[Xue Fuqiao]

Hi Junio,

On Fri, Oct 23, 2015 at 4:22 AM, Junio C Hamano <gitster@pobox.com> wrote:

> Yeah, that is the other way around.
>
>  (1) If the current branch is a descendant of the other--so every
>      commit present in the other branch is already contained in the
>      current branch--then merging the other branch into the current
>      branch is a no-op "Already up-to-date!".
>
>  (2) If the current branch is an ancestor of the other--so every
>      commit present in the current branch is already contained in
>      the other branch--then merging the other branch into the
>      current branch can be fast-forwarded, by moving the tip of the
>      current branch to point at the commit at the tip of the other
>      branch, and by default Git does so, instead of creating an
>      unnecessary merge.

I see.  Thank you.  What do you think about the following minor patch
for user-manual.txt?  I can send a more formal one using format-patch
and send-email if needed.

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 1b7987e..d68df13 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1431,11 +1431,11 @@ differently.  Normally, a merge results in a
merge commit, with two
 parents, one pointing at each of the two lines of development that
 were merged.

-However, if the current branch is a descendant of the other--so every
-commit present in the one is already contained in the other--then Git
-just performs a "fast-forward"; the head of the current branch is moved
-forward to point at the head of the merged-in branch, without any new
-commits being created.
+However, if the current branch is an ancestor of the other--so every commit
+present in the current branch is already contained in the other
branch--then Git
+just performs a "fast-forward"; the head of the current branch is moved forward
+to point at the head of the merged-in branch, without any new commits being
+created.

 [[fixing-mistakes]]
 Fixing mistakes

Re: ancestor and descendant ~ clarification needed

[Junio C Hamano]

Xue Fuqiao <xfq.free@gmail.com> writes:

> Hi Junio,
>
> On Fri, Oct 23, 2015 at 4:22 AM, Junio C Hamano <gitster@pobox.com> wrote:
>
>> Yeah, that is the other way around.
>>
>>  (1) If the current branch is a descendant of the other--so every
>>      commit present in the other branch is already contained in the
>>      current branch--then merging the other branch into the current
>>      branch is a no-op "Already up-to-date!".
>>
>>  (2) If the current branch is an ancestor of the other--so every
>>      commit present in the current branch is already contained in
>>      the other branch--then merging the other branch into the
>>      current branch can be fast-forwarded, by moving the tip of the
>>      current branch to point at the commit at the tip of the other
>>      branch, and by default Git does so, instead of creating an
>>      unnecessary merge.
>
> I see.  Thank you.  What do you think about the following minor patch
> for user-manual.txt?

While the updated text is more correct than the original, I do not
know if that is sufficient, or we would also want to mention the
"Already up-to-date!" case here while at it.

> -However, if the current branch is a descendant of the other--so every
> -commit present in the one is already contained in the other--then Git
> -just performs a "fast-forward"; the head of the current branch is moved
> -forward to point at the head of the merged-in branch, without any new
> -commits being created.
> +However, if the current branch is an ancestor of the other--so every commit
> +present in the current branch is already contained in the other
> branch--then Git
> +just performs a "fast-forward"; the head of the current branch is moved forward
> +to point at the head of the merged-in branch, without any new commits being
> +created.

Re: ancestor and descendant ~ clarification needed

[Xue Fuqiao]

On Sat, Oct 24, 2015 at 12:56 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> I see.  Thank you.  What do you think about the following minor patch
>> for user-manual.txt?
>
> While the updated text is more correct than the original, I do not
> know if that is sufficient, or we would also want to mention the
> "Already up-to-date!" case here while at it.

I thought about that, and IMHO it's not needed.  The section name is
"Fast-forward merges" and intends to introduce the "fast-forward"
concept, which is irrelevant to "Already up-to-date!".  Although the
"Already up-to-date!" case isn't mentioned all over the manual, it's
pretty clear to me (as someone who isn't quite familiar with Git).

>> -However, if the current branch is a descendant of the other--so every
>> -commit present in the one is already contained in the other--then Git
>> -just performs a "fast-forward"; the head of the current branch is moved
>> -forward to point at the head of the merged-in branch, without any new
>> -commits being created.
>> +However, if the current branch is an ancestor of the other--so every commit
>> +present in the current branch is already contained in the other
>> branch--then Git
>> +just performs a "fast-forward"; the head of the current branch is moved forward
>> +to point at the head of the merged-in branch, without any new commits being
>> +created.

Re: ancestor and descendant ~ clarification needed

[Junio C Hamano]

Xue Fuqiao <xfq.free@gmail.com> writes:

> On Sat, Oct 24, 2015 at 12:56 AM, Junio C Hamano <gitster@pobox.com> wrote:
>>> I see.  Thank you.  What do you think about the following minor patch
>>> for user-manual.txt?
>>
>> While the updated text is more correct than the original, I do not
>> know if that is sufficient, or we would also want to mention the
>> "Already up-to-date!" case here while at it.
>
> I thought about that, and IMHO it's not needed.  The section name is
> "Fast-forward merges" and intends to introduce the "fast-forward"
> concept, which is irrelevant to "Already up-to-date!".

Okay.