SpunkArt
Command line and project setup

How to write an .htaccess file

An .htaccess file holds Apache settings for one folder and everything below it. It is handy on shared hosting where you cannot edit the main server config. It is also easy to break a whole site with one typo, so this guide pairs each rule with a way to test it.

First check that it applies to you

Only the Apache web server reads .htaccess, and only when the main configuration allows it with AllowOverride. Nginx ignores the file completely, and so do most static hosting platforms, which use their own redirect and header settings. If your rules seem to do nothing, confirm the server software before you debug the rules. A response header such as Server: Apache is a clue, though many servers hide it.

Redirect one page to another

The simplest redirect uses mod_alias, with the old path and the new path:

Redirect 301 /old-pricing.html /plans.html
Redirect 301 /blog/ /articles/

A 301 tells browsers and search engines the move is permanent. Use 302 while you are still testing, because browsers cache 301 responses hard and a mistake can stick in your own browser after you fix the file. The second line moves a whole folder: a request for /blog/post.html goes to /articles/post.html.

Pattern redirects with mod_rewrite

For anything with patterns or conditions, turn on the rewrite engine. Suppose old article addresses looked like /news/2/my-post and now live at /articles/my-post, but only for requests that do not match a real file:

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^news/[0-9]+/(.+)$ /articles/$1 [R=301,L,NC]
  • RewriteCond lines are tests; the rule below them runs only if they pass. !-f means “is not an existing file”.
  • In .htaccess the path the rule sees has no leading slash, which is why the pattern starts with news/, not /news/.
  • (.+) captures the slug, and $1 inserts it into the target.
  • R=301 sends a permanent redirect, L stops processing more rules for this request, and NC ignores letter case.

Moving visitors to one host name, such as the www version, or forcing the secure scheme follows the same shape: a condition on %{HTTP_HOST} or %{HTTPS}, then a rule whose target is the full address with %{REQUEST_URI} appended. Many hosts offer both as a switch in their control panel, which is simpler and harder to get wrong.

Custom error pages

ErrorDocument 404 /404.html
ErrorDocument 500 /500.html

Use a local path that starts with a slash. If you give a full address on another host, Apache sends a redirect instead, and the visitor’s browser never sees the real 404 status.

Block access to sensitive files

<FilesMatch "^\.(env|git)">
  Require all denied
</FilesMatch>

Options -Indexes

The first block refuses any file whose name starts with .env or .git. Options -Indexes stops Apache from showing a list of files when a folder has no index page. The Require syntax is for Apache 2.4; very old servers used Order and Deny instead. Better still, keep secrets outside the public web folder entirely.

Caching headers

<IfModule mod_expires.c>
  ExpiresActive On
  ExpiresByType image/webp "access plus 1 month"
  ExpiresByType text/css "access plus 1 week"
  ExpiresByType text/html "access plus 0 seconds"
</IfModule>

The IfModule wrapper means the block is skipped, rather than crashing the site, if the module is not loaded. Long cache times suit files whose names change when their content changes; keep HTML short so visitors see updates.

Testing without guessing

  1. Keep a copy of the working file before every edit.
  2. Change one rule at a time.
  3. Check the result from a terminal: curl -I example.com/old-pricing.html should show the status line and a Location header.
  4. If the whole site returns a 500 error, the file has a syntax error or uses a module that is not loaded. Restore the copy, then read the server error log.

Questions

Does .htaccess slow a site down?

A little. Apache checks for the file in every folder on the path of each request. If you control the main config, put rules there and turn overrides off.

What permissions should the file have?

644 is typical: the owner can edit it, and the web server can read it. It never needs execute permission.