On Wed, Aug 28, 2019 at 12:15 PM Sergey Organov <sorganov@xxxxxxxxx> wrote: > > Hi, > [...] > 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". > 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.) > 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. > + > 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.
