Re: merge summaries

From: Steffen Prohaska <prohaska@zib.de>
Date: May 20, 2007, 08:17 UTC
Message-ID: <0E590255-A3F4-4D36-B798-80364ACD0D06@zib.de>
In-Reply-To: <7vy7jkva41.fsf@assigned-by-dhcp.cox.net>

On May 19, 2007, at 10:20 PM, Junio C Hamano wrote:

Show 9 quoted lines

> Junio C Hamano <junkio@cox.net> writes:
>
>> As long as you stay as a "pull-only" person, and will never ask
>> the upstream to pull back from you, what first parent log would
>> show would make perfectly good sense.  However, once a pull from
>> you by the upstream happens, the resulting history would get the
>> summary in the merge you did, which is totally unwanted --- the
>> upstream already had those summarized commits long time ago in
>> its history.

Why would the summary of the upstream-to-topic-merge be so harmful? It would not change the summary message of a pull from topic back to the upstream. Af far as I can see, merge commits do not contribute to a summary message. However, when browsing the full log the summary might be distracting because a single commit may be listed at various places, although it was already in the upstream. This is kind of ugly. ...

Show 9 quoted lines

> The criteria to decide "wanted vs unwanted" all boil down to
> essentially the question of who "owns" the history.  Although
> Linus often says that the point of distributed development is
> that nobody is special, at the end of day, once you asked the
> "upstream" to pull from you, your history becomes part of HIS
> history, and at that point, when HE browses the history (which
> he now thinks as HIS history), the summary shows the summary the
> wrong way.  So in that sense, merge.summary is going against the
> philosophy of distributedness.

... I'd say you only "own" the history of a branch along its first-parent-path to the initial commit. This is what you control either by directly committing to the branch or by pulling other branches.

Isn't the history along the first parents especially important because it documents the functionality of the project? If I want to say something about git at a certain point in time, I'd talk about master of the official git repository. "git log --first-parent" in some sense completely describes the history of git. At merges at least a summary of features pulled from topic branches is given.

But this is true not only for the upstream master but for every branch. The first-parent-path of any commit documents (at least in summaries) which features were introduced to the branch at which place. If a topic pulls from upstream, features already available in the upstream are introduced to the topic at this time. Why not summarize this?

Show 10 quoted lines

> The summary message is useful in a very short term (i.e. while
> it is still near the tip of the branch and running "git log"),
> but I think JBF is correct to point out that it is showing a
> shortcoming of our history browsing tools.  The information
> recorded there can easily be reproduced on the fly.  Whenever
> you see a merge commit, you can choose one parent to base your
> view of the history upon (typically the first parent), and
> summarize commits that are reachable from other parents but not
> from that parent (e.g. for a typical two-parent merge, you would
> run "git short-log $commit^1..$commit^2").

I find the summary messages quite useful when browsing merges. The summary allows to quickly locate the branch that was merged at that point. You just look at the list of summaries and locate the mentioned commits in gitk.

Minimal merge messages like "Merge branch 'maint' of URL into maint" are much harder to understand. The branches mentioned in the message do no longer have any meaning. They either ceased to exist or advanced to somewhere else. The URL typically means nothing to me, although it may have meant a lot to the one who pulled at the time of the pull. Such minimal messages do not help browsing history.

It would probably be more useful to name the merged branch by the summary of its head at the time of the merge. For example "Merge branch 'user-manual: reorganize public git repo discussion'" would give more hints where to continue browsing than "Merge branch 'maint' of URL into maint".

- Steffen