Subject: Re: [PATCH 1/1] doc: Glossary, describe Flattening

From: Junio C Hamano <[email-masked]>
Date: Sun, 14 May 2023 23:59:51 -0700

Philip Oakley <[email-masked]> writes:

> +[[def_flatten]]flatten::
> +	Flattening is a common term for the 'linearizing' of a
> +	selected portion of the <<def_commit_graph_general,commit graph>>.
> +	Flattening may include excluding commits, or rearranging commits,
> +	for the linearized sequence.

Thanks for writing.  I agree that it is a good idea to define the
verb "flatten".  The above I agree with 100%.

I think I was one of the first ones who used the verb in the context
of Git; what I wanted to convey with the verb was what it happens
when you use "am" to rebuild some history made into a series of
patches using the "format-patch" command on a part of the history.

When you have materials from two or more topic branches merged to
your primary integration branch, you would omit the merge commits on
the integration branch and send patches for commits on these topics
in a linearized way.  Applying these patches one by one will result
in a linearlized history, containing patches from all of these
topics (hopefully this is done in a topological order).

> +	In particular, linkgit:git-log[1] and linkgit:git-show[1] have a
> +	range of "History Simplification" techniques that affect which
> +	commits are included, and how they are linearized.

I didn't think (and I do not yet agree, but I may change my mind
after thinking about it further) that the history simplification had
much to do with flattening.

Even after a history is simplified (in the sense how rev-list family
of commands do so), there will still be merge commits left if both
branches contribute something to the end result.  So unless a merge
is to cauterize the side branch (i.e. in order to record the fact
that we already have everything we may want possibly merge to the
integration branch from the side branch, we create a merge commit
that merges the branch but does not change the tree from the parent
commit on the integration branch), history simplification may not
contribute to "excluding" commits.

> +	The default linkgit:git-rebase[1] will drop merge commits when it
> +	flattens history, which also may be unexpected.

I am tempted to suggest dropping ", which also may be unexpected"
here.  When learning a new system, there may be things a learner may
not expect (that is why we have documents), so it is not all that
useful to say "this may not be expected", expecially if we do not
mention why it behaves that way to clear the "unexpected"-ness.

And in this case, the reason may be obvious and it is OK to be left
unsaid---"git rebase" (without an option to keep merge commits) was
designed to be a way to flatten history, and a flattened history by
definition cannot have any merge commits in it.

> +	The two common linearization types are chronological (date-time), and
> +	topological (shape) based orderings. Generation numbering is topological.

Good.