commit 5ccb2ae150b68ab2231b94474b68d16ecbaf90a8
Author: jcoleman <james.coleman@getbraintree.com>
Date:   Fri Sep 13 17:28:53 2019 +0000

    Correct pg_rewind explanation
    
    The pg_rewind docs assert that the state of the target's data directory
    after rewind is equivalent to the source's data directory. But that
    isn't true both because the base state is further back in time and
    because the target's data directory will include the current state on
    the source of any copied blocks.
    
    In additional document clearly the state of the cluster after the
    operation and also the operation sequencing dangers caused by copying
    configuration files from the source.

diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
index ac142d22fc..e3aeb529de 100644
--- a/doc/src/sgml/ref/pg_rewind.sgml
+++ b/doc/src/sgml/ref/pg_rewind.sgml
@@ -48,14 +48,17 @@ PostgreSQL documentation
   </para>
 
   <para>
-   The result is equivalent to replacing the target data directory with the
-   source one. Only changed blocks from relation files are copied;
-   all other files are copied in full, including configuration files. The
-   advantage of <application>pg_rewind</application> over taking a new base backup, or
-   tools like <application>rsync</application>, is that <application>pg_rewind</application> does
-   not require reading through unchanged blocks in the cluster. This makes
-   it a lot faster when the database is large and only a small
-   fraction of blocks differ between the clusters.
+   After a successful rewind, the target data directory is equivalent to the
+   to the state of the data directory at the point at which the source and
+   target diverged plus the current state on the source of any blocks changed
+   on the target after that divergence. While only changed blocks from relation
+   files are copied; all other files are copied in full, including configuration
+   files and WAL segments. The advantage of <application>pg_rewind</application>
+   over taking a new base backup, or tools like <application>rsync</application>,
+   is that <application>pg_rewind</application> does not require comparing or 
+   copying unchanged relation blocks in the cluster. As such the rewind operation
+   is significantly faster than other approaches when the database is large and
+   only a small fraction of blocks differ between the clusters.
   </para>
 
   <para>
@@ -116,6 +119,23 @@ PostgreSQL documentation
     be necessary to remove the data copied and restore back the set of links
     used before the rewind.
    </para>
+
+   <para>
+    The result of the rewind operation is not expected to be a consistent
+    data directory state either internally to the node or with respect to
+    the rest of the cluster. Instead the resulting data directory will only
+    be consistent after WAL replay has completed to at least the LSN at which
+    changed blocks copied from the source were originally written on the source.
+   </para>
+   
+  <para>
+    Because <application>pg_rewind</application> copies configuration files
+    entirely from the source, correcting recovery configuration options before
+    restarting the server is necessary if you intend to re-introduce the target
+    as a replica of the source. If you restart the server after the rewind
+    operation has finished but without configuring recovery, the target will
+    again diverge from the primary.
+   </para>
   </warning>
  </refsect1>