doc: Put new options in consistent order on man pages

5 files changed, 294 insertions, 294 deletions

diff --git a/doc/src/sgml/ref/pg_combinebackup.sgml b/doc/src/sgml/ref/pg_combinebackup.sgml
index 55bc46849db..330a598f701 100644
--- a/doc/src/sgml/ref/pg_combinebackup.sgml
+++ b/doc/src/sgml/ref/pg_combinebackup.sgml
@@ -82,6 +82,35 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
+      <term><option>-k</option></term>
+      <term><option>--link</option></term>
+      <listitem>
+       <para>
+        Use hard links instead of copying files to the synthetic backup.
+        Reconstruction of the synthetic backup might be faster (no file copying)
+        and use less disk space, but care must be taken when using the output
+        directory, because any modifications to that directory (for example,
+        starting the server) can also affect the input directories. Likewise,
+        changes to the input directories (for example, starting the server on
+        the full backup) could affect the output directory. Thus, this option
+        is best used when the input directories are only copies that will be
+        removed after <application>pg_combinebackup</application> has completed.
+       </para>
+
+       <para>
+        Requires that the input backups and the output directory are in the
+        same file system.
+       </para>
+
+       <para>
+        If a backup manifest is not available or does not contain checksum of
+        the right type, hard links will still be created, but the file will be
+        also read block-by-block for the checksum calculation.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><option>-n</option></term>
       <term><option>--dry-run</option></term>
       <listitem>
@@ -138,35 +167,6 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>-k</option></term>
-      <term><option>--link</option></term>
-      <listitem>
-       <para>
-        Use hard links instead of copying files to the synthetic backup.
-        Reconstruction of the synthetic backup might be faster (no file copying)
-        and use less disk space, but care must be taken when using the output
-        directory, because any modifications to that directory (for example,
-        starting the server) can also affect the input directories. Likewise,
-        changes to the input directories (for example, starting the server on
-        the full backup) could affect the output directory. Thus, this option
-        is best used when the input directories are only copies that will be
-        removed after <application>pg_combinebackup</application> has completed.
-       </para>
-
-       <para>
-        Requires that the input backups and the output directory are in the
-        same file system.
-       </para>
-
-       <para>
-        If a backup manifest is not available or does not contain checksum of
-        the right type, hard links will still be created, but the file will be
-        also read block-by-block for the checksum calculation.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
       <term><option>--clone</option></term>
       <listitem>
        <para>
diff --git a/doc/src/sgml/ref/pg_resetwal.sgml b/doc/src/sgml/ref/pg_resetwal.sgml
index dd011d246c1..2c019c2aac6 100644
--- a/doc/src/sgml/ref/pg_resetwal.sgml
+++ b/doc/src/sgml/ref/pg_resetwal.sgml
@@ -172,25 +172,6 @@ PostgreSQL documentation
 
   <variablelist>
    <varlistentry>
-    <term><option>--char-signedness=<replaceable class="parameter">option</replaceable></option></term>
-    <listitem>
-     <para>
-      Manually set the default char signedness. Possible values are
-      <literal>signed</literal> and <literal>unsigned</literal>.
-     </para>
-     <para>
-      For a database cluster that <command>pg_upgrade</command> upgraded from
-      a <productname>PostgreSQL</productname> version before 18, the safe
-      value would be the default <type>char</type> signedness of the platform
-      that ran the cluster before that upgrade. For all other
-      clusters, <literal>signed</literal> would be the safe value. However,
-      this option is exclusively for use with <command>pg_upgrade</command>
-      and should not normally be used manually.
-     </para>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
     <term><option>-c <replaceable class="parameter">xid</replaceable>,<replaceable class="parameter">xid</replaceable></option></term>
     <term><option>--commit-timestamp-ids=<replaceable class="parameter">xid</replaceable>,<replaceable class="parameter">xid</replaceable></option></term>
     <listitem>
