| Message ID | 20190828225712.20041-1-newren@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v3] merge-options.txt: clarify meaning of various ff-related options | expand |
Elijah Newren <newren@gmail.com> writes: > diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt > index 79a00d2a4a..ed3804650b 100644 > --- a/Documentation/merge-options.txt > +++ b/Documentation/merge-options.txt > @@ -40,20 +40,26 @@ set to `no` at the beginning of them. > case of a merge conflict. > > --ff:: > --no-ff:: > --ff-only:: > + Whether to prefer resolving the merge as a fast forward (only > + updating the branch pointer to match the merged branch and not > + creating a merge commit), to never allow it (always creating a > + merge commit), or to only allow fast forward updates. The > + default is `--ff`, except when merging an annotated (and > + possibly signed) tag that is not stored in its natural place > + in the `refs/tags/` hierarchy (in which case `--no-ff` is > + assumed). > ++ > +With `--ff`, resolve the merge as a fast-forward when possible (when the > +merged branch contains the current branch in its history). When not > +possible, create a merge commit. > ++ > +With `--no-ff`, create a merge commit in all cases, even when the merge > +could instead be resolved as a fast-forward. > ++ > +With `--ff-only`, resolve the merge as a fast-forward when possible. > +When not possible, refuse to merge and exit with a non-zero status. I cannot shake the feeling that the above redundantly repeats the same thing twice. 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. Thanks.
On Fri, Aug 30, 2019 at 3:57 PM Junio C Hamano <gitster@pobox.com> 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.
diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 79a00d2a4a..ed3804650b 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -40,20 +40,26 @@ set to `no` at the beginning of them. case of a merge conflict. --ff:: - When the merge resolves as a fast-forward, only update the branch - pointer, without creating a merge commit. This is the default - behavior. - --no-ff:: - Create a merge commit even when the merge resolves as a - fast-forward. This is the default behaviour when merging an - annotated (and possibly signed) tag that is not stored in - its natural place in 'refs/tags/' hierarchy. - --ff-only:: - Refuse to merge and exit with a non-zero status unless the - current `HEAD` is already up to date or the merge can be - resolved as a fast-forward. + Whether to prefer resolving the merge as a fast forward (only + updating the branch pointer to match the merged branch and not + creating a merge commit), to never allow it (always creating a + merge commit), or to only allow fast forward updates. The + default is `--ff`, except when merging an annotated (and + possibly signed) tag that is not stored in its natural place + in the `refs/tags/` hierarchy (in which case `--no-ff` is + assumed). ++ +With `--ff`, resolve the merge as a fast-forward when possible (when the +merged branch contains the current branch in its history). When not +possible, create a merge commit. ++ +With `--no-ff`, create a merge commit in all cases, even when the merge +could instead be resolved as a fast-forward. ++ +With `--ff-only`, resolve the merge as a fast-forward when possible. +When not possible, refuse to merge and exit with a non-zero status. -S[<keyid>]:: --gpg-sign[=<keyid>]::
As discovered on the mailing list, some of the descriptions of the ff-related options were unclear. Try to be more precise with what these options do. Signed-off-by: Elijah Newren <newren@gmail.com> --- Changes since v2: * reordered the options * typeset the option flags differently to ensure they are monospace in the rendered documentation Documentation/merge-options.txt | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-)