git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH v3] merge-options.txt: clarify meaning of various ff-related options

From
Eric Sunshine <sunshine@sunshineco.com>
Date
Aug 30, 2019, 20:16 UTC
Message-ID
<CAPig+cRPGY4wEbUin3mDj0+nHigtndNWj6o-FHjKeCzgqY9Y5Q@mail.gmail.com>
In-Reply-To
<xmqq7e6uxw7r.fsf@gitster-ct.c.googlers.com>
On Fri, Aug 30, 2019 at 3:57 PM Junio C Hamano <gitster@pobox.com> wrote:
Show 24 quoted lines
> 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.

Previous: Junio C HamanoNext: Elijah Newren
Message 12 of 16 in “merge-options.txt: clarify meaning of various ff-related options”
  1. merge-options.txt: clarify meaning of various ff-related optionsElijah Newren, Aug 28, 2019
  2. Sergey OrganovAug 28, 2019
  3. merge-options.txt: clarify meaning of various ff-related optionsElijah Newren, Aug 28, 2019
  4. Martin ÅgrenAug 28, 2019
  5. Sergey OrganovAug 28, 2019
  6. Martin ÅgrenAug 28, 2019
  7. Sergey OrganovAug 29, 2019
  8. Elijah NewrenAug 28, 2019
  9. Sergey OrganovAug 29, 2019
  10. merge-options.txt: clarify meaning of various ff-related optionsElijah Newren, Aug 28, 2019
  11. Junio C HamanoAug 30, 2019
  12. Eric SunshineAug 30, 2019
  13. merge-options.txt: clarify meaning of various ff-related optionsElijah Newren, Aug 31, 2019
  14. Junio C HamanoAug 30, 2019
  15. Elijah NewrenAug 30, 2019
  16. Junio C HamanoAug 30, 2019

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.