Philip Oakley wrote:

minor nit/query on format..
On 22/07/2021 01:08, Felipe Contreras wrote:

quoted

Now that we have a locus for merge versus rebase documentation, we can
refer to it on the diverging advice.

Signed-off-by: Felipe Contreras <redacted>
---
 Documentation/git-fast-forward.txt | 48 ++++++++++++++++++++++++++++++
 advice.c                           |  4 ++-
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-fast-forward.txt b/Documentation/git-fast-forward.txt
index 38c920964f..1989fdec4a 100644
--- a/Documentation/git-fast-forward.txt
+++ b/Documentation/git-fast-forward.txt

@@ -50,6 +50,54 @@ synchronize the two branches.
 
 THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOUR MAY CHANGE.
 
+MERGE OR REBASE
+---------------
+
+The decision to whether merge or rebase depends on the situation and the
+project. Traditionally git has prefered merge over rebase, but that creates a
+new commit, and that's frowned up on some projects, so you can't just simply
+choose to merge blindly.
+
+------------
+    D---C---B---A origin/master
+	 \
+	  X---Y master
+------------
+
+The nature of distributed version control systems make this divergence
+unavoidable; you must decide how to synchronize this divergence.
+
+Should you choose to merge, the two heads (master and origin/master) will be joined
+together in a new commit:
+
+------------
+	  origin/master
+		|
+		v

.. here, in my email reader, the arrow doesn't align to the commit
because of the single char (+) indent relative to tab spacing. Does this
cause any problems when formatted in the html/web style?

No, it looks fine.

I don't have a problem with tabs or spaces, but git-pull.txt uses tabs.

It is good to have diagrams for the visual learners!

Actually, it seems there's no such thing as "visual learners" [1]; we
are all visual learners.

Cheers.

quoted

+    D---C---B---A---M master
+	 \	   /
+	  X---Y---+
+------------

[1] https://www.theatlantic.com/science/archive/2018/04/the-myth-of-learning-styles/557687/

-- 
Felipe Contreras