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

From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Date: May 19, 2023, 21:35 UTC
Message-ID: <90871d5e-2838-4026-bd83-ab259f7b18dc@app.fastmail.com>
In-Reply-To: <20230513165657.812-1-philipoakley@iee.email>

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.

Show 12 quoted lines

> +[[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