From 968f4db039f07a6cac32df677301d12025ede873 Mon Sep 17 00:00:00 2001
From: Christos Longros <98426896+chrislongros@users.noreply.github.com>
Date: Mon, 11 May 2026 21:19:28 +0200
Subject: [PATCH] zpool-attach.8: add EXAMPLES section

Mirror-attach (shared with zpool.8 example 5) and raidz expansion.

Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Reviewed-by: Alexander Motin <alexander.motin@TrueNAS.com>
Reviewed-by: Tino Reichardt <milky-zfs@mcmilk.de>
Signed-off-by: Christos Longros <chris.longros@gmail.com>
Closes #18508
---
 man/man8/zpool-attach.8 | 31 ++++++++++++++++++++++++++++++-
 man/man8/zpool.8        |  1 +
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/man/man8/zpool-attach.8 b/man/man8/zpool-attach.8
index 04996ed4fa1..8394a5efba6 100644
--- a/man/man8/zpool-attach.8
+++ b/man/man8/zpool-attach.8
@@ -27,7 +27,7 @@
 .\" Copyright 2017 Nexenta Systems, Inc.
 .\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
 .\"
-.Dd November 8, 2023
+.Dd May 9, 2026
 .Dt ZPOOL-ATTACH 8
 .Os
 .
@@ -132,6 +132,35 @@ Waits until
 has finished resilvering or expanding before returning.
 .El
 .
+.Sh EXAMPLES
+.\" Example 1 is example 5 from zpool.8.
+.\" Make sure to update them bidirectionally
+.Ss Example 1 : No Making a non-mirrored ZFS Storage Pool mirrored
+The following command converts an existing single device
+.Ar sda
+into a mirror by attaching a second device to it,
+.Ar sdb .
+.Dl # Nm zpool Cm attach Ar tank Pa sda sdb
+.
+.Ss Example 2 : No Expanding a RAID-Z vdev with an additional disk
+The following command adds
+.Ar sdg
+to the existing
+.Ar raidz2-0
+vdev in
+.Ar tank ,
+turning a 6-wide RAID-Z2 into a 7-wide RAID-Z2:
+.Dl # Nm zpool Cm attach Ar tank raidz2-0 Pa sdg
+Progress is reported by
+.Nm zpool Cm status .
+The operation requires the
+.Sy raidz_expansion
+pool feature, and
+.Ar sdg
+must be at least as large as the smallest existing disk in the vdev.
+Old blocks keep their original data-to-parity ratio; only blocks written
+after the expansion use the new ratio.
+.
 .Sh SEE ALSO
 .Xr zpool-add 8 ,
 .Xr zpool-detach 8 ,
diff --git a/man/man8/zpool.8 b/man/man8/zpool.8
index 4b07f96bbcb..25dff473c30 100644
--- a/man/man8/zpool.8
+++ b/man/man8/zpool.8
@@ -245,6 +245,7 @@ Invalid command line options were specified.
 .
 .Sh EXAMPLES
 .\" Examples 1, 2, 3, 4, 12, 13 are shared with zpool-create.8.
+.\" Example 5 is shared with zpool-attach.8.
 .\" Examples 6, 14 are shared with zpool-add.8.
 .\" Examples 7, 16 are shared with zpool-list.8.
 .\" Examples 8 are shared with zpool-destroy.8.