> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/zfs/shou-ce-ye/xi-tong-guan-li-ming-ling-system-administration-8/zfs-rewrite.8.md).

# zfs-rewrite(8)

## 名称

`zfs-rewrite` — 重写指定文件而不修改其内容

## 概述

```sh
zfs rewrite [-CPSWrvx] [-l 长度] [-o 偏移] 文件|目录…
```

## 说明

把指定文件的块原样重写到新位置，且可能应用新属性，就如同这些块被原子地读取后又写回一样。有关重写过程中可能应用的属性变更的更多信息，参见下文的“注释”一节。

### `-C`

跳过通过块克隆（BRT）共享的块。被克隆的块会被多个文件或数据集引用。重写这些块会创建独立的副本，增加空间占用。此标志通过跳过被克隆的块来避免这种扩张。

### `-P`

执行物理重写，保留块的逻辑出生时间。默认情况下，重写会更新逻辑出生时间，使块在快照和增量发送流中显示为已修改。物理重写保留逻辑出生时间，避免块被不必要地纳入增量流。物理重写要求池上已启用 `physical_rewrite` 特性。

### `-S`

跳过与快照共享的块。在最近一次快照之前创建的块会与该快照共享。重写这些块会创建新副本，旧副本仍留给快照，从而增加空间占用。此标志通过跳过与快照共享的块来避免这种扩张。

### `-W`

跳过那些重写后分配大小不会改变的块。RAID-Z 扩容完成后，只有扩容完成前写入的、且以新宽度存储时占用更少空间的块会被重写，因此被中断的重写可以再次运行，而不会重复重写同一批块。小于旧宽度的块会保持其大小并留在原处，这可能使其周围被释放的空间变得碎片化。属性变更可能导致的大小变化（如 `compression` 引起的）不在考虑范围内。在 RAID-Z 以外的 vdev 上，只有 gang 块和位于已移除设备上的块会被重写。

### `-l length`

最多重写这么多字节。

### `-o offset`

从该字节偏移处开始重写。

### `-r`

递归进入目录。

### `-v`

打印所有成功重写的文件名。

### `-x`

递归时不跨越文件系统挂载点。

## 注释

重写的原理是把现有的块替换为逻辑大小相同的新块。重写时会应用那些作用于数据或元数据、但不改变逻辑大小的已变更数据集属性，包括 `checksum`、`compression`、`dedup` 和 `copies`。而会影响逻辑块大小的属性变更（如 `recordsize`）不会生效。

重写被克隆的块和属于任何快照的块，与某些属性变更一样，可能会增加池的空间占用。可以分别使用 `-C` 和 `-S` 标志跳过被克隆的块和与快照共享的块，以避免这种扩张。从未写入过的空洞或此前经过零压缩的空洞不会被重写，即使禁用了压缩，它们也仍会保持为空洞。

在 RAID-Z vdev 上，一旦扩容完成，重写的块会采用该 vdev 扩容后的宽度，参见 zpool-attach(8)。扩容进行时重写的块保持其旧宽度。已去重的块会留在原处，并保持其宽度。

如果 `-l` 或 `-o` 的取值所请求的重写区域超出文件末尾，那么这些区域会被静默忽略，不会报告错误。

默认情况下，重写的块会更新其逻辑出生时间，这意味着它们会作为修改过的数据被纳入增量 `zfs send` 流。使用 `-P` 标志时，由于用户数据没有变化，重写的块会保留其逻辑出生时间。

## 参考文献

zfsprops(7)、zpool-features(7)、zpool-attach(8)

2026 年 10 月 13 日


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://book.bsdcn.org/zfs/shou-ce-ye/xi-tong-guan-li-ming-ling-system-administration-8/zfs-rewrite.8.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
