From: Philip Oakley <philipoakley@iee.email>
To: Kristoffer Haugsbakk <code@khaugsbakk.name>
Cc: Johannes Schindelin <Johannes.Schindelin@gmx.de>,
alexhenrie24@gmail.com, git@vger.kernel.org,
Elijah Newren <newren@gmail.com>,
Phillip Wood <phillip.wood123@gmail.com>,
tao@klerks.biz, Junio C Hamano <gitster@pobox.com>
Subject: Re: [PATCH 1/1] doc: Glossary, describe Flattening
Date: Sat, 27 May 2023 17:46:29 +0100 [thread overview]
Message-ID: <5bca2615-21e6-34fa-bb22-519acd74cbbd@iee.email> (raw)
In-Reply-To: <90871d5e-2838-4026-bd83-ab259f7b18dc@app.fastmail.com>
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
prev parent reply other threads:[~2023-05-27 16:46 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-02-20 3:32 [PATCH 1/2] rebase: add a --rebase-merges=drop option Alex Henrie
2023-02-20 3:32 ` [PATCH 2/2] rebase: add a config option for --rebase-merges Alex Henrie
2023-02-20 9:38 ` Phillip Wood
2023-02-20 17:06 ` Alex Henrie
2023-02-20 16:41 ` Elijah Newren
2023-02-20 9:31 ` [PATCH 1/2] rebase: add a --rebase-merges=drop option Phillip Wood
2023-02-20 17:03 ` Alex Henrie
2023-02-20 21:42 ` Junio C Hamano
2023-02-21 16:08 ` Philip Oakley
2023-02-21 18:42 ` Junio C Hamano
2023-05-13 16:51 ` [PATCH 0/1] cover-letter: flatten Philip Oakley
2023-05-13 16:56 ` [PATCH 1/1] doc: Glossary, describe Flattening Philip Oakley
2023-05-15 6:59 ` Junio C Hamano
2023-05-27 16:28 ` Philip Oakley
2023-05-19 21:35 ` Kristoffer Haugsbakk
2023-05-27 16:46 ` Philip Oakley [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5bca2615-21e6-34fa-bb22-519acd74cbbd@iee.email \
--to=philipoakley@iee.email \
--cc=Johannes.Schindelin@gmx.de \
--cc=alexhenrie24@gmail.com \
--cc=code@khaugsbakk.name \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=newren@gmail.com \
--cc=phillip.wood123@gmail.com \
--cc=tao@klerks.biz \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).