@@ -333,34 +314,6 @@ PostgreSQL documentation
    </varlistentry>
 
    <varlistentry>
-    <term><option>--wal-segsize=<replaceable class="parameter">wal_segment_size</replaceable></option></term>
-    <listitem>
-     <para>
-      Set the new WAL segment size, in megabytes.  The value must be set to a
-      power of 2 between 1 and 1024 (megabytes).  See the same option of <xref
-      linkend="app-initdb"/> for more information.
-     </para>
-
-     <para>
-      This option can also be used to change the WAL segment size of an
-      existing database cluster, avoiding the need to
-      re-<command>initdb</command>.
-     </para>
-
-     <note>
-      <para>
-       While <command>pg_resetwal</command> will set the WAL starting address
-       beyond the latest existing WAL segment file, some segment size changes
-       can cause previous WAL file names to be reused.  It is recommended to
-       use <option>-l</option> together with this option to manually set the
-       WAL starting address if WAL file name overlap will cause problems with
-       your archiving strategy.
-      </para>
-     </note>
-    </listitem>
-   </varlistentry>
-
-   <varlistentry>
     <term><option>-u <replaceable class="parameter">xid</replaceable></option></term>
     <term><option>--oldest-transaction-id=<replaceable class="parameter">xid</replaceable></option></term>
     <listitem>
@@ -402,6 +355,53 @@ PostgreSQL documentation
      <!-- 1048576 = SLRU_PAGES_PER_SEGMENT * BLCKSZ * CLOG_XACTS_PER_BYTE -->
     </listitem>
    </varlistentry>
+
+   <varlistentry>
+    <term><option>--char-signedness=<replaceable class="parameter">option</replaceable></option></term>
+    <listitem>
+     <para>
+      Manually set the default char signedness. Possible values are
+      <literal>signed</literal> and <literal>unsigned</literal>.
+     </para>
+     <para>
+      For a database cluster that <command>pg_upgrade</command> upgraded from
+      a <productname>PostgreSQL</productname> version before 18, the safe
+      value would be the default <type>char</type> signedness of the platform
+      that ran the cluster before that upgrade. For all other
+      clusters, <literal>signed</literal> would be the safe value. However,
+      this option is exclusively for use with <command>pg_upgrade</command>
+      and should not normally be used manually.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>--wal-segsize=<replaceable class="parameter">wal_segment_size</replaceable></option></term>
+    <listitem>
+     <para>
+      Set the new WAL segment size, in megabytes.  The value must be set to a
+      power of 2 between 1 and 1024 (megabytes).  See the same option of <xref
+      linkend="app-initdb"/> for more information.
+     </para>
+
+     <para>
+      This option can also be used to change the WAL segment size of an
+      existing database cluster, avoiding the need to
+      re-<command>initdb</command>.
+     </para>
+
+     <note>
+      <para>
+       While <command>pg_resetwal</command> will set the WAL starting address
+       beyond the latest existing WAL segment file, some segment size changes
+       can cause previous WAL file names to be reused.  It is recommended to
+       use <option>-l</option> together with this option to manually set the
+       WAL starting address if WAL file name overlap will cause problems with
+       your archiving strategy.
+      </para>
+     </note>
+    </listitem>
+   </varlistentry>
   </variablelist>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index b6de497aee1..2295df62d03 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -178,28 +178,6 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>--exclude-database=<replaceable class="parameter">pattern</replaceable></option></term>
-      <listitem>
-       <para>
-        Do not restore databases whose name matches
-        <replaceable class="parameter">pattern</replaceable>.
-        Multiple patterns can be excluded by writing multiple
-        <option>--exclude-database</option> switches.  The
-        <replaceable class="parameter">pattern</replaceable> parameter is
-        interpreted as a pattern according to the same rules used by
-        <application>psql</application>'s <literal>\d</literal>
-        commands (see <xref linkend="app-psql-patterns"/>),
-        so multiple databases can also be excluded by writing wildcard
-        characters in the pattern.  When using wildcards, be careful to
-        quote the pattern if needed to prevent shell wildcard expansion.
-       </para>
-       <para>
-        This option is only relevant when restoring from an archive made using <application>pg_dumpall</application>.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
       <term><option>-e</option></term>
       <term><option>--exit-on-error</option></term>
       <listitem>
