PyNextcloud-Sync

Install

https://github.com/ehstbr/PyNextCloud-Sync

First Step

1. Enter the base URL normally used to open your Nextcloud server.
2. Prefer Sign in with browser for Login Flow v2 and two-factor authentication support. Manual username plus password/app-password is also available.
3. Choose the local mirror folder. The default is $HOME/NextCloud.
4. Review the configuration and start the protected analysis.
5. Check computer-only, Nextcloud-only, identical, conflicting, and old synchronization-state paths.
6. Merge while preserving both versions, prioritize Nextcloud, prioritize the computer, or decide each conflict individually.

The analysis uses a completely new private folder to obtain a protected server snapshot. Any .sync_*.db found in the selected local folder is identified and archived outside the synchronized tree; it is never reused silently. Bidirectional mode, inotify, timers, and notify_push are enabled only after the reviewed result is applied, verified, and saved as a safety baseline.

New account setup then enables local filesystem monitoring, a 10-minute remote safety interval, compatible server push, disposable-file exclusions, and autostart. It also adds the synchronized folder to the Files sidebar, creates a safe symbolic link on the XDG Desktop, and applies the PyNextCloud Sync folder icon. These integrations can be changed independently in Settings → General → Local Folder.

Installations upgraded from 0.1.13 also start paused and go through this review once. This is intentional: the new release does not treat an older state without its own safety manifest as trusted.

Continuous deletion protection

After every successful synchronization, PyNextCloud Sync records a local manifest of the verified tree. Before another bidirectional run, it verifies the folder identity and its basic contents. A tiny run marker records whether the wrapper reached a committed post-sync baseline; after an interrupted process, the previous known-good baseline is checked again before recovery. If Linux reports an inotify queue overflow, the watcher is rebuilt and the app requests a normal protected reconciliation from nextcloudcmd instead of attempting to reconstruct missed changes itself.

Synchronization is blocked when:

• the local folder is missing, is no longer a directory, or cannot be read;
• the configured folder appears to have been replaced or remounted;
• a previously populated folder becomes empty;
• the nextcloudcmd state database disappears unexpectedly;
• at least 10 files or 20% of the previous baseline disappear, according to configurable limits.

The safety review lets the user restore from Nextcloud, remain paused, or explicitly approve those deletions for one run. Limits are available under Settings → Advanced → Deletion Safety Guard. Empty, missing, replaced, and unreadable folders always require review regardless of those limits.

If Files removes the sidebar bookmark, the application respects that choice and reflects the real state instead of recreating it.

Update checks

At every application startup, PyNextCloud Sync reads version.json from the root of the GitHub repository before enabling the synchronization runtime. An unreachable GitHub service, HTTP failure, or invalid manifest is logged and does not prevent normal startup.

Field	Purpose
schema_version	Version of the manifest contract
version	Latest release using SemVer
mandatory	Prevents older versions from running when true
released_at	ISO 8601 release date and time in UTC
summary	Short plain-text release summary
changelog	Complete ordered list of plain-text changes

Optional updates use a non-modal Libadwaita window, so normal initialization continues. Mandatory updates keep the runtime, filesystem monitoring, timers, and push connection disabled and offer only the official Releases page or application exit. The same validation can be started manually from About → Check for Updates. The detailed changelog remains collapsed until requested.

Configuration model

Area	What it controls
General	Autostart, battery behavior, local folder, Files bookmark, Desktop shortcut, and branded folder icon
Synchronization	inotify, local interval, notify_push, remote safety interval, and disposable-file exclusions
Network	Account removal, optional HTTP proxy, and explicit opt-in for invalid/self-signed certificates
Advanced	Daily logs, retention, detailed output, deletion-guard limits, and runtime diagnostics

All four automatic triggers can be combined or disabled. With local monitoring, local interval, server push, and remote interval all disabled, the application operates in manual-only mode.

Compatibility

Currently tested with Nextcloud Hub 26 Spring (34.0.1) deployed with Nextcloud AIO.

Compatibility with other installations may depend on the installed nextcloudcmd, server configuration, reverse proxy, authentication method, and optional apps. Future versions of Nextcloud are not guaranteed to remain compatible.

Exclusions

The default rules cover conservative disposable files such as .DS_Store, Thumbs.db, office lock files, Vim swap files, backup suffixes, and the nextcloudcmd journal noise file. Hidden user files remain eligible for synchronization because the client is always invoked with hidden-file support.

Patterns containing /, \, or .. are rejected. Version 1 does not support folder, path, or remote-subtree exclusions.

Files, credentials, and privacy

• Configuration: $XDG_CONFIG_HOME/pynextcloud-sync/settings.jsonK
• Generated exclusions: $XDG_CONFIG_HOME/pynextcloud-sync/excludes.lst
• Daily logs: $XDG_STATE_HOME/pynextcloud-sync/pynextcloud-sync-YYYY-MM-DD.log
• Safety manifest: $XDG_STATE_HOME/pynextcloud-sync/safety-manifest.json
• Archived old state databases: $XDG_STATE_HOME/pynextcloud-sync/safety-archives/
• Account secret: GNOME Keyring or another compatible Secret Service provider

Logs remain local, use one file per day, and are retained for 30 days by default. Sensitive values are redacted from application-owned log messages. If biometric desktop login leaves the Login keyring locked, GNOME shows its native unlock prompt before synchronization. The desktop password is handled only by GNOME; PyNextCloud Sync does not receive or store it. Canceling the prompt leaves the app waiting for an explicit Unlock Password Keyring request instead of repeatedly prompting or reporting invalid Nextcloud credentials.

Development and tests

PYTHONPATH=src python3 -m unittest discover -s tests -v
python3 -m compileall -q src tests

The pure-Python suite includes a fake nextcloudcmd for success, failure, authentication failure, output, and slow-run scenarios. Real account, GNOME tray host, UPower, suspend/resume, and long-running memory tests still require an actual desktop session.

Contributions are welcome when they preserve the project's narrow scope, low idle resource use, secure credential handling, and GNOME-oriented design. See CONTRIBUTING.md.

Documentation

• Changelog
• Terms of Use
• MIT License
• Third-party projects and licenses
• Contributing

Project status

Version 0.1.18 is a development release intended for evaluation. Test it with non-critical data before relying on it for regular synchronization, and always keep independent backups of important files.