Re: [PATCH 1/2] doc: pull: explain what is a fast-forward

[Philip Oakley <philipoakley@iee.email>]

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@gmail.com>
> ---
>  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
>  ---