Inital docs and requirements files

README.md

@@ -0,0 +1,32 @@
+block-cloning-tool
+==================
+
+a script made for helping handle block cloning files with-out some of the footguns from using GNU coreutils cp
+
+Issues that cp has
+==================
+
+* It will wipe out ACLs and xattr on the cloned file
+* Potential race conditions where the file could be changed out before cp does the operation
+* Resets [amcb]times on the files.
+
+... others?
+
+
+How this works
+=================
+
+First it will do some sanity checks to be sure that it's not going to make a clone that shouldn't be done.  This is to check for races between finding duplicate files with rmlint, fdupes, or other tools and the time of attempting the clone
+
+1) Start by flock()ing the source and destination files.  Not perfect but it will help prevent something else from replacing the file out from under us.
+2) Check that the lengths match on both source and destination files, mostly as a very quick sanity check before we do anything to the files
+3) Check the digest of the files (BLAKE3?) to check that they're identical.  (should it instead do a complete byte by byte comparison?)
+4) Serialize the xattr, acl, and [amcb]times of the destination file
+5) Create a new file (dest filename + mktmpfile-ish), setacls, xattr on the new file and flock it
+6) make the ioctl(FIDEDUP) call to clone the file
+  6a) If that errors, and --across-datasets is provided try doing copyfilerange() syscall
+  6b) TODO any reasonable way to warn if we think that didn't clone?
+7) set the times on the file (TODO how?)
+8) rename old dest file
+9) rename new cloned file
+10) unlink ole dest file

cpanfile

@@ -0,0 +1,3 @@
+requires 'Path::Tiny';
+requires 'File::ExtAttr';
+requires 'Linux::ACL';