if in location with regex capture will reset numeric variable like $1 from captured group but not for named capture group

[n0099@…]

This works:

location ~ /uploads/(?<filePath>.*)$ {
    if ($http_referer !~ "^https://example.com") {
        return 403;
    }
    more_set_headers  'X-Path: $1' 'X-Path2: $filePath' 'X-Referer: $http_referer';
    try_files $uri altUploads/$filePath ../otherUploads/$filePath =404;
}

and this won't:

location ~ /uploads/(.*)$ {
    if ($http_referer !~ "^https://example.com") {
        return  403;
    }
    more_set_headers  'X-Path: $1' 'X-Referer: $http_referer';
    try_files   $uri altUploads/$1 ../otherUploads/$1 =404;
}

The X-Path header doesn't exist in the response header when requesting the latter one.
If we remove the whole if block both variable and headers will be appeared in the response.

location ~ /uploads/(.*)$ {
    more_set_headers  'X-Path: $1' 'X-Referer: $http_referer';
    try_files   $uri altUploads/$1 ../otherUploads/$1 =404;
}

[Maxim Dounin]

Positional captures as available via the $1..$9 variables are from the last executed regular expression, and the last regular expression is in the if condition in the examples provided. That is, these variables are expected to be empty.

In contrast, named captures are explicitly saved into the relevant variables when a regular expression matches, and remain available unless the same variable is explicitly overwritten.

Closing this as a duplicate of #1285, which is a ticket about improving documentation on captures.