From: Rich Bowen Date: Fri, 15 May 2026 16:21:03 +0000 (+0000) Subject: Consolidate per-directory rewrite notes: remove duplication between mod_rewrite.xml... X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=f6b5339b1fa725625e796cbed0e9dd869ce16c74;p=thirdparty%2Fapache%2Fhttpd.git Consolidate per-directory rewrite notes: remove duplication between mod_rewrite.xml and rewrite/htaccess.xml The large "Per-directory Rewrites" note block in mod_rewrite.xml duplicated content already covered (and better explained) in rewrite/htaccess.xml. Replace it with a short link to the guide. Migrate the useful tips that were unique to that block into rewrite/htaccess.xml: - ^/ never matches in per-directory context (path-stripping section) - Use %{REQUEST_URI} to match the full URL-path, with example - / are unsupported contexts (new section) - follows directory context rules (new section) Part of: https://bz.apache.org/bugzilla/show_bug.cgi?id=70045 git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1934228 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml index 44f5de8acb..32769edd37 100644 --- a/docs/manual/mod/mod_rewrite.xml +++ b/docs/manual/mod/mod_rewrite.xml @@ -1132,70 +1132,13 @@ RewriteRule "^/$" "/homepage.std.html" [L] <glossary ref="perdirectory">Per-directory</glossary> Rewrites -
    -
  • The rewrite engine may be used in .htaccess files and in Directory sections, with some additional -complexity.
    • - -
  • To enable the rewrite engine in this context, you need to set -RewriteEngine On and -at least one of the FollowSymLinks or -SymLinksIfOwnerMatch -Options must be enabled. Note -that these options cannot be set in a distributed configuration file -(.htaccess) unless -AllowOverride permits it -in the server configuration.
    • - -
  • See the RewriteBase -directive for more information regarding what prefix will be added back to -relative substitutions.
    • - -
  • If you wish to match against the full URL-path in a -per-directory context -RewriteRule, use the %{REQUEST_URI} variable in -a RewriteCond.
    • - -
  • The removed prefix always ends with a slash, meaning the matching occurs against a string which -never has a leading slash. Therefore, a Pattern with ^/ never -matches in per-directory context.
    • - -
  • Although rewrite rules are syntactically permitted in Location and Files sections -(including their regular expression counterparts), this -should never be necessary and is unsupported. A likely feature -to break in these contexts is relative substitutions.
    • - -
  • The If blocks -follow the rules of the directory context.
    • - -
  • By default, mod_rewrite overrides rules when -merging sections belonging to the same context. The RewriteOptions directive can change this behavior, -for example using the Inherit setting.
    • - -
  • The RewriteOptions also regulates the -behavior of sections that are stated at the same nesting level of the configuration. In the -following example, by default only the RewriteRules stated in the second -If block -are considered, since the first ones are overridden. Using RewriteOptions Inherit forces mod_rewrite to merge the two -sections and consider both set of statements, rather than only the last one.
    • -
- - -<If "true"> - # Without RewriteOptions Inherit, this rule is overridden by the next - # section and no redirect will happen for URIs containing 'foo' - RewriteRule foo http://example.com/foo [R] -</If> -<If "true"> - RewriteRule bar http://example.com/bar [R] -</If> - - +

+Using rewrite rules in per-directory +context requires special attention to how patterns are +matched and how rule inheritance works. See the +Per-directory Rewrites +guide for complete details. +

For information on regular diff --git a/docs/manual/rewrite/htaccess.xml b/docs/manual/rewrite/htaccess.xml index 2e42ab9bc9..02ddd88340 100644 --- a/docs/manual/rewrite/htaccess.xml +++ b/docs/manual/rewrite/htaccess.xml @@ -131,6 +131,24 @@ determines what URL-path prefix is prepended. This subrequest mechanism is also why rules can loop — see below.

+ +

Because the directory prefix (including the trailing +slash) is stripped before matching, patterns in +per-directory context +will never match a leading slash. A pattern +beginning with ^/ will never match in this +context.

+ +

If you need to match against the full original +URL-path (including the directory prefix), use +%{REQUEST_URI} in a +RewriteCond:

+ + +RewriteCond "%{REQUEST_URI}" "^/admin/" +RewriteRule "^.*$" "-" [F] + +
When you need RewriteBase @@ -279,6 +297,24 @@ would be prohibitively expensive to repeat each time.

+
Which contexts support rewrite rules? + +

Rewrite rules are supported in +per-directory context +(.htaccess files, +Directory, and +If blocks).

+ +

Although rewrite rules are syntactically permitted in +Location +and Files +sections (including their regex counterparts), this is +unsupported and should never be necessary. Relative +substitutions, in particular, are likely to break in +these contexts.

+ +
+
Rule inheritance with RewriteOptions

By default, mod_rewrite rules are not