FileSync Plugin

The FileSync Plugin adds a filesync SCM provider that copies repository contents from a local directory or Windows SMB/UNC network share into Codumentor's repos directory before ingestion. It is useful for teams that store source code on shared drives rather than a Git hosting platform.

Requirements

• For SMB/UNC network paths, the Python package smbprotocol must be installed: ``bash pip install smbprotocol ``
• For local directory paths, no additional dependencies are needed.

Configuration

Plugin Registration

plugins:
  - module: codumentor.plugins.filesync
    class: FileSyncPlugin

No args are required. The plugin registers the filesync SCM provider automatically.

Repository Configuration

Repositories using FileSync are declared with scm: filesync in the repos list:

repos:
  # Sync from a local directory
  - name: my-project
    scm: filesync
    path: /mnt/shared/projects/my-project

  # Sync from a Windows UNC path
  - name: legacy-app
    scm: filesync
    path: "\\\\fileserver\\projects\\legacy-app"
    options:
      username: "domain\\user"
      password: "${SMB_PASSWORD}"   # Env var expansion is supported

  # Sync from an SMB URL
  - name: another-app
    scm: filesync
    path: "smb://fileserver/projects/another-app"
    options:
      username: user
      password: "${SMB_PASSWORD}"
      clear_target: false           # Keep existing target before sync

Repository Options

Option	Type	Default	Description
path	string	—	Source directory, UNC path, or smb:// URL
username	string	—	SMB username (supports ${ENV_VAR} expansion)
password	string	—	SMB password (supports ${ENV_VAR} expansion)
clear_target	bool	true	Delete the target directory before syncing
target_dir	string	auto	Override the destination path under repos_dir

How It Works

During ingestion, when Codumentor processes a filesync repository:

1. The source path is resolved (local filesystem, UNC, or SMB URL)
2. If credentials are provided, an SMB session is registered for the server
3. The source directory (or file) is copied to the target path under repos_dir
4. Ingestion continues on the local copy as normal

The sync runs in a thread pool to avoid blocking the async event loop.

Notes

• Passwords and paths support ${ENV_VAR} syntax expanded at runtime via os.path.expandvars
• UNC paths using backslashes (\\server\share) are normalized to forward slashes internally for smbclient
• Both smb://server/share/path URLs and \\server\share\path UNC paths are supported
• Setting clear_target: false is useful for incremental syncs where you want to preserve files that were deleted from the source