@@ -224,86 +202,6 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>--filter=<replaceable class="parameter">filename</replaceable></option></term>
-      <listitem>
-       <para>
-        Specify a filename from which to read patterns for objects excluded
-        or included from restore. The patterns are interpreted according to the
-        same rules as
-        <option>-n</option>/<option>--schema</option> for including objects in schemas,
-        <option>-N</option>/<option>--exclude-schema</option> for excluding objects in schemas,
-        <option>-P</option>/<option>--function</option> for restoring named functions,
-        <option>-I</option>/<option>--index</option> for restoring named indexes,
-        <option>-t</option>/<option>--table</option> for restoring named tables
-        or <option>-T</option>/<option>--trigger</option> for restoring triggers.
-        To read from <literal>STDIN</literal>, use <filename>-</filename> as the
-        filename.  The <option>--filter</option> option can be specified in
-        conjunction with the above listed options for including or excluding
-        objects, and can also be specified more than once for multiple filter
-        files.
-       </para>
-
-       <para>
-        The file lists one database pattern per row, with the following format:
-<synopsis>
-{ include | exclude } { function | index | schema | table | trigger } <replaceable class="parameter">PATTERN</replaceable>
-</synopsis>
-       </para>
-
-       <para>
-        The first keyword specifies whether the objects matched by the pattern
-        are to be included or excluded. The second keyword specifies the type
-        of object to be filtered using the pattern:
-        <itemizedlist>
-         <listitem>
-          <para>
-           <literal>function</literal>: functions, works like the
-           <option>-P</option>/<option>--function</option> option. This keyword
-           can only be used with the <literal>include</literal> keyword.
-          </para>
-         </listitem>
-         <listitem>
-          <para>
-           <literal>index</literal>: indexes, works like the
-           <option>-I</option>/<option>--indexes</option> option. This keyword
-           can only be used with the <literal>include</literal> keyword.
-          </para>
-         </listitem>
-         <listitem>
-          <para>
-           <literal>schema</literal>: schemas, works like the
-           <option>-n</option>/<option>--schema</option> and
-           <option>-N</option>/<option>--exclude-schema</option> options.
-          </para>
-         </listitem>
-         <listitem>
-          <para>
-           <literal>table</literal>: tables, works like the
-           <option>-t</option>/<option>--table</option> option. This keyword
-           can only be used with the <literal>include</literal> keyword.
-          </para>
-         </listitem>
-         <listitem>
-          <para>
-           <literal>trigger</literal>: triggers, works like the
-           <option>-T</option>/<option>--trigger</option> option. This keyword
-           can only be used with the <literal>include</literal> keyword.
-          </para>
-         </listitem>
-        </itemizedlist>
-       </para>
-
-       <para>
-        Lines starting with <literal>#</literal> are considered comments and
-        ignored. Comments can be placed after an object pattern row as well.
-        Blank lines are also ignored. See <xref linkend="app-psql-patterns"/>
-        for how to perform quoting in patterns.
-       </para>
-
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
       <term><option>-F <replaceable class="parameter">format</replaceable></option></term>
       <term><option>--format=<replaceable class="parameter">format</replaceable></option></term>
       <listitem>
@@ -647,15 +545,6 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>--statistics-only</option></term>
-      <listitem>
-       <para>
-        Restore only the statistics, not schema (data definitions) or data.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
       <term><option>-1</option></term>
       <term><option>--single-transaction</option></term>
       <listitem>
