Hi

On Sat, May 13, 2023, at 18:56, Philip Oakley wrote:

Clarify the term 'flatten' and the unexpected effects that the user
may come across, such as discussed in [1] and [2].

Nice to see this effort. I would like more “labels” such as this one to
conceptualize things because sometimes it feels that Git concepts are
just handled bottom-up. Specifically in the case of rebase it seems that
(judging by things like StackOverflow) the pedagogy amounts to
explaining how rebase *works* (without factoring in `--rebase-merges`)
and then explaining how that in turn means that a linearization kind of
“falls out” of that process. And then it seems that you are expected to
remember that bottom-up explanation without putting any kind of label on
it; it’s just what it is.

+[[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.
+	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.
+	The default linkgit:git-rebase[1] will drop merge commits when it
+	flattens history, which also may be unexpected.
+	The two common linearization types are chronological (date-time), and
+	topological (shape) based orderings. Generation numbering is topological.

When I first read this I thought, ah, so this is an explanation of how
linearized rebases are born. But this part also mentions history
viewing. Then I thought: does my history viewing (git-log(1)) work the
same as shuffling around changes into new (and linearized) commits? And
can git-rebase-(1) move between chronological and topological and
ordering? But these two things feel different to me (just a feeling,
UX-wise). So after reading this I am left wondering if different parts
of this paragraph apply *only* to history viewing and to rebase
(“rewriting”).

Again, this is just how I immediately read this paragraph as a user.

-- 
Kristoffer Haugsbakk