2017-08-29 01:22 UTC
  • Xyne


Description: A tool that synchronizes hierarchies of symlinks.
Latest Version: 2017.8
Source Code: src/
  • i686
  • x86_64
  • glibc
Arch Repositories:
  • [xyne-i686]
  • [xyne-x86_64]
AUR Page: synclinks
Arch Forum Thread: 137161


synclinks is a tool for synchronizing a hierarchy of symlinks. It’s a bit like a limited version of rsync that creates synclinks instead of copying the files.



synclinks foo bar

This will traverse the directory “foo” and create a symlink at the same relative path in “bar” for every file that it finds. For example, given “foo” with


synlinks will create

bar/bar.txt -> foo/bar.txt
bar/baz/whatever.txt -> foo/baz/whatever.txt

Basic with update option.

synclinks -u foo bar

The update option will make synclinks traverse “bar” first and copy any files in bar to “foo”. It will then continue as above. This ensures that any files created in “bar” (i.e. completely new files or replaced symlinks) will be moved to “foo”, so that “foo” continues to contain all of the real files.

File lists

File lists are where the real functionality of synclinks lies. A file list is a plaintext file with a relative path on each line, for example:



synclinks -f /path/to/file foo bar

would then create

bar/a.txt -> foo/a.txt
bar/b.txt -> foo/b.txt
bar/d.txt -> foo/d.txt
bar/img -> foo/img

In this case, if “foo” contains e.g. c.txt, it will not be symlinked in “bar”. This allows you to expose a subset of the files in “foo”. Furthermore, the paths in the file list may be directories (e.g. “img” in this case) and they do not need to exist when synlinks is run.1

Including the upgrade option when using a file list will move both files and directories back to the source directory.

What is this good for?

I wrote this as part of a solution to manage clutter in my home directory. Some applications create files that I want to keep but most just clutter up my home directory with crap. With synclinks, I can keep the files that I want in a given location and then use filelists to symlink those into a temporary home directory in which I run applications. When I’m done, I use the update option to copy back any changes in my chosen files to the source files that I have in a different directory. After that I can just discard the entire temporary home directory.

I’m sure that there are other uses for this though.

Help Message

$ synclinks --help

Usage: synclinks [OPTION...] <source dir> <dest dir>
Create symlinks in <dest dir> to paths in <source dir>. The paths may be
specified as relative paths to <source dir> in a file list list with the -f
option, otherwise the entire directory hierarchy is mirrored and all
non-directory items are symlinked.

  -a, --always               Always create links even when the target does not
                             exist. This is only useful for links that will
                             point to files, because the target file will be
                             created when writing to the link. If you use this
                             option when linking directories, then make sure
                             that empty directories are created in <source dir>
                             before using the links in <dest dir>. Otherwise,
                             skip this option and let your applications create
                             directories in <dest dir>, then run synclinks with
                             the update option to copy them to <source dir>
                             before linking them. This option only works with
                             file lists as a directory scan has no way of
                             determining which non-existent paths should be
  -b, --bakdir=<backup dir>  Set a backup directory path for deleted files.
                             File name extensions will be added to indicate the
                             original location of the files. If this path is
                             not set then the files will be saved in their
                             original directory with an extension.
  -d, --dryrun               Dry run. Print messages without creating or
                             removing any files. This option activates verbose
  -e, --existing             When updating without a file list, the destination
                             directory is normally scanned for existing files
                             which are moved to the source directory. With this
                             option, only files that already exist in the
                             source directory will be updated. This is useful
                             to prevent synclinks from adding new files to the
                             source directory when working without a file list.
  -f, --filelist=<file list> Read paths from <file list>. This is the main
                             functionality of synclinks. <file list> is a
                             plaintext file with paths on separate lines. Each
                             path is a relative path to a file or directory in
                             <source dir> and will be used to create a
                             corresponding symlink in <dest dir>. For example,
                             the line "foo" will create a symlink at "<dest
                             dir>/foo" that points to "<source dir>/foo".
  -g, --glob                 Interpret paths in the file list as glob patterns.
  -r, --relative             Create relative symlinks instead of absolute
  -u, --update               Replace files in <source dir> with files in <dest
                             dir>. This is useful if new files in <dest dir>
                             have been added to the file list or if an
                             application has removed a symlink in <dest dir>
                             and created a regular file instead. This currently
                             only works with file lists. If this option is
                             passed once then the <source dir> file will be
                             replaced by the <dest dir> file if it is newer. If
                             it is passed more than once then the <source dir>
                             file will always be replaced by the file in <dest
  -v, --verbose              Verbose mode. This currently only works with file
                             lists. Pass multiple times to increase verbosity.
  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.



  • Added option to limit links to existing source files when no file list is given.
  • Added option for creating relative symlinks.
  • Fixed more bugs.
  • Added basic unit tests.


  • Refactored to support globbing in file lists.
  • Dry run and verbose options now work without a file list.
  • Documented with Doxygen.


  • By default symlinks to missing paths are no longer created. This should avoid problems with directories.
  • A new option, -a, has been added to emulate the previous behavior.


  • Fixed bug that required two runs to created missing directories.



  • create daemon mode using inotify events (see maown)

  1. You should create directories first though so that the symlinks will work as expected. Writing to a symlink that points to a missing file will create the file. Trying to create files in a missing directory through a symlink will not create the directory.

echo | sed 's/\./@/'
Blog News
XHTML 1.0 Strict CSS level 3 Atom 1.0