Re: builtin difftool parsing issue

From: Jacob Keller <jacob.keller@gmail.com>
Date: Jan 4, 2017, 01:05 UTC
Message-ID: <CA+P7+xqaOXagpXb53raPcD19uZRgYrOYH6O9pDPsAxE6TsMkvg@mail.gmail.com>
In-Reply-To: <CAGZ79kaMnFUefiMagU82euxjeQdnc9KdgSwyDvkDp--QT-MbCA@mail.gmail.com>

On Tue, Jan 3, 2017 at 10:47 AM, Stefan Beller <sbeller@google.com> wrote:

Show 22 quoted lines

> On Mon, Jan 2, 2017 at 11:05 AM, Paul Sbarra <sbarra.paul@gmail.com> wrote:
>>> I would have expected `git difftool --submodule=diff ...` to work... What
>>> are the problems?
>>
>> The docs for difftool state...
>> "git difftool is a frontend to git diff and accepts the same options
>> and arguments."
>
> I think such a sentence in the man page is dangerous, as nobody
> was caught this issue until now. There have been numerous authors
> and reviewers that touched "diff --submodule=<format>, but as there
> is no back-reference, hinting that the patch is only half done, and the
> difftool also needs to implement such an option.
>
> We should reword the man page either as
>
>   "git difftool is a frontend to git diff and accepts the most(?) options
>   and arguments."
>
> or even be explicit and list the arguments instead. There we could also
> describe differences if any (e.g. the formats available might be different
> for --submodule=<format>)

I agree with updating the documentation. Difftool would require extensive work to support the --submodule format, and I'm not sure it's worth it.

Thanks, Jake