On Mon, Mar 18, 2019 at 03:45:25PM +0900, Junio C Hamano wrote: > Duy Nguyen <pclouds@xxxxxxxxx> writes: > > >> - This is synonymous to the previous form. If <commit> on > >> + This is synonymous to the previous form. However, > >> + users should prefer the previous form over this form > >> + as this form may be more confusing due to the same > >> + notation having a logically conflicting meaning in > >> + linkgit:git-rev-list[1]-ish commands. If <commit> on > >> one side is omitted, it will have the same effect as > >> using HEAD instead. > > > > This is fine as-is. But another option to reduce even more exposure of > > these forms (both <commit>..[<commit>] and <commit>...[<commit>]) is > > to delete these forms in "DESCRIPTION" section and add maybe "EXOTIC > > SYNTAX" (or something) section after "OPTIONS" for just them. > > There is no other way to express A...B (well, short of spelling it > out as "$(git merge-base A B) B"), so while it makes quite a lot of > sense to discourage A..B (simply because .. is unnecessary and can > be replace with a string with one fewer letter in it, namely " "), > I am not sure if it is wise to throw the three-dot form into the > same basket. > Perhaps we could add an option to use the base as a comparison, something like "git diff --compare-base A B" which would mean "git diff $(git merge-base A B) B". If we do this, we could keep feature-parity while deprecating the confusing "range-notation" for diff. Then, we could possibly move .. and ... into a "RANGE-BASED SYNTAX" section and call it a day. I now personally don't think that deprecating it in the code (or even adding a warning) would be worth the effort since the syntax is so ingrained in common usage. However, I believe that we should encourage new users to avoid the range-syntax if possible.
