dirsync

Common errors

• TypeError: sync() missing 1 required positional argument: 'action'

  cause The `action` argument (e.g., 'sync', 'diff', 'update') was not provided when calling the `dirsync.sync` function.
  fix Specify the synchronization action as the third positional argument: `from dirsync import sync; sync('source_dir', 'target_dir', 'sync')`.

• IOError: [Errno 2] No such file or directory: 'target_data'

  cause The target directory specified for synchronization does not exist, and the `create` option was not enabled.
  fix Either create the target directory manually before calling `sync`, or pass the `create=True` argument: `sync('source_dir', 'target_dir', 'sync', create=True)`.

• Files are not being filtered correctly with `include` or `exclude` options.

  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.
  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$'])`.

Warnings

• gotcha 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.
  Fix: Always provide the `action` argument, e.g., `sync(sourcedir, targetdir, 'sync', ...)`.
• gotcha 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.
  Fix: Ensure the target directory exists before calling `sync`, or pass `create=True` (Python) / `--create` (CLI).
• gotcha 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.
  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$']`.
• gotcha 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.
  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).

Install

• pip install dirsync Install with pip

Imports

• sync

  from dirsync import sync

Quickstart

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.

import os
from dirsync import sync

# Create dummy source and target directories for demonstration
source_dir = './source_data'
target_dir = './target_data'

os.makedirs(source_dir, exist_ok=True)
os.makedirs(target_dir, exist_ok=True)

with open(os.path.join(source_dir, 'file1.txt'), 'w') as f:
    f.write('Hello from source!')
with open(os.path.join(source_dir, 'file2.log'), 'w') as f:
    f.write('Log content.')

print(f"Synchronizing from '{source_dir}' to '{target_dir}'")
# Sync: copies all files from source to target, creating target if it doesn't exist
sync(source_dir, target_dir, 'sync', verbose=True, create=True)

print(f"Content of '{target_dir}': {os.listdir(target_dir)}")

# Clean up (optional)
os.remove(os.path.join(source_dir, 'file1.txt'))
os.remove(os.path.join(source_dir, 'file2.log'))
os.rmdir(source_dir)
os.remove(os.path.join(target_dir, 'file1.txt'))
os.remove(os.path.join(target_dir, 'file2.log'))
os.rmdir(target_dir)