apfsclone

README

This project provides Go APIs for making and checking APFS clones, as well as a CLI tool. Supports recursively cloning directories.

Credit to https://github.com/dyorgio/apfs-clone-checker for the checking method.

API

See reference.

CLI

To install,

go install tcl.sh/apfsclone/cmd/apfsclone@latest

Usage:
	apfsclone <source> <destination>
	apfsclone -c [-q] <file1> <file2>

Makes or checks APFS clones.

---

In clone mode, if <source> is a file, make an APFS clone of it at <destination>.
If <source> is a directory, recursively clone contents of it at <destination>.
<source> and <destination> must be on the same APFS volume, and <destination>
must not exist. If <source> is a symbolic link, it is cloned as is, not followed.

The exit code is 0 if the clone operation is successful, and 1 otherwise.

---

In check mode (-c), check if <file1> and <file2> are APFS clones of each other.
Symbolic links are not followed. The following results may be printed:

  result unknown (only when there's an error; printed in addition to the error)
  files are apfs clones
  files aren't apfs clones
  files reference the same inode
  both files are empty

The exit code is 0 if "files are apfs clones", 2 if "result unknown" (errored),
and 1 otherwise. With -q, message is suppressed, exit code is the same.

---

Options:
  -c	check mode
  -q	quiet

Documentation

Overview

Package apfsclone provides tools to make and check APFS clones.

Index

• func CloneDir(src, dst string) (err error)
• func CloneFile(src, dst string) (err error)
• func IsOnAPFSVolume(path string) (isAPFS bool, err error)
• type CloneCheckResult
  • func FilesAreAPFSClones(f1, f2 string) (result CloneCheckResult, err error)
  • func (r CloneCheckResult) String() string

Functions

func CloneDir

func CloneDir(src, dst string) (err error)

CloneDir recursively creates APFS clones of all files in src at dst.

src must be a directory, not a symbolic link to a directory. dst must not exist. Both must be on the same APFS volume.

This operation uses copyfile(3) with COPYFILE_CLONE|COPYFILE_RECURSIVE under the hood, with extra checks to make sure contents must be cloned, instead of only opportunistically cloned. If you want more flexibility with flags and/or progress reporting, check out https://pkg.go.dev/go-darwin.dev/apfs#CopyFile.

func CloneFile

func CloneFile(src, dst string) (err error)

CloneFile creates an APFS clone of src at dst.

src must be a file. dst must not exist. Both must be on the same APFS volume. Symbolic link is not followed and cloned as is.

This operation uses copyfile(3) with COPYFILE_CLONE_FORCE under the hood. If you want more flexibility with flags, check out https://pkg.go.dev/go-darwin.dev/apfs#CopyFile.

func IsOnAPFSVolume

func IsOnAPFSVolume(path string) (isAPFS bool, err error)

IsOnAPFSVolume checks whether the given path is on an APFS volume. Symbolic link is not followed.

Types

type CloneCheckResult

type CloneCheckResult int

const (
	// Unable to determine if checked files are APFS clones.
	UnknownResult CloneCheckResult = iota
	// Checked files are APFS clones.
	AreClones
	// Checked files are not APFS clones.
	NotClones
	// Checked files reference the same inode on disk.
	SameInode
	// Both checked files are empty, making the question moot.
	BothEmpty
)

func FilesAreAPFSClones

func FilesAreAPFSClones(f1, f2 string) (result CloneCheckResult, err error)

FilesAreAPFSClones checks whether the two files are APFS clones of each other. Symbolic links are not followed.

The checking is done by comparing the physical location of each block of both files (if they pass some basic similarity checks). Credit to https://github.com/dyorgio/apfs-clone-checker for the idea.

func (CloneCheckResult) String

func (r CloneCheckResult) String() string