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@xxxxxxxxx> > --- > 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
