I have a large set of files which I mostly use in Linux but occassionaly I need to access them in Windows. Unfortunately, some of these files have invalid Windows characters, such as : and ?. When viewing this in Windows the filenames show up as garbage. I needed something that would allow me to view these files in Windows without duplicating the data and without modifying the proper file name. My first though was a Samba extension that would rename invalid file names when sharing them. That seemed a bit tedious. Then I came up with symtree which first creates a mirrored folder structure. Then it creates symbolic links to the source files in the proper directory. Before creating the folders or symlinks it runs regular expressions on the name.

You can find the code at GitHub.


A tool to create a mirrored symlink directory tree. The main use case is when the source files have characters in their name that are not always desirable. For example, a tree of files that contain Unix valid characters (eg, :"*>) that you want to share with Windows via Samba. You can use this tool to create file names that are valid in Windows without duplicating the content.

Folders are created in the target directory. These are actual folders and not links. The files are symbolic links to the source folder. Optionally, enabled by default, a regular expression can be ran on each folder and file name before the destination is created.


Basic usage python SOURCE DEST. To mirror a folder files into a folder windows_files you would use python files windows_files.

usage: [-h] [-c] [-f] [-o] [-v] [-V] [--settings SETTINGS]
                  source dest

Create a mirrored folder structure with symlinked files.

positional arguments:
  source                the source directory
  dest                  the target directory, will be the highest level mirror
                        of source

optional arguments:
  -h, --help            show this help message and exit
  -c, --create          create destination if it does not exist
  -d, --disableregex    disable the usage of regular expressions
  -f, --followsymlinks  symtree will follow symbolic links for source folders
  -o, --overwritesymlinks
                        symtree will overwrite symlinks in the destination
  -v, --verbose         verbose output
  -V, --veryverbose     insanely verbose output
  --settings SETTINGS   override the default settings file of symtree.json

Settings File

A settings file can be supplied which allows a set of regular expressions to be loaded into symtree, each of which are run on the on the file and folder names before they are linked. If an invalid setting file is provided, the default regular expression is s/<>:"\\|?*/_.

To add regular expressions to the settings file, follow this format:

"regular_expressions": {
    "<>\"\\\\|*": "_",
    "?": "",
    ":": " -"
Posted by kael on 9 September 2012