Re: [PATCH 7/7] fast-forward: add help about merge vs. rebase

[Philip Oakley <philipoakley@iee.email>]

minor nit/query on format..
On 22/07/2021 01:08, Felipe Contreras wrote:
> 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 <felipe.contreras@gmail.com>
> ---
>  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?

It was my impression that, for ASCII art diagrams, we used space
indenting, leaving tabs for regular text indents. I quss you have an
auto tab setting that converts the 8-spaces to tabs in the source txt.

It is good to have diagrams for the visual learners!

> +    D---C---B---A---M master
> +	 \	   /
> +	  X---Y---+
> +------------
> +
> +This new commit is called a "merge commit" and has two parents (A and Y).
> +
> +Rebasing on the other hand rewrites the history:
> +
> +------------
> +	  origin/master
> +		|
> +		v
> +    D---C---B---A---X'---Y' master
> +------------
> +
> +The commits that diverged (X and Y) are rewritten as if they were created on top
> +of the new base (A). This creates a linear history, which is cleaner, but some
> +people prefer to preserve the original hsitory.
> +
> +In both cases it's likely you would have to resolve conflicts, the difference is
> +that in a merge you would have to do it all at once in one commit, while with a
> +rebase you would have to do it on every rewritten commit.
> +
>  SEE ALSO
>  --------
>  linkgit:git-merge[1], linkgit:git-rebase[1]
> diff --git a/advice.c b/advice.c
> index 60de7fbc4e..7f422b05d3 100644
> --- a/advice.c
> +++ b/advice.c
> @@ -337,5 +337,7 @@ void diverging_advice(void)
>  		"\n"
>  		"or:\n"
>  		"\n"
> -		"\tgit rebase\n"));
> +		"\tgit rebase\n"
> +		"\n"
> +		"For more information check \"git help fast-forward\".\n"));
>  }
--
Philip