merge-options.txt: clarify meaning of various ff-related options
PATCH 1/1 merge-options.txt: clarify meaning of various ff-related options
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.
---
I noticed this patch sitting around in one of my branches, and noticed it wasn't upstream. I'm pretty sure I submitted it a few months back, but I think it got lost in the cracks. Resubmitting and I'll see if I can do a better job following up on it.
Documentation/merge-options.txt | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-)
Documentation/merge-options.txt +11 -9
@@ -40,20 +40,22 @@ 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 + When the merge can resolve as a fast-forward, do so (only + update the branch pointer to match the merged branch; do not + create a merge commit). When a fast forward update is not + possible, create 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. + Create a merge commit even when the merge could instead resolve + 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. + When possible, resolve the merge as a fast-forward (do not + create a merge commit). When not possible, refuse to merge and + exit with a non-zero status. -S[<keyid>]:: --gpg-sign[=<keyid>]::
Signature · 1 line
2.23.0.38.gfc6987be7e
Quoted 29 lines · Elijah Newren
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 <[email protected]>---
I noticed this patch sitting around in one of my branches, and noticed it wasn't upstream. I'm pretty sure I submitted it a few months back, but I think it got lost in the cracks. Resubmitting and I'll see if I can do a better job following up on it.Documentation/merge-options.txt | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-)Documentation/merge-options.txt +4
-2@@ -40,20 +40,22 @@ 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 + When the merge can resolve as a fast-forward, do so (only + update the branch pointer to match the merged branch; do not + create a merge commit). When a fast forward update is not + possible, create a merge commit. This is the default behavior.
Documentation/merge-options.txt set to `no` at the beginning of them. · line 53
Quoted 10 lines
Documentation/merge-options.txt +4
-4--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. + Create a merge commit even when the merge could instead resolve + 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.
Please notice that virtually all the other cases of --something/--no-something are formatted like this:
--something::
--no-something::
[descriptions]
So, even only for consistency, it seems to be better to have this the same way:
--ff::
--no-ff::
--ff-only::
[descriptions]
that, as a bonus, will make it explicit and crystal clear that these 3 things are alternatives, and thus the last one on the command line takes precedence.
-- Sergey
PATCH v2 1/1 merge-options.txt: clarify meaning of various ff-related options
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.
---
Changes since v1:
* Grouped much like --option/--no-option items are to make it clearer that these are related options, as suggested by Sergey.
Documentation/merge-options.txt | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-)
Documentation/merge-options.txt +20 -13
@@ -39,21 +39,28 @@ set to `no` at the beginning of them. to `MERGE_MSG` before being passed on to the commit machinery in the 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. - +--ff-only:: --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:: + Whether to only allow 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 prefer it when possible. The + default is --ff, except when merging an annotated (and + possibly signed) tag that is not stored in its natural place + in 'refs/tags/' hierarchy (in which case --no-ff is the + default). ++ +With --ff-only, resolve the merge as a fast-forward when possible +(when the merged branch contains the current branch in its history). +When not possible, refuse to merge and exit with a non-zero status. ++ +With --no-ff, create a merge commit in all cases, even when the merge +could instead resolve as a fast-forward. ++ +With --ff, resolve the merge as a fast-forward when possible. When not +possible, create a merge commit. ---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. -S[<keyid>]:: --gpg-sign[=<keyid>]::
Signature · 1 line
2.23.0.9.g568fda2d03
Hi Elijah,
Quoted 7 lines · Elijah Newren
---ff::
Documentation/merge-options.txt +1
-4- When the merge resolves as a fast-forward, only update the branch - pointer, without creating a merge commit. This is the default - behavior. - +--ff-only:: --no-ff::
Documentation/merge-options.txt set to `no` at the beginning of them. · line 49
Quoted 10 lines
Documentation/merge-options.txt +6
-4- 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:: + Whether to only allow 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 prefer it when possible. The + default is --ff, except when merging an annotated (and
It would be great if you'd write this as --ff so that it got monospaced in the rendered documentation. Same thing with no-ff later in this paragraph and a few more times in the next three paragraphs that you're adding.
Documentation/merge-options.txt set to `no` at the beginning of them. · line 52
Quoted 3 lines
Documentation/merge-options.txt +3
-0+ possibly signed) tag that is not stored in its natural place + in 'refs/tags/' hierarchy (in which case --no-ff is the + default).
I'd also write refs/tags/, but I realize that you're just inheriting what is already here. If you'd rather punt on that, that's understood. This whole document could need a look-over with respect to monospacing anyway, but it seems unfortunate to introduce *new* non-monospaced instances, especially for command-line options where it's pretty clear how they should be handled (Documentation/CodingGuidelines, line ~610).
Quoted 5 lines
++
Documentation/merge-options.txt +4
-0+With --ff-only, resolve the merge as a fast-forward when possible +(when the merged branch contains the current branch in its history). +When not possible, refuse to merge and exit with a non-zero status. ++
Documentation/merge-options.txt set to `no` at the beginning of them. · line 56
Quoted 10 lines
Documentation/merge-options.txt +5
-4+With --no-ff, create a merge commit in all cases, even when the merge +could instead resolve as a fast-forward. ++ +With --ff, resolve the merge as a fast-forward when possible. When not +possible, create a merge commit. ---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.
I was sort of expecting these to be listed in the order "--ff, --no-ff, --ff-only", and I see Sergey suggested the same ordering. The way your proposed text reads does make sense though... Would it read as well turning it over and going through the options in the other order? That's the way it is before your patch, so you could argue "but people don't grok that!". What your patch does well is to offer an overview before describing each option in a bit more detail. Would that work with the reversed direction as well (compared to this patch)? Dunno.
I wondered briefly whether it might make sense to float "The default is --no-ff." to the top, but since it's really "The default ... unless so-and-so", it would probably complicate things more than it'd help.
Martin
Hi,
Martin Ågren <[email protected]> writes:
[...]
Quoted 25 lines
Quoted 5 lines
++
Documentation/merge-options.txt +4
-0+With --ff-only, resolve the merge as a fast-forward when possible +(when the merged branch contains the current branch in its history). +When not possible, refuse to merge and exit with a non-zero status. ++Documentation/merge-options.txt set to `no` at the beginning of them. · line 56
Quoted 10 lines
Documentation/merge-options.txt +5
-4+With --no-ff, create a merge commit in all cases, even when the merge +could instead resolve as a fast-forward. ++ +With --ff, resolve the merge as a fast-forward when possible. When not +possible, create a merge commit. ---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.I was sort of expecting these to be listed in the order "--ff, --no-ff, --ff-only", and I see Sergey suggested the same ordering. The way your proposed text reads does make sense though... Would it read as well turning it over and going through the options in the other order? That's the way it is before your patch, so you could argue "but people don't grok that!". What your patch does well is to offer an overview before describing each option in a bit more detail. Would that work with the reversed direction as well (compared to this patch)? Dunno.
Quoted 3 lines
I wondered briefly whether it might make sense to float "The default is
--no-ff." to the top, but since it's really "The default ... unless so-and-so", it would probably complicate things more than it'd help.
Dunno if it helps, but here is what I came up with somewhere in previous discussions:
--ff::
--no-ff::
--ff-only::
When the merge resolves as a fast-forward, only update the branch pointer (without creating a merge commit). When a fast forward update is not possible, create a merge commit. This is the default behavior, unless merging an annotated (and possibly signed) tag that is not stored in its natural place in 'refs/tags/' hierarchy, in which case --no-ff is assumed.
+
With --no-ff create a merge commit even when the merge could instead resolve as a fast-forward.
+
With --ff-only resolve the merge as a fast-forward (never create a merge commit). When fast-forward is not possible, refuse to merge and exit with non-zero status.
Signature · 1 line
Sergey
Hiya,
Quoted 12 lines · Sergey Organov
Quoted 8 lines
I was sort of expecting these to be listed in the order "--ff, --no-ff, --ff-only", and I see Sergey suggested the same ordering. The way your proposed text reads does make sense though... Would it read as well turning it over and going through the options in the other order? That's the way it is before your patch, so you could argue "but people don't grok that!". What your patch does well is to offer an overview before describing each option in a bit more detail. Would that work with the reversed direction as well (compared to this patch)? Dunno.
Dunno if it helps, but here is what I came up with somewhere in previous discussions:
Quoted 16 lines
--ff::
--no-ff::
--ff-only::
When the merge resolves as a fast-forward, only update the branch pointer (without creating a merge commit). When a fast forward update is not possible, create a merge commit. This is the default behavior, unless merging an annotated (and possibly signed) tag that is not stored in its natural place in 'refs/tags/' hierarchy, in which case --no-ff is assumed.
+
With --no-ff create a merge commit even when the merge could instead resolve as a fast-forward.
+
With --ff-only resolve the merge as a fast-forward (never create a merge commit). When fast-forward is not possible, refuse to merge and exit with non-zero status.
I think this could make clear that the first paragraph talks about --ff. I know that we often list --foo and --no-foo, say "This option does bar" and leave it to the reader to figure out which is which. Most of the time, that's fairly obvious though (foo=bar). With this tri-state option, we might be past the point of fair obviousness. Then again, seeing "ff" and "fast forward", it's not /that hard/ to figure out.
Apart from that, this reads well. Of course with the usual caveat of the topic being fresh on my mind, so in general, I'd be more likely to understand what it is I'm reading. ;-)
Martin
Quoted 1 line · Martin Ågren
Hiya,
This one was new to me :-)
Quoted 31 lines · Sergey Organov
Quoted 12 lines
Quoted 8 lines
I was sort of expecting these to be listed in the order "--ff, --no-ff, --ff-only", and I see Sergey suggested the same ordering. The way your proposed text reads does make sense though... Would it read as well turning it over and going through the options in the other order? That's the way it is before your patch, so you could argue "but people don't grok that!". What your patch does well is to offer an overview before describing each option in a bit more detail. Would that work with the reversed direction as well (compared to this patch)? Dunno.
Dunno if it helps, but here is what I came up with somewhere in previous discussions:
Quoted 16 lines
--ff::
--no-ff::
--ff-only::
When the merge resolves as a fast-forward, only update the branch pointer (without creating a merge commit). When a fast forward update is not possible, create a merge commit. This is the default behavior, unless merging an annotated (and possibly signed) tag that is not stored in its natural place in 'refs/tags/' hierarchy, in which case --no-ff is assumed.
+
With --no-ff create a merge commit even when the merge could instead resolve as a fast-forward.
+
With --ff-only resolve the merge as a fast-forward (never create a merge commit). When fast-forward is not possible, refuse to merge and exit with non-zero status.
Quoted 7 lines
I think this could make clear that the first paragraph talks about
--ff. I know that we often list--fooand--no-foo, say "This option does bar" and leave it to the reader to figure out which is which. Most of the time, that's fairly obvious though (foo=bar). With this tri-state option, we might be past the point of fair obviousness. Then again, seeing "ff" and "fast forward", it's not /that hard/ to figure out.
Yeah, I've noticed that myself, but decided to keep it, as this was meant to be a quick re-arrangement of already existing description, and be as short as at all possible, as lengthy descriptions tend to obscure problems.
Being this way it shows how difficult it is to document flawed design. I guess the author of --ff-only would think twice should --ff/--no-ff be originally documented similarly to the rest of 2-way options. At least he'd likely call it --only-ff, as:
--ff::
--no-ff::
--only-ff::
looks much better. Yeah, I do realize all this is historical and such...
Quoted 4 lines
Apart from that, this reads well. Of course with the usual caveat of the topic being fresh on my mind, so in general, I'd be more likely to understand what it is I'm reading. ;-)
... and I'm in even worse position here ;-)
Signature · 1 line
Sergey
Quoted 3 lines · Sergey Organov
Hi,
[...]
Quoted 7 lines
Dunno if it helps, but here is what I came up with somewhere in previous discussions:
--ff::
--no-ff::
--ff-only::
When the merge resolves as a fast-forward, only update the
I think this loose wording (that you just took from the original) is problematic. Saying that a "merge resolves as a fast-forward" seems to imply that there are circumstances when a fast-forward is the only option. An _individual_ can decide to resolve a merge as a fast-forward in some circumstances, but it's certainly not the only choice in any circumstance. If you want to keep this wording short, you could replace "resolves" with "can be resolved".
Quoted 1 line
branch pointer (without creating a merge commit). When a fast
Only update the branch pointer to what? (Yes, I know the original text we were improving left this unclear, but it's worth noting.)
Quoted 4 lines
forward update is not possible, create a merge commit. This is the default behavior, unless merging an annotated (and possibly signed) tag that is not stored in its natural place in 'refs/tags/' hierarchy, in which case --no-ff is assumed.
Maybe it's just me, but I think it takes extra human cycles to figure out that this paragraph is referring just to the --ff case, and that users might not be able to do so until after reading the next 2-3 sentences. While more brief, I think it will cause people to need to read the description for these three options twice, removing most the savings from being shorter. It'd be better if it could be re-worded to not need re-reads.
Quoted 7 lines
+
With --no-ff create a merge commit even when the merge could instead resolve as a fast-forward.
+
With --ff-only resolve the merge as a fast-forward (never create a merge commit). When fast-forward is not possible, refuse to merge and exit with non-zero status.
Something else I was trying to address with my patch that perhaps you can see a different way to tackle: Using the wording "when possible" is probably going to make users wonder when a fast forward is possible; the "can be resolved" wording tweak also makes it more likely they will wonder about this. Another question they will be wondering about is what a fast forward is (which you partially explain). Some basic knowledge of both are probably very useful in helping them decide which option to actually pick. As such, I think trying to explain the answers to these sub-questions will assist them in knowing which option to use. Simply inserting a couple phrases (e.g. "when the merged branch contains the current branch in its history", and "only update the branch pointer *to match the merged branch* and do not create a merge commit") may help a lot.
Anyway, I'll send a v3 addressing Martin's comments; if you've got further suggestions for streamlining or rearranging, though, please do send them along.
Quoted 61 lines · Elijah Newren
Quoted 3 lines · Sergey Organov
Hi,
[...]
Quoted 7 lines
Dunno if it helps, but here is what I came up with somewhere in previous discussions:
--ff::
--no-ff::
--ff-only::
When the merge resolves as a fast-forward, only update theI think this loose wording (that you just took from the original) is problematic. Saying that a "merge resolves as a fast-forward" seems to imply that there are circumstances when a fast-forward is the only option. An _individual_ can decide to resolve a merge as a fast-forward in some circumstances, but it's certainly not the only choice in any circumstance. If you want to keep this wording short, you could replace "resolves" with "can be resolved".
Quoted 1 line
branch pointer (without creating a merge commit). When a fast
Only update the branch pointer to what? (Yes, I know the original text we were improving left this unclear, but it's worth noting.)
Quoted 4 lines
forward update is not possible, create a merge commit. This is the default behavior, unless merging an annotated (and possibly signed) tag that is not stored in its natural place in 'refs/tags/' hierarchy, in which case --no-ff is assumed.
Maybe it's just me, but I think it takes extra human cycles to figure out that this paragraph is referring just to the --ff case, and that users might not be able to do so until after reading the next 2-3 sentences. While more brief, I think it will cause people to need to read the description for these three options twice, removing most the savings from being shorter. It'd be better if it could be re-worded to not need re-reads.
Quoted 7 lines
+
With --no-ff create a merge commit even when the merge could instead resolve as a fast-forward.
+
With --ff-only resolve the merge as a fast-forward (never create a merge commit). When fast-forward is not possible, refuse to merge and exit with non-zero status.Something else I was trying to address with my patch that perhaps you can see a different way to tackle: Using the wording "when possible" is probably going to make users wonder when a fast forward is possible; the "can be resolved" wording tweak also makes it more likely they will wonder about this. Another question they will be wondering about is what a fast forward is (which you partially explain). Some basic knowledge of both are probably very useful in helping them decide which option to actually pick. As such, I think trying to explain the answers to these sub-questions will assist them in knowing which option to use. Simply inserting a couple phrases (e.g. "when the merged branch contains the current branch in its history", and "only update the branch pointer *to match the merged branch* and do not create a merge commit") may help a lot.
Quoted 3 lines
Anyway, I'll send a v3 addressing Martin's comments; if you've got further suggestions for streamlining or rearranging, though, please do send them along.
Thanks for thorough reply!
My version was meant to show how to re-arrange the description preserving original wording as much as possible, so your version should be better, as it addresses other problems as well.
Signature · 1 line
Sergey
PATCH v3 1/1 merge-options.txt: clarify meaning of various ff-related options
In reply to Martin ÅgrenAs 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.
---
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(-)
Documentation/merge-options.txt +18 -12
@@ -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>]::
Signature · 1 line
2.23.0.3.g93492fb5e6.dirty
Quoted 18 lines · Elijah Newren
Documentation/merge-options.txt +8
-0@@ -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).
Documentation/merge-options.txt set to `no` at the beginning of them. · line 62
Quoted 10 lines
Documentation/merge-options.txt +10
-0++ +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.
Quoted 21 lines · Junio C Hamano
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.
--ffis the default unless merging an annotated or signed tag that is not stored in therefs/tags/hierarchy, in which case--no-ffis 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 ...
Quoted 3 lines
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.
PATCH v4 1/1 merge-options.txt: clarify meaning of various ff-related options
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.
---
Changes since v3:
* Shorten the leading paragraph, as suggested by Junio (and Eric).
Documentation/merge-options.txt | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-)
Documentation/merge-options.txt +16 -12
@@ -40,20 +40,24 @@ 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. + 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 (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`, when possible resolve the merge as a fast-forward (only +update the branch pointer to match the merged branch; do not create a +merge commit). When not possible (when the merged-in history is not a +descendant of the current history), 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>]::
Signature · 1 line
2.23.0.39.gf92d9de5c3
Quoted 11 lines · Martin Ågren
Documentation/merge-options.txt set to `no` at the beginning of them. · line 49
Quoted 6 lines
+--ff::
Documentation/merge-options.txt +5
-0+ Whether to only allow 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 prefer it when possible. The + default is --ff, except when merging an annotated (andIt would be great if you'd write this as
--ffso that it got monospaced in the rendered documentation. ...
I'd also writerefs/tags/, but I realize that you're just inheriting what is already here. ...
These comments may sound nitpicky at times, and some parts may be beyond the scope of the discussion on the patch and are better left for a later time, but the consistency is valuable.
Thanks for mentioning them; and it would be appreciated if these suggesions are followed through after the dust settles.
Quoted 15 lines · Junio C Hamano
Quoted 11 lines · Martin Ågren
Documentation/merge-options.txt set to `no` at the beginning of them. · line 49
Quoted 6 lines
+--ff::
Documentation/merge-options.txt +5
-0+ Whether to only allow 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 prefer it when possible. The + default is --ff, except when merging an annotated (andIt would be great if you'd write this as
--ffso that it got monospaced in the rendered documentation. ...
I'd also writerefs/tags/, but I realize that you're just inheriting what is already here. ...
Quoted 6 lines
These comments may sound nitpicky at times, and some parts may be beyond the scope of the discussion on the patch and are better left for a later time, but the consistency is valuable.
Thanks for mentioning them; and it would be appreciated if these suggesions are followed through after the dust settles.
I'm confused; these suggestions were incorporated into V3 already. Am I misunderstanding something here?
(But yes, I agree that Martin's reviews are valuable.)
Quoted 20 lines · Elijah Newren
Quoted 19 lines · Junio C Hamano
Quoted 11 lines · Martin Ågren
Documentation/merge-options.txt set to `no` at the beginning of them. · line 49
Quoted 6 lines
+--ff::
Documentation/merge-options.txt +5
-0+ Whether to only allow 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 prefer it when possible. The + default is --ff, except when merging an annotated (andIt would be great if you'd write this as
--ffso that it got monospaced in the rendered documentation. ...
I'd also writerefs/tags/, but I realize that you're just inheriting what is already here. ...These comments may sound nitpicky at times, and some parts may be beyond the scope of the discussion on the patch and are better left for a later time, but the consistency is valuable.
Quoted 5 lines
Quoted 2 lines
Thanks for mentioning them; and it would be appreciated if these suggesions are followed through after the dust settles.
I'm confused; these suggestions were incorporated into V3 already. Am I misunderstanding something here?
I was assuming that outside the context of the patch there also are the same malformatted reference to refs/blah and --option "you're just inheriting", which would be cleaned up outside of this topic after the dust settles, if the suggestions are followed through.