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

> 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
```

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