@@ -715,6 +604,108 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
+      <term><option>--exclude-database=<replaceable class="parameter">pattern</replaceable></option></term>
+      <listitem>
+       <para>
+        Do not restore databases whose name matches
+        <replaceable class="parameter">pattern</replaceable>.
+        Multiple patterns can be excluded by writing multiple
+        <option>--exclude-database</option> switches.  The
+        <replaceable class="parameter">pattern</replaceable> parameter is
+        interpreted as a pattern according to the same rules used by
+        <application>psql</application>'s <literal>\d</literal>
+        commands (see <xref linkend="app-psql-patterns"/>),
+        so multiple databases can also be excluded by writing wildcard
+        characters in the pattern.  When using wildcards, be careful to
+        quote the pattern if needed to prevent shell wildcard expansion.
+       </para>
+       <para>
+        This option is only relevant when restoring from an archive made using <application>pg_dumpall</application>.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>--filter=<replaceable class="parameter">filename</replaceable></option></term>
+      <listitem>
+       <para>
+        Specify a filename from which to read patterns for objects excluded
+        or included from restore. The patterns are interpreted according to the
+        same rules as
+        <option>-n</option>/<option>--schema</option> for including objects in schemas,
+        <option>-N</option>/<option>--exclude-schema</option> for excluding objects in schemas,
+        <option>-P</option>/<option>--function</option> for restoring named functions,
+        <option>-I</option>/<option>--index</option> for restoring named indexes,
+        <option>-t</option>/<option>--table</option> for restoring named tables
+        or <option>-T</option>/<option>--trigger</option> for restoring triggers.
+        To read from <literal>STDIN</literal>, use <filename>-</filename> as the
+        filename.  The <option>--filter</option> option can be specified in
+        conjunction with the above listed options for including or excluding
+        objects, and can also be specified more than once for multiple filter
+        files.
+       </para>
+
+       <para>
+        The file lists one database pattern per row, with the following format:
+<synopsis>
+{ include | exclude } { function | index | schema | table | trigger } <replaceable class="parameter">PATTERN</replaceable>
+</synopsis>
+       </para>
+
+       <para>
+        The first keyword specifies whether the objects matched by the pattern
+        are to be included or excluded. The second keyword specifies the type
+        of object to be filtered using the pattern:
+        <itemizedlist>
+         <listitem>
+          <para>
+           <literal>function</literal>: functions, works like the
+           <option>-P</option>/<option>--function</option> option. This keyword
+           can only be used with the <literal>include</literal> keyword.
+          </para>
+         </listitem>
+         <listitem>
+          <para>
+           <literal>index</literal>: indexes, works like the
+           <option>-I</option>/<option>--indexes</option> option. This keyword
+           can only be used with the <literal>include</literal> keyword.
+          </para>
+         </listitem>
+         <listitem>
+          <para>
+           <literal>schema</literal>: schemas, works like the
+           <option>-n</option>/<option>--schema</option> and
+           <option>-N</option>/<option>--exclude-schema</option> options.
+          </para>
+         </listitem>
+         <listitem>
+          <para>
+           <literal>table</literal>: tables, works like the
+           <option>-t</option>/<option>--table</option> option. This keyword
+           can only be used with the <literal>include</literal> keyword.
+          </para>
+         </listitem>
+         <listitem>
+          <para>
+           <literal>trigger</literal>: triggers, works like the
+           <option>-T</option>/<option>--trigger</option> option. This keyword
+           can only be used with the <literal>include</literal> keyword.
+          </para>
+         </listitem>
+        </itemizedlist>
+       </para>
+
+       <para>
+        Lines starting with <literal>#</literal> are considered comments and
+        ignored. Comments can be placed after an object pattern row as well.
+        Blank lines are also ignored. See <xref linkend="app-psql-patterns"/>
+        for how to perform quoting in patterns.
+       </para>
+
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><option>--if-exists</option></term>
       <listitem>
        <para>
