Elijah Newren <newren@xxxxxxxxx> writes: > 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. 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. -- Sergey
