On 21/06/2021 18:52, Felipe Contreras wrote: > We want users to know what is a fast-forward in order to understand the > default warning. > > Let's expand the explanation in order to cover both the simple, and the > complex cases with as much detail as possible. > > Signed-off-by: Felipe Contreras <felipe.contreras@xxxxxxxxx> > --- > Documentation/git-pull.txt | 41 ++++++++++++++++++++++++++++++++------ > 1 file changed, 35 insertions(+), 6 deletions(-) > > diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt > index 5c3fb67c01..142df1c4a1 100644 > --- a/Documentation/git-pull.txt > +++ b/Documentation/git-pull.txt > @@ -41,16 +41,41 @@ Assume the following history exists and the current branch is > ------------ > A---B---C master on origin > / > - D---E---F---G master > + D---E master > ^ > origin/master in your repository > ------------ > > Then "`git pull`" will fetch and replay the changes from the remote > `master` branch since it diverged from the local `master` (i.e., `E`) > -until its current commit (`C`) on top of `master` and record the > -result in a new commit along with the names of the two parent commits > -and a log message from the user describing the changes. > +until its current commit (`C`) on top of `master`. > + > +After the remote changes have been synchronized, the local `master` will > +be fast-forwarded to the same commit as the remote one, therefore Perhaps s/be fast-forwarded/have been 'fast-forward'ed/ ? I.E. we highlight the term "fast-forward" (the purpose of the patch) and we hint at the underlying mechanism of simply moving the branch pointer. > +creating a linear history. > + > +------------ > + D---E---A---B---C master, origin/master > +------------ > + > +However, a non-fast-forward case looks very different: > + > +------------ > + A---B---C origin/master > + / > + D---E---F---G master > +------------ > + > +If there are additional changes in the local `master`, it's > +not possible to fast-forward, so a decision must be made how to > +synchronize the local, and remote brances. > + > +In these situations `git pull` will warn you about your possible > +options, which are either merge (`--no-rebase`), or rebase (`--rebase`). > +However, by default it will continue doing a merge. > + > +A merge will create a new commit with two parent commits (`G` and `C`) > +and a log message describing the changes, which you can edit. > > ------------ > A---B---C origin/master > @@ -58,8 +83,11 @@ and a log message from the user describing the changes. > D---E---F---G---H master > ------------ > > +Once the merge commit is created (`H`), your local `master` branch has > +incorporated the changes of the remote `master` branch. > + > See linkgit:git-merge[1] for details, including how conflicts > -are presented and handled. > +are presented and handled, and also linkgit:git-rebase[1]. > > In Git 1.7.0 or later, to cancel a conflicting merge, use > `git reset --merge`. *Warning*: In older versions of Git, running 'git pull' > @@ -248,7 +276,8 @@ version. > > SEE ALSO > -------- > -linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1] > +linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-rebase[1], > +linkgit:git-config[1] > > GIT > ---