@@ -852,33 +843,6 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>--with-data</option></term>
-      <listitem>
-       <para>
-        Dump data. This is the default.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>--with-schema</option></term>
-      <listitem>
-       <para>
-        Dump schema (data definitions). This is the default.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>--with-statistics</option></term>
-      <listitem>
-       <para>
-        Dump statistics. This is the default.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
        <term><option>--section=<replaceable class="parameter">sectionname</replaceable></option></term>
        <listitem>
          <para>
@@ -898,6 +862,15 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
+      <term><option>--statistics-only</option></term>
+      <listitem>
+       <para>
+        Restore only the statistics, not schema (data definitions) or data.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><option>--strict-names</option></term>
       <listitem>
        <para>
@@ -947,6 +920,33 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
+      <term><option>--with-data</option></term>
+      <listitem>
+       <para>
+        Dump data. This is the default.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>--with-schema</option></term>
+      <listitem>
+       <para>
+        Dump schema (data definitions). This is the default.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>--with-statistics</option></term>
+      <listitem>
+       <para>
+        Dump statistics. This is the default.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
        <term><option>-?</option></term>
        <term><option>--help</option></term>
        <listitem>
diff --git a/doc/src/sgml/ref/pg_verifybackup.sgml b/doc/src/sgml/ref/pg_verifybackup.sgml
index 53341024cd2..61c12975e4a 100644
--- a/doc/src/sgml/ref/pg_verifybackup.sgml
+++ b/doc/src/sgml/ref/pg_verifybackup.sgml
@@ -144,35 +144,6 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>-i <replaceable class="parameter">path</replaceable></option></term>
-      <term><option>--ignore=<replaceable class="parameter">path</replaceable></option></term>
-      <listitem>
-       <para>
-        Ignore the specified file or directory, which should be expressed
-        as a relative path name, when comparing the list of data files
-        actually present in the backup to those listed in the
-        <literal>backup_manifest</literal> file.  If a directory is
-        specified, this option affects the entire subtree rooted at that
-        location. Complaints about extra files, missing files, file size
-        differences, or checksum mismatches will be suppressed if the
-        relative path name matches the specified path name. This option
-        can be specified multiple times.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>-m <replaceable class="parameter">path</replaceable></option></term>
-      <term><option>--manifest-path=<replaceable class="parameter">path</replaceable></option></term>
-      <listitem>
-       <para>
-        Use the manifest file at the specified path, rather than one located
-        in the root of the backup directory.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
       <term><option>-F <replaceable class="parameter">format</replaceable></option></term>
       <term><option>--format=<replaceable class="parameter">format</replaceable></option></term>
       <listitem>
@@ -212,6 +183,35 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
+      <term><option>-i <replaceable class="parameter">path</replaceable></option></term>
+      <term><option>--ignore=<replaceable class="parameter">path</replaceable></option></term>
+      <listitem>
+       <para>
+        Ignore the specified file or directory, which should be expressed
+        as a relative path name, when comparing the list of data files
+        actually present in the backup to those listed in the
+        <literal>backup_manifest</literal> file.  If a directory is
+        specified, this option affects the entire subtree rooted at that
+        location. Complaints about extra files, missing files, file size
+        differences, or checksum mismatches will be suppressed if the
+        relative path name matches the specified path name. This option
+        can be specified multiple times.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-m <replaceable class="parameter">path</replaceable></option></term>
+      <term><option>--manifest-path=<replaceable class="parameter">path</replaceable></option></term>
+      <listitem>
+       <para>
+        Use the manifest file at the specified path, rather than one located
+        in the root of the backup directory.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><option>-n</option></term>
       <term><option>--no-parse-wal</option></term>
       <listitem>
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index cb8e4f5c48a..aeeed297437 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -146,15 +146,6 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>--no-statistics</option></term>
-      <listitem>
-       <para>
-        Do not restore statistics from the old cluster into the new cluster.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
       <term><option>-o</option> <replaceable class="parameter">options</replaceable></term>
       <term><option>--old-options</option> <replaceable class="parameter">options</replaceable></term>
       <listitem><para>options to be passed directly to the
