clonetree 0.0.1

A copy-on-write directory library for Rust with fast reflink cloning
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# clonetree

**A copy‑on‑write directory library for Rust**

`clonetree` is a **Rust crate** for fast directory duplication. It uses
filesystem‑level *reflinks* so large trees are cloned quickly and consume no
extra space until files diverge.

---

## Highlights

* **Fast copy‑on‑write clone** on APFS, Btrfs, XFS, bcachefs, overlayfs, ReFS…

* **Powered by [`reflink-copy`](https://github.com/cargo-bins/reflink-copy)** for portable block‑cloning.

* **Flexible glob patterns** to include/exclude files (uses `!` prefix for exclusions).

* **Graceful fallback** to `std::fs::copy` when reflinks are unsupported.

* **Pure Rust**, no unsafe code, minimal deps.

---

## Library quick start

Clone only Rust source files under `src/` into `./sandbox`, while excluding
unit tests. This demonstrates the precedence rules from the
[`ignore`](https://docs.rs/ignore) crate: later patterns override earlier ones.

```rust
use clonetree::{clone_tree, Options};

fn main() -> anyhow::Result<()> {
    // Include all source files but drop tests
    let opts = Options::new()
        .glob("src/**")         // positive include
        .glob("!src/tests/**"); // negative exclude; overrides the line above

    clone_tree("./", "./sandbox", &opts)?;
    Ok(())
}
```

---

## Glob syntax

`clonetree` accepts the same glob rules as a single line in a `.gitignore`
file. Prefix a pattern with `!` to **exclude** matching paths instead of
including them.

| Pattern             | Description                                      |
| ------------------- | ------------------------------------------------ |
| `*.rs`              | All Rust source files in the current directory   |
| `**/*.toml`         | Any `.toml` file at any depth                    |
| `!target/**`        | **Exclude** Cargo build artefacts                |
| `images/**/thumb_*` | Every `thumb_*` file under `images/` recursively |

Rules:

* `*` matches any sequence of characters except path separators.
* `**` matches across directory boundaries.
* `?` matches exactly one character.
* A trailing `/` restricts the pattern to directories only.
* Patterns are evaluated **in the order they are given**; later patterns can
  override earlier ones (precedence follows the `ignore` crate).

---

## `ctree` ‑ command‑line tool

The crate ships with a convenience binary so users can benefit without writing code.

### Install

```bash
cargo install ctree
```

### Semantics

`ctree` copies a directory to a specified destination. The source must be a
directory, and the destination must not exist. 

### Basic usage

```bash
ctree <SRC> <DEST> [OPTIONS]

OPTIONS:
  -g, --glob <GLOB>      Match or exclude glob (repeatable)
      --no-reflink       Disable reflink, perform a regular copy
  -q, --quiet            Suppress progress output
  -h, --help             Show this help
```

Example: snapshot a repo while excluding Git metadata and build output:

```bash
ctree . ./sandbox \
  --glob '!target/**' \
  --glob '!.git/**'
```

---

## Filesystem support matrix

Via [reflink-copy](https://crates.io/crates/reflink-copy)

| OS / FS                        | Reflink supported | API used                          | Behaviour          |
| ------------------------------ | ----------------- | --------------------------------- | ------------------ |
| macOS 10.13+ / APFS            | ✅                 | `clonefile(2)`                    | COW clone          |
| iOS / APFS                     | ✅                 | `clonefile(2)`                    | COW clone          |
| Linux 6.7+ / Btrfs             | ✅                 | `FICLONE` ioctl                   | COW clone          |
| Linux 5.4+ / XFS (`reflink=1`) | ✅                 | `FICLONE` ioctl                   | COW clone          |
| Linux 6.1+ / bcachefs          | ✅                 | `remap_file_range`                | COW clone          |
| Linux 5.13+ / overlayfs        | ✅                 | `remap_file_range`                | COW clone          |
| Windows Server 2016+ / ReFS    | ✅                 | `FSCTL_DUPLICATE_EXTENTS_TO_FILE` | COW clone          |
| ext4 (Ubuntu/Fedora default)   | ❌                 | –                                 | Byte‑for‑byte copy |