Subject: Re: [PATCH v2 19/27] gitattributes doc: document multi-line userdiff patterns

From: Junio C Hamano <[email-masked]>
Date: Tue, 16 Feb 2021 16:03:52 -0800

Ævar Arnfjörð Bjarmason  <[email-masked]> writes:

> -There are built-in patterns shipped as part of git itself. A more
> -advanced version of the `tex` pattern discussed above is one of them.
> +Multiple patterns can be supplied by listing them one per line
> +separated by `\n`. They will be matched one at a time from left to
> +right. Do not supply a trailing "\n" for the last pattern. E.g.:

I've always thought that this was modelled after "grep --file=FILE",
where patterns are listed one per line, so "from left to right"
looked a bit funny, at least to me.

If the "do not supply" is because "it would result in giving an
empty string '' as the final pattern, which may not be what you
want", then it is a good idea to spell it out.

> +------------------------
> +[diff "perl"]
> +	xfuncname = "!^=head\n^[^ ]+.*"
> +------------------------
> +
> +Patterns in in a list of multiple that begin with "!" are negated. A

"in in"???

> +matching negated pattern will cause the matched line to be
> +skipped. Use it to skip a later pattern that would otherwise match. It
> +is an error if one or more negated patterns aren't followed by a
> +non-negated pattern.
> +
> +To match a literal "!" at the start of a line, use some other regex
> +construct that will match a literal "!" without "!" being the first
> +character on that line, such as "[!]".
> +
> +If the pattern contains a `$1` capture it will be used instead of the
> +entire matching line (`$0`) to display the hunk header. This can be
> +used e.g. to strip whitespace from the beginning of the line, or to
> +only display the function name as part of a longer function
> +definition.
> +
> +There are built-in patterns shipped as part of git itself, see the
> +full listing below.

Other than the minor nits above, the new text is written very well.