Support

Documentation

RegEx Files and Directories Exclusion

[Note]Note

This feature is available only in Akeeba Backup Professional

Sometimes you know that you have to exclude files or directories following a specific naming pattern, but they are so many that it's 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 too complicated tracking them down and excluding them one by one. Regular expression filters let you create pattern-based filters to deal with that. What are regular expressions? Let's consult Wikipedia:

 

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, we recommend taking a look at the Regular Expressions Cheat Sheet (V2) from Cheatography. 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.

  • Akeeba Backup 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.

  • Akeeba Backup stores and parses your data as raw Unicode (UTF-8), provided that your database meets the minimum requirement of site database server version. 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 images/stories directory on the root of your Joomla!™ site is internally referenced as images/stories. You have to take this into account when writing regular expressions.

RegEx Files and Directories Exclusion

At the very top of the page you will see the backup profile number and title as a reminder. Remember that database table exclusion filters, just like all Akeeba Backup filters, are set up per backup profile.

Right below it is the Root Directory drop-down menu. Akeeba Backup 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 main 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.

Each row in the grid below represents a filter. The three columns on each row are:

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:

  • 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.

You can easily make sure that your filters match the directories and/or files you meant to. 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 on writing regular expressions, it's always a good idea to have some recipes which serve as a starting point for 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 Akeeba Backup 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.