On 19/05/2023 22:35, Kristoffer Haugsbakk wrote: > 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. It would be good to get a list of those concepts that could benefit from better explanations. These conceptual views (and misunderstandings) often only emerge after a period of usage. > 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. It's not helped by the default settings for some commands being opinionated as to the workflow of the creators (see also 'pull';-). Other cases are simply 'new' so falling into the 'naming is hard' phlogiston camp (staging area concept comes to mind). > >> +[[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? I had latched on to the 'linearise' (ordered list of commits) perspective which fits both rebase (merge commits dropped) and the history simplification (uninteresting commits dropped) viewpoint, both of which can give people trouble of the missing commits. (see also reply to Junio) > 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. Thanks for the feedback. Especially the first reading perspective. It's all too easy for writers to feel that explaining away a confusion has solved the problem. I'll probably tighten 'flatten' to be for rebase only on the basis of a patch list, without merges. Not sure what to do about the two types of re-list linearisations just yet. -- Philip
