{"id":29151217,"url":"https://github.com/karpeleslab/reflink","last_synced_at":"2025-07-01T00:08:56.313Z","repository":{"id":57533479,"uuid":"280637116","full_name":"KarpelesLab/reflink","owner":"KarpelesLab","description":"Reflink file copy in Go","archived":false,"fork":false,"pushed_at":"2025-03-18T01:25:20.000Z","size":32,"stargazers_count":36,"open_issues_count":2,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-01T00:08:51.749Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KarpelesLab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-18T10:54:37.000Z","updated_at":"2025-06-22T22:36:19.000Z","dependencies_parsed_at":"2024-06-19T00:48:09.810Z","dependency_job_id":null,"html_url":"https://github.com/KarpelesLab/reflink","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/KarpelesLab/reflink","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarpelesLab%2Freflink","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarpelesLab%2Freflink/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarpelesLab%2Freflink/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarpelesLab%2Freflink/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KarpelesLab","download_url":"https://codeload.github.com/KarpelesLab/reflink/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarpelesLab%2Freflink/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262870877,"owners_count":23377314,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-01T00:08:54.572Z","updated_at":"2025-07-01T00:08:56.265Z","avatar_url":"https://github.com/KarpelesLab.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GoDoc](https://godoc.org/github.com/KarpelesLab/reflink?status.svg)](https://godoc.org/github.com/KarpelesLab/reflink)\n\n# reflink\n\nA Go library to perform efficient file copies using reflink operations on compatible filesystems (btrfs or xfs).\n\n## What is a reflink?\n\nThere are several types of links in file systems:\n\n* symlinks (symbolic links) - pointer to another file path\n* hardlinks - multiple directory entries pointing to the same inode/data\n* reflinks - copy-on-write links where files initially share the same data blocks\n\nReflinks are a modern file system feature found in btrfs and xfs that act similar to hard links but with a key difference: modifying one file doesn't affect the other. Only the modified portions will consume additional disk space (copy-on-write). This makes reflinks ideal for efficient file copies, snapshots, and deduplication.\n\n## Benefits of reflinks\n\n* **Space efficiency**: Initial reflink copies use virtually no additional disk space\n* **Performance**: Creating a reflink is nearly instantaneous, even for very large files\n* **Safety**: Changes to one file don't affect the other file's contents\n* **Transparency**: Applications don't need to be aware they're using reflinked files\n\n## Compatibility\n\nA system needs a compatible OS and filesystem to perform reflinks. Currently supported:\n\n* btrfs on Linux\n* xfs on Linux (with reflink=1 mount option)\n\nOther operating systems have similar features that may be implemented in future versions:\n\n* Windows has `DUPLICATE_EXTENTS_TO_FILE`\n* Solaris has `reflink`\n* MacOS has `clonefile`\n\n## Usage\n\n### Basic usage\n\n```golang\n// Creates a reflink copy or fails if reflink is not supported\nerr := reflink.Always(\"original_file.bin\", \"snapshot-001.bin\")\n\n// Creates a reflink copy if supported, falls back to regular copy if not\nerr := reflink.Auto(\"source_img.png\", \"modified_img.png\")\n```\n\n### Working with file handles\n\n```golang\nsrc, _ := os.Open(\"source.dat\")\ndefer src.Close()\ndst, _ := os.Create(\"dest.dat\")\ndefer dst.Close()\n\n// Reflink the entire file\nerr := reflink.Reflink(dst, src, true) // true enables fallback to regular copy\n\n// Reflink just a portion of the file\n// Copy 1MB from offset 2MB in source to offset 0 in destination\nerr := reflink.Partial(dst, src, 0, 2*1024*1024, 1*1024*1024, true)\n```\n\n## Error handling\n\nThe library defines these specific errors:\n\n* `ErrReflinkUnsupported` - Returned when reflink is not supported on this OS\n* `ErrReflinkFailed` - Returned when reflink is not supported on the specific filesystem or files\n\nUse standard Go error handling to check for these:\n\n```golang\nerr := reflink.Always(src, dst)\nif err != nil {\n    if errors.Is(err, reflink.ErrReflinkUnsupported) {\n        // OS doesn't support reflinks\n    } else if errors.Is(err, reflink.ErrReflinkFailed) {\n        // These specific files or filesystem don't support reflinks\n    } else {\n        // Other error (permissions, file not found, etc.)\n    }\n}\n```\n\n## Fallback mechanism\n\nWhen using `Auto()` or setting `fallback=true` in other functions, the library tries these methods in order:\n1. FICLONE ioctl (real reflink)\n2. copy_file_range syscall (efficient kernel-space copy)\n3. io.Copy (regular userspace copy)\n\n## Requirements\n\n* Source and destination files must be on the same filesystem\n* The filesystem must support reflinks (btrfs, xfs with reflink=1)\n* Appropriate file permissions are needed\n\n## Notes\n\n* The arguments are in the same order as `os.Link` or `os.Rename` (src, dst) rather than `io.Copy` (dst, src) as we are dealing with filenames\n* For optimal performance with large files, always try to use reflinks instead of regular copies\n* Reflinks are transparent to applications - a reflinked file behaves exactly like a regular file\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarpeleslab%2Freflink","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarpeleslab%2Freflink","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarpeleslab%2Freflink/lists"}