{"id":8083,"library":"dirsync","title":"dirsync","description":"dirsync is an advanced Python library and command-line tool for synchronizing directory trees. It is based on Anand B Pillai's Python robocopier and provides functionalities like reporting differences, syncing content, and updating existing content with various options for filtering and behavior. The current version is 2.2.6, and it appears to have a stable, though infrequent, release cadence.","status":"active","version":"2.2.6","language":"en","source_language":"en","source_url":"https://github.com/tkhyn/dirsync/","tags":["directory synchronization","file management","backup","cli","utility"],"install":[{"cmd":"pip install dirsync","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"sync","correct":"from dirsync import sync"}],"quickstart":{"code":"import os\nfrom dirsync import sync\n\n# Create dummy source and target directories for demonstration\nsource_dir = './source_data'\ntarget_dir = './target_data'\n\nos.makedirs(source_dir, exist_ok=True)\nos.makedirs(target_dir, exist_ok=True)\n\nwith open(os.path.join(source_dir, 'file1.txt'), 'w') as f:\n    f.write('Hello from source!')\nwith open(os.path.join(source_dir, 'file2.log'), 'w') as f:\n    f.write('Log content.')\n\nprint(f\"Synchronizing from '{source_dir}' to '{target_dir}'\")\n# Sync: copies all files from source to target, creating target if it doesn't exist\nsync(source_dir, target_dir, 'sync', verbose=True, create=True)\n\nprint(f\"Content of '{target_dir}': {os.listdir(target_dir)}\")\n\n# Clean up (optional)\nos.remove(os.path.join(source_dir, 'file1.txt'))\nos.remove(os.path.join(source_dir, 'file2.log'))\nos.rmdir(source_dir)\nos.remove(os.path.join(target_dir, 'file1.txt'))\nos.remove(os.path.join(target_dir, 'file2.log'))\nos.rmdir(target_dir)","lang":"python","description":"This quickstart demonstrates how to use the `sync` function to synchronize files from a source directory to a target directory. It includes creating dummy directories and files, performing a 'sync' operation with verbose output and target directory creation, and finally cleaning up."},"warnings":[{"fix":"Always provide the `action` argument, e.g., `sync(sourcedir, targetdir, 'sync', ...)`.","message":"The `action` parameter (e.g., 'sync', 'diff', 'update') is mandatory when calling `dirsync.sync` from Python or using the command-line tool. Omitting it will result in an error or unexpected behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the target directory exists before calling `sync`, or pass `create=True` (Python) / `--create` (CLI).","message":"By default, the target directory must exist. If it doesn't, `dirsync` will fail. To automatically create the target directory if it's missing, you must explicitly use the `create=True` option in the Python API or `--create` flag in the CLI.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Construct regex patterns to match the full path (e.g., `^.*\\.txt$` for all .txt files). For the Python API, pass patterns as a list: `include=['^.*\\.txt$']`.","message":"When using `ignore`, `only`, `exclude`, or `include` options, the patterns provided are regular expressions and must match the *entire path* from the beginning. For the Python API, these options expect a list of regex strings.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If using the Python API, all options must be passed programmatically as arguments to the `sync` function. For CLI, ensure options are defined in the config file or as command-line arguments (which override config).","message":"Configuration files (`.dirsync` in user's home or source/target directories) are only parsed and used when `dirsync` is run from the command line. They are ignored when the `sync` function is called directly from Python code.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Specify the synchronization action as the third positional argument: `from dirsync import sync; sync('source_dir', 'target_dir', 'sync')`.","cause":"The `action` argument (e.g., 'sync', 'diff', 'update') was not provided when calling the `dirsync.sync` function.","error":"TypeError: sync() missing 1 required positional argument: 'action'"},{"fix":"Either create the target directory manually before calling `sync`, or pass the `create=True` argument: `sync('source_dir', 'target_dir', 'sync', create=True)`.","cause":"The target directory specified for synchronization does not exist, and the `create` option was not enabled.","error":"IOError: [Errno 2] No such file or directory: 'target_data'"},{"fix":"Ensure regex patterns are anchored (`^` and `$`) to match the full path (e.g., `r'^.*\\.py$'`). When using the Python API, provide patterns as a list: `sync(..., include=['^.*\\.py$'])`.","cause":"The regex patterns provided to `include` or `exclude` do not match the full file paths, or they were not passed as a list of strings when using the Python API.","error":"Files are not being filtered correctly with `include` or `exclude` options."}]}