On Sun, Mar 17, 2019 at 6:09 PM Denton Liu <[email protected]> wrote: > > The documentation used to consider > > git diff <commit> <commit> > > and > > git diff <commit>..<commit> > > to be equal counterparts. However, rev-list-ish commands also use the > <commit>..<commit> notation, but in a logically conflicting manner which > was confusing for some users (including me!). > > Deprecating the notation entirely is not really an option because it > would be an arduous process without much end-value. In addition, there > are some valid use-cases that we don't want to break. > > Document the preference of the first form so that future confusion can > be minimised. > > Signed-off-by: Denton Liu <[email protected]> > --- > > Thanks all on your feedback on the discussion thread[1]! I opted for > just the documentation-only route so we don't break any valid use-cases. > > [1]: > https://public-inbox.org/git/[email protected]/ > > Documentation/git-diff.txt | 6 +++++- > 1 file changed, 5 insertions(+), 1 deletion(-) > > diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt > index 72179d993c..10c7a2220c 100644 > --- a/Documentation/git-diff.txt > +++ b/Documentation/git-diff.txt > @@ -63,7 +63,11 @@ two blob objects, or changes between two files on disk. > > 'git diff' [<options>] <commit>..<commit> [--] [<path>...]:: > > - 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. > -- > 2.21.0.512.g57bf1b23e1 > -- Duy
