https://github.com/fizzed/jsync
Pure Java rsync-like library for local to/from remote ssh/sftp. Can be used programmatically or via the command-line. Works on all platforms including Windows!
https://github.com/fizzed/jsync
Last synced: 2 months ago
JSON representation
Pure Java rsync-like library for local to/from remote ssh/sftp. Can be used programmatically or via the command-line. Works on all platforms including Windows!
- Host: GitHub
- URL: https://github.com/fizzed/jsync
- Owner: fizzed
- Created: 2025-11-25T15:29:23.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2025-12-06T00:21:47.000Z (6 months ago)
- Last Synced: 2025-12-09T14:16:52.122Z (6 months ago)
- Language: Java
- Homepage:
- Size: 2.15 MB
- Stars: 41
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
- awesome-java - Jsync
README
# Jsync by Fizzed
[](https://mvnrepository.com/artifact/com.fizzed/jsync)
## Automated Testing
The following Java versions and platforms are tested using GitHub workflows:
[](https://github.com/fizzed/jsync/actions/workflows/linux-java8.yaml)
[](https://github.com/fizzed/jsync/actions/workflows/linux-java11.yaml)
[](https://github.com/fizzed/jsync/actions/workflows/linux-java17.yaml)
[](https://github.com/fizzed/jsync/actions/workflows/linux-java21.yaml)
[](https://github.com/fizzed/jsync/actions/workflows/linux-java25.yaml)
[](https://github.com/fizzed/jsync/actions/workflows/linux-java8.yaml)
[](https://github.com/fizzed/jsync/actions/workflows/macos-arm64.yaml)
[](https://github.com/fizzed/jsync/actions/workflows/windows-x64.yaml)
The following platforms are tested using the [Fizzed, Inc.](http://fizzed.com) build system:
[](buildx-results.txt)
[](buildx-results.txt)
[](buildx-results.txt)
[](buildx-results.txt)
[](buildx-results.txt)
[](buildx-results.txt)
[](buildx-results.txt)
[](buildx-results.txt)
[](buildx-results.txt)
[](buildx-results.txt)
[](buildx-results.txt)
[](buildx-results.txt)
## Overview
Pure Java library (8, 11, 17, 21, 25, etc.) for providing rsync-like efficient file synchronization between two directories
or files either locally or remotely via SSH/SFTP. Requires no native dependencies, works on all major platforms including Windows,
and requires no special executables present on the remote system.
## Features
- Supports all platforms that Java can run on, including Windows
- Diff-based Syncing: Only transfers files that have changed (based on size, modification time, or checksum).
- Local: Sync between local directories.
- SSH/SFTP: Sync between local and remote servers (via SSH/SFTP).
- Zero-Dependency Core: The core logic is separated from protocol implementations to keep the footprint small.
- Builder API: Fluent, easy-to-use Java API for configuring sync jobs.
- Supports syncing file and directory permissions
- Does NOT require rsync to be installed on either system, uses SFTP for file operations on the remote system,
along with using SSH for checksums if needed.
- Leverages the excellent [Jsch](https://github.com/mwiede/jsch) library for SSH/SFTP support (but designed to pluggable
and support other SSH/SFTP implementations in the future)
## Command-Line Tool / Example
This library is optimized primarily for programmatic use, but if you'd like to simply use it from the command-line,
or to quickly give it a try, we suggest trying it out from within the [Blaze Script System](https://github.com/fizzed/blaze)
which has a built-in Jsync plugin with sophisticated SSH session handling (such as supporting ~/.ssh/config, ssh agents, etc.)
To quickly give it a try, you can run the following commands:
```shell
git clone https://github.com/fizzed/blaze.git
cd blaze
java -jar blaze.jar examples/jsync.java --from ~/example.iso --to bmh-build-x64-freebsd15-1:. --mode nest
```
Not all options are available from the command-line, but many of the most common ones are supported. If there is enough
demand, we may add a standalone command-line tool in the future.
## Usage
Published to maven central use the following for core and local-only syncing:
```xml
com.fizzed
jsync-engine
1.5.0
```
If you'd like to use SSH/SFTP syncing, you'll need to add the following dependency as well:
```xml
com.fizzed
jsync-sftp
1.5.0
```
To sync between two directories locally, here is an example:
```java
import com.fizzed.jsync.vfs.VirtualVolume;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.nio.file.Paths;
import static com.fizzed.jsync.vfs.LocalVirtualVolume.localVolume;
public class LocalToLocalDemo {
static private final Logger log = LoggerFactory.getLogger(LocalToLocalDemo.class);
static public void main(String[] args) throws Exception {
final VirtualVolume source = localVolume(Paths.get("example/source"));
final VirtualVolume target = localVolume(Paths.get("example/target"));
final JsyncResult result = new JsyncEngine()
.setDelete(true)
.sync(source, target, JsyncMode.MERGE);
}
}
```
To sync between a local and remote directory, here is an example. Note that this includes more options to control
how the sync is performed, such as telling the engine to create parent directories if they don't exist, and to force
the sync if the target directory has "file type" mismatches (i.e. a file exists on the target with the same name as a
directory on the source, or vice versa), and to ignore syncing the local '.git' directory.
```java
import com.fizzed.jsync.vfs.VirtualVolume;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.nio.file.Paths;
import static com.fizzed.jsync.sftp.SftpVirtualVolume.sftpVolume;
import static com.fizzed.jsync.vfs.LocalVirtualVolume.localVolume;
public class LocalToRemoteDemo {
static private final Logger log = LoggerFactory.getLogger(LocalToRemoteDemo.class);
static public void main(String[] args) throws Exception {
final VirtualVolume source = localVolume(Paths.get("example/source"));
final VirtualVolume target = sftpVolume("target-host", "remote-dir/target");
final JsyncResult result = new JsyncEngine()
.setDelete(true)
.setParents(true)
.setForce(true)
.addIgnore(".git")
.sync(source, target, JsyncMode.MERGE);
}
}
```
The sftp module provides fairly basic support for SSH configuration with just a hostname. Ideally, you'd provide your
own Jsch SSH session to your `sftpVolume` call, where you can then provide your own custom SSH configuration. For example:
```java
import com.fizzed.jsync.vfs.VirtualVolume;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.nio.file.Paths;
import static com.fizzed.jsync.sftp.SftpVirtualVolume.sftpVolume;
import static com.fizzed.jsync.vfs.LocalVirtualVolume.localVolume;
public class LocalToRemoteDemo {
static private final Logger log = LoggerFactory.getLogger(LocalToRemoteDemo.class);
static public void main(String[] args) throws Exception {
// create a jsch session with custom configuration
final com.jcraft.jsch.Session ssh = createMyOwnSshSession();
final VirtualVolume source = localVolume(Paths.get("example/source"));
final VirtualVolume target = sftpVolume(ssh, "remote-dir/target");
final JsyncResult result = new JsyncEngine()
.sync(source, target, JsyncMode.MERGE);
}
}
```
If you want more sophisticated SSH sessions automatically handled by this Jsync engine, you should look at using
the [Blaze Script System](https://github.com/fizzed/blaze), which has a built-in Jsync plugin that supports SSH sessions with sophisticated configuration
(such as ~/.ssh/config, ssh agents, etc.).
## Sponsorship & Support
Project by [Fizzed, Inc.](http://fizzed.com) (Follow on X: [@fizzed_inc](https://x.com/fizzed_inc))
**Developing and maintaining opensource projects requires significant time.** If you find this project useful or need
commercial support, we'd love to chat. Drop us an email at [ping@fizzed.com](mailto:ping@fizzed.com)
Project sponsors may include the following benefits:
- Priority support (outside of Github)
- Feature development & roadmap
- Priority bug fixes
- Privately hosted continuous integration tests for their unique edge or use cases
## License
Copyright (C) 2025+ Fizzed, Inc.
This work is licensed under the Apache License, Version 2.0. See LICENSE for details.