Clone Files or Directories

note

​On-prem The source and destination of a clone must reside in the same zone. JuiceFS 5.3 and earlier do not support cloning across zones.

juicefs clone (alias juicefs snapshot) creates a 1:1 clone by copying metadata only, without duplicating any new data in the object storage. Thus cloning is very fast, regardless of target file/directory size. In JuiceFS, this command is a better alternative to cp. Moreover, for Linux clients using kernels with copy_file_range support, the cp command achieves the same result as juicefs clone.

The clone result is a metadata copy only, where all the files still reference the same underlying object storage blocks. That is why a clone behaves the same in every way as its originals. Upon any file data modification, new data is written to new object storage blocks, with its associating metadata redirected to the new blocks as well (ROW, Redirect-on-Write), while the unchanged part of the files remains the same, still referencing the original blocks. And just like native JuiceFS files, random write on a clone can result in file fragmentations, which will be compacted in background jobs in order to improve read performance.

Please note that system tools like disk-free (df) or disk-usage (du) report space usage for the cloned data, but the underlying object storage space does not grow as blocks remain the same. In the same way, as metadata is actually replicated, the clone takes the same metadata engine storage space as the original.

Some caveats when using this feature:

• Although object storage data is not actually copied, clones take up both file system storage space (including inodes) and metadata engine storage space. This increases storage costs. Pay special attention when cloning large directories.
• Cloning a large directory takes time. If files are deleted or moved during the operation, the command may report ano such file error. This is normal behavior.
• JuiceFS volumes are isolated from each other, so clones cannot be created across file systems.

juicefs clone SRC DST

# Clone a file
juicefs clone /mnt/jfs/file1 /mnt/jfs/file2

# Clone a directory
juicefs clone /mnt/jfs/dir1 /mnt/jfs/dir2

# When DST ends with a slash, it is treated as an existing directory, and the
# clone is created inside it using the source's base name (here: /mnt/jfs/backup/file1)
juicefs clone /mnt/jfs/file1 /mnt/jfs/backup/

# The same applies when SRC is a directory (here: /mnt/jfs/backup/dir1)
juicefs clone /mnt/jfs/dir1 /mnt/jfs/backup/

# Preserve the source file's UID, GID, and permission mode
juicefs clone -p /mnt/jfs/file1 /mnt/jfs/file2

# Delete a clone (deprecated since 5.4, use rmr or rm -r instead)
juicefs clone -d /mnt/jfs/file2

# Recommended: use rmr to delete a clone
juicefs rmr /mnt/jfs/file2

# Or use rm -r
rm -r /mnt/jfs/file2