RegEx Files and Directories Exclusion

 

RegEx Files and Directories Exclusion

https://www.akeeba.com/documentation/akeeba-solo/regex-files-directories-exclusion.html

Sometimes you know that you have to exclude files or directories following a specific naming pattern, but there are so many that it's completely impractical going to the normal exclusion filters page and click them one by one. Or they are scattered around the file system tree, making it extremely complex to track them down and exclude them. Wouldn't it be nice to have an automated way to say, for example, "exclude all SVN directories from the backup"? Enter regular expressions. What are those regular expressions? Let's see what Wikipedia has to say on the subject:

	In computing, regular expressions, also referred to as regex or regexp, provide a concise and flexible means for matching strings of text, such as particular characters, words, or patterns of characters. A regular expression is written in a formal language that can be interpreted by a regular expression processor, a program that either serves as a parser generator or examines text and identifies parts that match the provided specification.
	--"Regular expression" article from Wikipedia

In a nutshell, regular expressions allow you to quickly define filters which span multiple subdirectories and match file or directory names based on a number of criteria. If you want a quick cheatsheet you can use, I suggest the Regular Expressions Cheat Sheet (V2) from AddedBytes.com. Some practical examples will be presented at the end of this section.

There are some special considerations experienced regular expressions users must have in mind:

• You are supposed to specify a full regular expression, including its opening and ending separators. So ^foo is invalid, but /^foo/ and #^foo# are valid.

• The application supports an extension to the PCRE syntax. If you prefix the regex with an exclamation mark you negate its meaning. So /^foo/ will match all entities starting with foo, whereas !/^foo/ will match all entities NOT starting with foo.

• The application stores and parses your data as raw Unicode (UTF-8), provided that your database server meets the minimum version requirements. This eliminates the need to use the u suffix of regular expressions in order to reference Unicode characters.

When it comes to files and directories exclusion filters in particular, you have to bear in mind:

• The path separator is always the forward slash, even on Windows. This means that c:\wamp\www\index.php is internally represented as c:/wamp/www/index.php. Therefore, all regular expressions must use the forward slash whenever referencing a path separator.

• The filenames are always relative to the root. That's why you have to select a root before entering a regex filter. For instance, the /home/mysite/public_html/images/stories directory (where /home/mysite/public_html is the root of your site) is internally referenced as images/stories. You have to take this into account when writing regular expressions.

RegEx Files and Directories Exclusion

This page primarily consists of a grid view. Above the grid, you can find the Root Directory drop-down menu. The application can define filters for the site's files or for each of the off-site directories separately. The default selection, [SITEROOT], contains all filters pertaining to the configured site's files. If you have defined off-site directories, you can select the appropriate directory from the drop-down list in order to define filters for that directory.

The grid contains three columns:

Icons column

You can perform the basic operation by clicking on this column's icons:

• Trashcan. When you click it, the filter row will be removed.

• Pencil. When you click it, the row switches to edit mode

• Add (only on the last row). Clicking this icon adds a new row at the end of the list and switches it to edit mode. You can select the type of the newly added filter.

Type

The filter type defines what will happen when a directory or file matches the regex filter and can be one of:

• Exclude directory. Completely skips backing up the given subdirectory.

• Exclude file. Completely skips backing up the given file.

• Skip subdirectories. Skips backing up all the subdirectories inside the given directory.

• Skip files. Skips backing up all the files inside the given directory.

Filter Item

This is the actual regular expression you have to write.

RegEx Files and Directories Exclusion - Edit Mode

When you click on the pencil or add icons, the respective row enters the edit mode. In this mode, the filter type becomes a drop-down list where you can select the type of this filter row. The filter item column also turns into an edit box so that you can enter your filter definition. The icon column now contains two different icons:

• Floppy disk. When you click it, the changes will be saved.

• Cancel. When you click it, any changes will be cancelled and the row will resume its previous state.

In order to make sure that your filters match the directories and/or files you meant it to, you can do so very easily. Just go back to the Control Panel and click on the Files and Directory Exclusion button. The items filtered out by the regular expressions filters will be automatically highlighted in red. You can browse through the file system structure to make sure that only the items you really meant are being excluded.

Regular Expressions recipes for files and directories

No matter how good you are at writing regular expressions, it's always a good idea to have some recipes which serve as a starting point to cooking your own.

1. Exclude AVI files in all directories (note: the i at the end causes the regex to match .avi, .Avi, .AVI, etc without discriminating lower or upper case):

   #\.avi$#i

2. Exclude AVI files in your site's images directory and all of its subdirectories:

   #^images/(.*).avi$#i

3. Exclude AVI files in your site's images directory but not its subdirectories

   #^images/[^/]*.avi$#i

4. Exclude AVI files in your site's images/video subdirectory but not its subdirectories

   #^images/video/[^/]*.avi$#i

5. Exclude all files except for files ending in .php (note: the exclamation mark in the beginning is a custom notation which negates the meaning of the following regular expression)

   !#\.php$#

6. Exclude all .svn subdirectories anywhere and everywhere in your site. The idea is to match everything which ends in a slash (directory separator) and .svn, therefore it's a .svn subdirectory.

   #/\.svn$#

   However, this won't match the .svn directory in your site's root, so you will have to add yet another filter:

   #^\.svn$#

   This second filter matches only the .svn directory in your site's root.