| Message ID | 20210722000854.1899129-8-felipe.contreras@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | fast-forward: new command with advice and documentation | expand |
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
Philip Oakley wrote: > 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? 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. > > + D---C---B---A---M master > > + \ / > > + X---Y---+ > > +------------ [1] https://www.theatlantic.com/science/archive/2018/04/the-myth-of-learning-styles/557687/
On 23/07/2021 18:10, Felipe Contreras wrote: >> 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. > >>> + D---C---B---A---M master >>> + \ / >>> + X---Y---+ >>> +------------ > [1] https://www.theatlantic.com/science/archive/2018/04/the-myth-of-learning-styles/557687/ It's a double myth, in that many try to suggest that a person has a single style (untrue), or that a single style is relevant in a particular context, when it should be that sometime individuals fail to learn (a particular item) when not provided with a particular style that would suit them in the moment. I.e the removal of a particular format (e.g. no visuals) will reduce the effectiveness of the manual (excepting the 'The pictures are better on radio' aphorism ;-). Philip
Philip Oakley wrote: > On 23/07/2021 18:10, Felipe Contreras wrote: > >> 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. > > > >>> + D---C---B---A---M master > >>> + \ / > >>> + X---Y---+ > >>> +------------ > > [1] https://www.theatlantic.com/science/archive/2018/04/the-myth-of-learning-styles/557687/ > It's a double myth, in that many try to suggest that a person has a > single style (untrue), or that a single style is relevant in a > particular context, when it should be that sometime individuals fail to > learn (a particular item) when not provided with a particular style that > would suit them in the moment. I.e the removal of a particular format > (e.g. no visuals) will reduce the effectiveness of the manual (excepting > the 'The pictures are better on radio' aphorism ;-). The myth (as I understand it) is that people have a primary learning style (e.g. "I'm a visual learner"). The truth is that everyone benefits from multiple styles. Either way--myth or no myth--I think we can agree it's better to have both text and visuals. Cheers.
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 + 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")); }
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(-)