Re: [PATCH] Keep git-external-diff usage text from executing

> On Oct 22, 2026, at 14:53, Chao Li <li(dot)evan(dot)chao(at)gmail(dot)com> wrote:
>
>
>
>> On Oct 21, 2026, at 12:16, 夏侯莯昍 <xiahoumuxuan(at)gmail(dot)com> wrote:
>>
>> Hi,
>>
>> src/tools/git-external-diff is a Bash script, but its usage text is enclosed
>> in the Perl POD markers =comment and =cut. Bash therefore tries to execute
>> the prose and the embedded git config/git diff examples on each invocation.
>>
>> The attached patch changes only those two delimiters to a quoted no-op
>> here-document. This preserves the text literally, without executing it or
>> performing shell expansions, and leaves the actual diff code unchanged.
>>
>> The patch was prepared against master at
>> 3cde90ecc5f85e7c6cb9fba29d473b2f6dd40ee1.
>>
>> Validation:
>> - bash -n and git diff --check pass.
>> - The attached standalone test passes all three cases with the patch;
>> all three fail against the unmodified master file. It records Git calls
>> rather than allowing the documentation examples to change configuration
>> or invoke another diff. It covers unchanged content, context diffs with
>> spaced paths, and custom DIFF_OPTS=-u.
>> - A separate integration check using real Git in an isolated temporary
>> repository produces the expected context diff and leaves configuration
>> unchanged.
>>
>> Run the standalone test with an explicit path to the file under test:
>> python3 test_git_external_diff.py /path/to/postgres/src/tools/git-external-diff
>>
>> This was originally proposed to IvorySQL; its maintainers asked that this
>> inherited tool change be sent upstream first:
>> https://github.com/IvorySQL/IvorySQL/pull/2510
>>
>> AI assistance was used to prepare the patch, tests, and this message.
>> The reported validation results are from actual local runs.
>>
>> Regards,
>> zmuxuny
>> <v1-0001-Make-git-external-diff-usage-text-a-shell-comment.patch><test_git_external_diff.py><test_git_integration.py>
>
> The fix looks good to me.
>
> Per PG News on May 27 2018 [1], not sure how many folks still use this tool:
> ```
> - Preserve information on use of git-external-diff. Now that the Working with
> git wiki page no longer suggests producing context diffs, we should preserve
> the information on how to use git-external-diff for those people who want to
> view context format diffs. The most obvious place is in the script itself, so
> that's what's done here.
> https://git.postgresql.org/pg/commitdiff/4431c94c3606ab54594b15ad89c7e71e46b4fb6a
> ```

Oops, missed the reference [1].

[1] https://www.postgresql.org/message-id/20180527190517.GA29473%40fetter.org

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/