On Fri, Aug 30, 2019 at 3:57 PM Junio C Hamano <gitster@xxxxxxxxx> wrote: > If we want to dedicate one paragraph for each of these options, we > can and should make the introductory paragraph lighter by saying > something like > > Specifies how a merge is handled when the merged-in history > is already a descendant of the current history. `--ff` is > the default unless merging an annotated or signed tag that > is not stored in the `refs/tags/` hierarchy, in which case > `--no-ff` is the default. > > Alternatively, we could sprinkle the actual option name in the first > paragraph and drop the last three paragraphs, while fattening the > description as necessary, e.g. > > Whether to prefer resolving the merge as a fast-forward and > update the branch pointer to match the merged branch without > creating an extra merge commit (`--ff`), never allow fast-forward > and always creating an extra merge commit (`--no-ff`), or to > only allow fast forward updates and reject when a merge > commit needs to be created (`--ff-only`). The default is ... > > I think either approach shown above would reduce the redundancy. I > do not care too deeply which one of these approaches is used myself, > but the redundancy feels a bit disturbing. I have not been paying close attention to this thread, but upon reading your suggested rewrites, I find the lighter paragraph (the first of your options), followed by the three short paragraphs -- each dedicated to a distinct option -- easier to follow and grok. I think that's because the lighter/shorter arrangement keeps the three cases reasonably separate -- thus the reader is able to absorb and understand each distinct option in isolation -- rather than having to manually pluck out the meaning of each option from one long, run-on sentence.
