docs: juicefs clone explanation (#4005)

juicedata · Aug 18, 2023 · f143e22 · f143e22
1 parent cf1791e
commit f143e22
Show file tree

Hide file tree

Showing 4 changed files with 22 additions and 2 deletions.
diff --git a/docs/en/images/juicefs-clone.svg b/docs/en/images/juicefs-clone.svg
diff --git a/docs/en/reference/command_reference.md b/docs/en/reference/command_reference.md
@@ -940,7 +940,13 @@ In which:
 
 ### `juicefs clone` <VersionAdd>1.1</VersionAdd> {#clone}
 
-This command can clone a file or directory without copying the underlying data, similar to the `cp` command, but very fast.
+This command makes a clone of your data by creating a mere metadata copy, without creating any new data in the object storage, thus cloning is very fast regardless of target file / directory size. Under JuiceFS, this command is a better alternative to `cp`, moreover, for Linux clients using kernels with [`copy_file_range`](https://man7.org/linux/man-pages/man2/copy_file_range.2.html) support, then the `cp` command achieves the same result as `juicefs clone`.
+
+![clone](../images/juicefs-clone.svg)
+
+The clone result is a metadata copy, all the files are still referencing the same object storage blocks, that's why a clone behaves the same in every way as its originals. When either of them go through actual file data modification, the affected data blocks will be copied on write, and become new blocks after write, while the unchanged part of the files remains the same, still referencing the original blocks.
+
+**Clones takes up both file system storage space and metadata engine storage space**, pay special attention when making clones on large size directories.
 
 #### Synopsis
 

diff --git a/docs/zh_cn/images/juicefs-clone.svg b/docs/zh_cn/images/juicefs-clone.svg
diff --git a/docs/zh_cn/reference/command_reference.md b/docs/zh_cn/reference/command_reference.md
@@ -939,7 +939,13 @@ juicefs sync --include='a1/b1' --exclude='a*' --include='b2' --exclude='b?' s3:/
 
 ### `juicefs clone` <VersionAdd>1.1</VersionAdd> {#clone}
 
-该命令可以克隆文件或目录但不复制底层数据，类似于 `cp` 命令，但是非常快。
+对指定数据进行克隆，创建克隆时不会实际拷贝对象存储数据，而是仅拷贝元数据，因此不论对多大的文件或目录进行克隆，都非常快。因此对于 JuiceFS，这个命令是 `cp` 更好的替代，甚至对于 Linux 客户端来说，如果所使用的内核支持 [`copy_file_range`](https://man7.org/linux/man-pages/man2/copy_file_range.2.html)，那么调用 `cp` 时，实际发生的也是同样的元数据拷贝，调用将会格外迅速。
+
+![clone](../images/juicefs-clone.svg)
+
+克隆结果是纯粹的元数据拷贝，实际引用的对象存储块和源文件相同，因此在各方面都和源文件一样，可以正常读写。有任何一方文件数据被实际修改时，对应的数据块变更会以写入时复制（Copy-on-Write）的方式，写入到新的数据块，而其他未经修改的文件区域，由于对象存储数据块仍然相同，所以引用关系依然保持不变。
+
+需要注意的是，**克隆产生的元数据，也同样占用文件系统存储空间，以及元数据引擎的存储空间**，因此对庞大的目录进行克隆操作时请格外谨慎。
 
 #### 概览