@@ -264,50 +255,10 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>--swap</option></term>
-      <listitem>
-       <para>
-        Move the data directories from the old cluster to the new cluster.
-        Then, replace the catalog files with those generated for the new
-        cluster.  This mode can outperform <option>--link</option>,
-        <option>--clone</option>, <option>--copy</option>, and
-        <option>--copy-file-range</option>, especially on clusters with many
-        relations.
-       </para>
-       <para>
-        However, this mode creates many garbage files in the old cluster, which
-        can prolong the file synchronization step if
-        <option>--sync-method=syncfs</option> is used.  Therefore, it is
-        recommended to use <option>--sync-method=fsync</option> with
-        <option>--swap</option>.
-       </para>
-       <para>
-        Additionally, once the file transfer step begins, the old cluster will
-        be destructively modified and therefore will no longer be safe to
-        start.  See <xref linkend="pgupgrade-step-revert"/> for details.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>--sync-method=</option><replaceable>method</replaceable></term>
+      <term><option>--no-statistics</option></term>
       <listitem>
        <para>
-        When set to <literal>fsync</literal>, which is the default,
-        <command>pg_upgrade</command> will recursively open and synchronize all
-        files in the upgraded cluster's data directory.  The search for files
-        will follow symbolic links for the WAL directory and each configured
-        tablespace.
-       </para>
-       <para>
-        On Linux, <literal>syncfs</literal> may be used instead to ask the
-        operating system to synchronize the whole file systems that contain the
-        upgraded cluster's data directory, its WAL files, and each tablespace.
-        See <xref linkend="guc-recovery-init-sync-method"/> for information
-        about the caveats to be aware of when using <literal>syncfs</literal>.
-       </para>
-       <para>
-        This option has no effect when <option>--no-sync</option> is used.
+        Do not restore statistics from the old cluster into the new cluster.
        </para>
       </listitem>
      </varlistentry>
@@ -366,6 +317,55 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
+      <term><option>--swap</option></term>
+      <listitem>
+       <para>
+        Move the data directories from the old cluster to the new cluster.
+        Then, replace the catalog files with those generated for the new
+        cluster.  This mode can outperform <option>--link</option>,
+        <option>--clone</option>, <option>--copy</option>, and
+        <option>--copy-file-range</option>, especially on clusters with many
+        relations.
+       </para>
+       <para>
+        However, this mode creates many garbage files in the old cluster, which
+        can prolong the file synchronization step if
+        <option>--sync-method=syncfs</option> is used.  Therefore, it is
+        recommended to use <option>--sync-method=fsync</option> with
+        <option>--swap</option>.
+       </para>
+       <para>
+        Additionally, once the file transfer step begins, the old cluster will
+        be destructively modified and therefore will no longer be safe to
+        start.  See <xref linkend="pgupgrade-step-revert"/> for details.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>--sync-method=</option><replaceable>method</replaceable></term>
+      <listitem>
+       <para>
+        When set to <literal>fsync</literal>, which is the default,
+        <command>pg_upgrade</command> will recursively open and synchronize all
+        files in the upgraded cluster's data directory.  The search for files
+        will follow symbolic links for the WAL directory and each configured
+        tablespace.
+       </para>
+       <para>
+        On Linux, <literal>syncfs</literal> may be used instead to ask the
+        operating system to synchronize the whole file systems that contain the
+        upgraded cluster's data directory, its WAL files, and each tablespace.
+        See <xref linkend="guc-recovery-init-sync-method"/> for information
+        about the caveats to be aware of when using <literal>syncfs</literal>.
+       </para>
+       <para>
+        This option has no effect when <option>--no-sync</option> is used.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><option>-?</option></term>
       <term><option>--help</option></term>
       <listitem><para>show help, then exit</para></listitem>