[PATCH 0/7] fast-forward: new command with advice and documentation

[PATCH 0/7] fast-forward: new command with advice and documentation

[Felipe Contreras]

Fast-forwards have frequently been the subject of debate over the years.
Are they a modifier? (adverb), are they a command? (verb), are they an
object? (noun).

While these semantic debates are unlikely to go away, what is clear is
that people have wanted to do these fast-forwards since as far back as
2008 [1].

Moreover, all the discussions about the brokenness of `git pull` have
lead to the conclusion that to synchronize changes there are three
basic actions users might want to do:

  * fast-forward
  * merge
  * rebase

We have commands for the latter two, why not the former?

`git fast-forward` is much more user friendly than
`git merge --ff-only`, and additionally we can print an advice when the
fast-forward is not possible, plus we can explain in the documentation
what is a fast-forward, when to choose a merge, and when to choose a
rebase:

  git help fast-forward

Moreover, this will help further efforts to fix `git pull` by
simplifying the mental model of users:

  * git pull          -> git fast-forward
  * git pull --merge  -> git merge
  * git pull --rebase -> git rebase

Not to mention other efforts like my proposed `git update` [2].

This is just the first part of my `git update` patch series [2], which
actually received feedback so presumably there's a recognition of
usefulness.

I reordered the series to add the advice first due to comments from
Ævar Arnfjörð Bjarmason, added more clarifications in the commit
messages, fixed one test, and improved the documentation.

This is v1 since the previous series was a RFC and contained a lot more
changes, but I'm attaching the range-diff of these patches anyway.

[1] https://lore.kernel.org/git/loom.20080116T151930-575@post.gmane.org/
[2] https://lore.kernel.org/git/20210705123209.1808663-1-felipe.contreras@gmail.com/

1:  456cc92db3 ! 1:  c04cae2379 merge: improve fatal fast-forward message
    @@ Metadata
      ## Commit message ##
         merge: improve fatal fast-forward message
     
    +    The documentation of --ff-only says:
    +
    +      With `--ff-only`, resolve the merge as a fast-forward when possible.
    +      When not possible, refuse to merge and exit with a non-zero status.
    +
    +    So when the user does --ff-only, and a fast-forward is not possible, the
    +    user wants git to abort, therefore an error message of:
    +
    +     fatal: Not possible to fast-forward, aborting.
    +
    +    is redundant; no need to say ", aborting".
    +
    +    Additionally, use lowercase and lose the full stop to be consistent with
    +    other die() messages.
    +
         Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
     
      ## builtin/merge.c ##
5:  fbbde141b3 ! 2:  d99c5ec51e fast-forward: add advice for novices
    @@ Metadata
     Author: Felipe Contreras <felipe.contreras@gmail.com>
     
      ## Commit message ##
    -    fast-forward: add advice for novices
    +    merge: add diverging advice for novices
     
    -    It doesn't hurt showing it on `git merge --ff-only` too.
    +    Diverging branches is one of the most confusing aspects of distributed
    +    version control systems for novices, so a little help explaining what to
    +    do on those situations will come in handy.
    +
    +    Right now this advice will be displayed only when the user does
    +    `git merge --ff-only`, `git pull --ff-only`, or has configured
    +    `pull.ff=only` for `git pull`, but in the future it's expected that
    +    --ff-only will be the default for `git pull`, and a proposed `git
    +    fast-forward` command will imply --ff-only, in addition to `git update`.
    +
    +    So it makes sense to add the advice in preparation for those future
    +    changes, although even currently it helps.
     
         Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
     
    @@ advice.h: void NORETURN die_resolve_conflict(const char *me);
      #endif /* ADVICE_H */
     
      ## builtin/merge.c ##
    -@@ builtin/merge.c: static int merge_common(int argc, const char **argv, const char *prefix,
    +@@ builtin/merge.c: int cmd_merge(int argc, const char **argv, const char *prefix)
      		}
      	}
      
6:  75be93e2f6 ! 3:  7bb27c22ad fast-forward: make the advise configurable
    @@ Metadata
     Author: Felipe Contreras <felipe.contreras@gmail.com>
     
      ## Commit message ##
    -    fast-forward: make the advise configurable
    +    merge: make the diverging advise configurable
     
         With advice.diverging.
     
2:  4430c62ccc = 4:  d7943e9826 merge: split cmd_merge()
3:  891462cc8b ! 5:  f70db9b464 fast-forward: add new builtin
    @@ Commit message
         This is one of the most common git operations, it makes sense it has its
         own built-in.
     
    +    Additionally it's more user friendly than `git merge` because by default
    +    does --ff-only and thus shows the diverging advice.
    +
    +    Moreover, the documentation about fast-forwards is scattered, by having
    +    a standalone command users can be referred to it very simply:
    +
    +      git help fast-forward
    +
         This is basically the same as `git merge --ff-only` (for now).
     
         Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
    @@ t/t7600-merge.sh: test_expect_success 'merges with --ff-only' '
     +	test_must_fail git fast-forward c3 &&
     +	test_must_fail git fast-forward c2 c3 &&
     +	git reset --hard c0 &&
    -+	git merge c3 &&
    ++	git fast-forward c3 &&
     +	verify_head $c3
     +'
     +
4:  111a1d7ca4 ! 6:  e4e64401b5 doc: fast-forward: explain what it is
    @@ Documentation/git-fast-forward.txt: DESCRIPTION
     +Then `git fast-forward` will advance the local `master` to `origin/master`:
     +
     +------------
    -+    D---C---B---A master, origin/master
    ++    D---C---B---A origin/master
    ++		^
    ++		|
    ++	      master
     +------------
     +
    -+This operation is not always possible; if you made changes and the branches
    -+have diverged:
    ++This operation is not always possible; if you've made changes and the branches
    ++diverged:
     +
     +------------
     +    D---C---B---A origin/master
7:  d9b0f2c60d ! 7:  d242ac06ae fast-forward: add help about merge vs. rebase
    @@ Metadata
      ## Commit message ##
         fast-forward: add help about merge vs. rebase
     
    +    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 ##
    @@ Documentation/git-fast-forward.txt: synchronize the two branches.
     +MERGE OR REBASE
     +---------------
     +
    -+The decision to whether merge or rebase depends on the situation, and the
    ++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.
    @@ Documentation/git-fast-forward.txt: synchronize the two branches.
     +------------
     +
     +The nature of distributed version control systems make this divergence
    -+unavoidable. You must decide how to synchronize this divergence.
    ++unavoidable; you must decide how to synchronize this divergence.
     +
    -+If you choose to merge, the two heads (master and origin/master) will be joined
    ++Should you choose to merge, the two heads (master and origin/master) will be joined
     +together in a new commit:
     +
     +------------
    @@ Documentation/git-fast-forward.txt: synchronize the two branches.
     +	  X---Y---+
     +------------
     +
    -+This new commit is called a merge commit and has two parents (A and Y).
    ++This new commit is called a "merge commit" and has two parents (A and Y).
     +
     +Rebasing on the other hand rewrites the history:
     +

Felipe Contreras (7):
  merge: improve fatal fast-forward message
  merge: add diverging advice for novices
  merge: make the diverging advise configurable
  merge: split cmd_merge()
  fast-forward: add new builtin
  doc: fast-forward: explain what it is
  fast-forward: add help about merge vs. rebase

 .gitignore                             |   1 +
 Documentation/config/advice.txt        |   2 +
 Documentation/git-fast-forward.txt     | 107 +++++++++++++++++++++++++
 Makefile                               |   1 +
 advice.c                               |  15 ++++
 advice.h                               |   2 +
 builtin.h                              |   1 +
 builtin/merge.c                        |  47 +++++++----
 contrib/completion/git-completion.bash |  10 +++
 git.c                                  |   1 +
 t/t7600-merge.sh                       |  21 +++++
 11 files changed, 194 insertions(+), 14 deletions(-)
 create mode 100644 Documentation/git-fast-forward.txt

-- 
2.32.0.40.gb9b36f9b52

[PATCH 1/7] merge: improve fatal fast-forward message

[Felipe Contreras]

The documentation of --ff-only says:

  With `--ff-only`, resolve the merge as a fast-forward when possible.
  When not possible, refuse to merge and exit with a non-zero status.

So when the user does --ff-only, and a fast-forward is not possible, the
user wants git to abort, therefore an error message of:

 fatal: Not possible to fast-forward, aborting.

is redundant; no need to say ", aborting".

Additionally, use lowercase and lose the full stop to be consistent with
other die() messages.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 builtin/merge.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/builtin/merge.c b/builtin/merge.c
index a8a843b1f5..05e631229d 100644
--- a/builtin/merge.c
+++ b/builtin/merge.c
@@ -1620,7 +1620,7 @@ int cmd_merge(int argc, const char **argv, const char *prefix)
 	}
 
 	if (fast_forward == FF_ONLY)
-		die(_("Not possible to fast-forward, aborting."));
+		die(_("unable to fast-forward"));
 
 	if (autostash)
 		create_autostash(the_repository,
-- 
2.32.0.40.gb9b36f9b52

[PATCH 2/7] merge: add diverging advice for novices

[Felipe Contreras]

Diverging branches is one of the most confusing aspects of distributed
version control systems for novices, so a little help explaining what to
do on those situations will come in handy.

Right now this advice will be displayed only when the user does
`git merge --ff-only`, `git pull --ff-only`, or has configured
`pull.ff=only` for `git pull`, but in the future it's expected that
--ff-only will be the default for `git pull`, and a proposed `git
fast-forward` command will imply --ff-only, in addition to `git update`.

So it makes sense to add the advice in preparation for those future
changes, although even currently it helps.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 advice.c        | 11 +++++++++++
 advice.h        |  1 +
 builtin/merge.c |  4 +++-
 3 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/advice.c b/advice.c
index 0b9c89c48a..8f068c8be9 100644
--- a/advice.c
+++ b/advice.c
@@ -326,3 +326,14 @@ void detach_advice(const char *new_name)
 
 	fprintf(stderr, fmt, new_name);
 }
+
+void diverging_advice(void)
+{
+	advise(_("Diverging branches can't be fast-forwarded, you need to either:\n"
+		"\n"
+		"\tgit merge\n"
+		"\n"
+		"or:\n"
+		"\n"
+		"\tgit rebase\n"));
+}
diff --git a/advice.h b/advice.h
index bd26c385d0..6ce967c962 100644
--- a/advice.h
+++ b/advice.h
@@ -97,5 +97,6 @@ void NORETURN die_resolve_conflict(const char *me);
 void NORETURN die_conclude_merge(void);
 void advise_on_updating_sparse_paths(struct string_list *pathspec_list);
 void detach_advice(const char *new_name);
+void diverging_advice(void);
 
 #endif /* ADVICE_H */
diff --git a/builtin/merge.c b/builtin/merge.c
index 05e631229d..56a526f42c 100644
--- a/builtin/merge.c
+++ b/builtin/merge.c
@@ -1619,8 +1619,10 @@ int cmd_merge(int argc, const char **argv, const char *prefix)
 		}
 	}
 
-	if (fast_forward == FF_ONLY)
+	if (fast_forward == FF_ONLY) {
+		diverging_advice();
 		die(_("unable to fast-forward"));
+	}
 
 	if (autostash)
 		create_autostash(the_repository,
-- 
2.32.0.40.gb9b36f9b52

[PATCH 3/7] merge: make the diverging advise configurable

[Felipe Contreras]

With advice.diverging.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/config/advice.txt | 2 ++
 advice.c                        | 4 +++-
 advice.h                        | 1 +
 3 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt
index 8b2849ff7b..dae85310dc 100644
--- a/Documentation/config/advice.txt
+++ b/Documentation/config/advice.txt
@@ -123,4 +123,6 @@ advice.*::
 		Advice shown when either linkgit:git-add[1] or linkgit:git-rm[1]
 		is asked to update index entries outside the current sparse
 		checkout.
+	diverging::
+		Advice shown when a fast-forward is not possible.
 --
diff --git a/advice.c b/advice.c
index 8f068c8be9..60de7fbc4e 100644
--- a/advice.c
+++ b/advice.c
@@ -110,6 +110,7 @@ static struct {
 	[ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME] 	= { "checkoutAmbiguousRemoteBranchName", 1 },
 	[ADVICE_COMMIT_BEFORE_MERGE]			= { "commitBeforeMerge", 1 },
 	[ADVICE_DETACHED_HEAD]				= { "detachedHead", 1 },
+	[ADVICE_DIVERGING]				= { "diverging", 1 },
 	[ADVICE_FETCH_SHOW_FORCED_UPDATES]		= { "fetchShowForcedUpdates", 1 },
 	[ADVICE_GRAFT_FILE_DEPRECATED]			= { "graftFileDeprecated", 1 },
 	[ADVICE_IGNORED_HOOK]				= { "ignoredHook", 1 },
@@ -329,7 +330,8 @@ void detach_advice(const char *new_name)
 
 void diverging_advice(void)
 {
-	advise(_("Diverging branches can't be fast-forwarded, you need to either:\n"
+	advise_if_enabled(ADVICE_DIVERGING,
+		_("Diverging branches can't be fast-forwarded, you need to either:\n"
 		"\n"
 		"\tgit merge\n"
 		"\n"
diff --git a/advice.h b/advice.h
index 6ce967c962..695f5a62bb 100644
--- a/advice.h
+++ b/advice.h
@@ -49,6 +49,7 @@ extern int advice_add_empty_pathspec;
 	ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME,
 	ADVICE_COMMIT_BEFORE_MERGE,
 	ADVICE_DETACHED_HEAD,
+	ADVICE_DIVERGING,
 	ADVICE_FETCH_SHOW_FORCED_UPDATES,
 	ADVICE_GRAFT_FILE_DEPRECATED,
 	ADVICE_IGNORED_HOOK,
-- 
2.32.0.40.gb9b36f9b52

[PATCH 4/7] merge: split cmd_merge()

[Felipe Contreras]

We want to re-use most of cmd_merge() for a new command.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 builtin/merge.c | 26 ++++++++++++++------------
 1 file changed, 14 insertions(+), 12 deletions(-)

diff --git a/builtin/merge.c b/builtin/merge.c
index 56a526f42c..2770dabf22 100644
--- a/builtin/merge.c
+++ b/builtin/merge.c
@@ -1259,7 +1259,8 @@ static int merging_a_throwaway_tag(struct commit *commit)
 	return is_throwaway_tag;
 }
 
-int cmd_merge(int argc, const char **argv, const char *prefix)
+static int merge_common(int argc, const char **argv, const char *prefix,
+	const struct option *options, const char * const usage[])
 {
 	struct object_id result_tree, stash, head_oid;
 	struct commit *head_commit;
@@ -1273,7 +1274,7 @@ int cmd_merge(int argc, const char **argv, const char *prefix)
 	int orig_argc = argc;
 
 	if (argc == 2 && !strcmp(argv[1], "-h"))
-		usage_with_options(builtin_merge_usage, builtin_merge_options);
+		usage_with_options(usage, options);
 
 	/*
 	 * Check if we are _not_ on a detached HEAD, i.e. if there is a
@@ -1299,8 +1300,7 @@ int cmd_merge(int argc, const char **argv, const char *prefix)
 
 	if (branch_mergeoptions)
 		parse_branch_merge_options(branch_mergeoptions);
-	argc = parse_options(argc, argv, prefix, builtin_merge_options,
-			builtin_merge_usage, 0);
+	argc = parse_options(argc, argv, prefix, options, usage, 0);
 	if (shortlog_len < 0)
 		shortlog_len = (merge_log_config > 0) ? merge_log_config : 0;
 
@@ -1314,7 +1314,7 @@ int cmd_merge(int argc, const char **argv, const char *prefix)
 
 		if (orig_argc != 2)
 			usage_msg_opt(_("--abort expects no arguments"),
-			      builtin_merge_usage, builtin_merge_options);
+				usage, options);
 
 		if (!file_exists(git_path_merge_head(the_repository)))
 			die(_("There is no merge to abort (MERGE_HEAD missing)."));
@@ -1336,8 +1336,7 @@ int cmd_merge(int argc, const char **argv, const char *prefix)
 	if (quit_current_merge) {
 		if (orig_argc != 2)
 			usage_msg_opt(_("--quit expects no arguments"),
-				      builtin_merge_usage,
-				      builtin_merge_options);
+				usage, options);
 
 		remove_merge_branch_state(the_repository);
 		goto done;
@@ -1349,7 +1348,7 @@ int cmd_merge(int argc, const char **argv, const char *prefix)
 
 		if (orig_argc != 2)
 			usage_msg_opt(_("--continue expects no arguments"),
-			      builtin_merge_usage, builtin_merge_options);
+				usage, options);
 
 		if (!file_exists(git_path_merge_head(the_repository)))
 			die(_("There is no merge in progress (MERGE_HEAD missing)."));
@@ -1416,8 +1415,7 @@ int cmd_merge(int argc, const char **argv, const char *prefix)
 	}
 
 	if (!argc)
-		usage_with_options(builtin_merge_usage,
-			builtin_merge_options);
+		usage_with_options(usage, options);
 
 	if (!head_commit) {
 		/*
@@ -1458,8 +1456,7 @@ int cmd_merge(int argc, const char **argv, const char *prefix)
 				      argc, argv, &merge_msg);
 
 	if (!head_commit || !argc)
-		usage_with_options(builtin_merge_usage,
-			builtin_merge_options);
+		usage_with_options(usage, options);
 
 	if (verify_signatures) {
 		for (p = remoteheads; p; p = p->next) {
@@ -1740,3 +1737,8 @@ int cmd_merge(int argc, const char **argv, const char *prefix)
 	free(branch_to_free);
 	return ret;
 }
+
+int cmd_merge(int argc, const char **argv, const char *prefix)
+{
+	return merge_common(argc, argv, prefix, builtin_merge_options, builtin_merge_usage);
+}
-- 
2.32.0.40.gb9b36f9b52

[PATCH 5/7] fast-forward: add new builtin

[Felipe Contreras]

This is one of the most common git operations, it makes sense it has its
own built-in.

Additionally it's more user friendly than `git merge` because by default
does --ff-only and thus shows the diverging advice.

Moreover, the documentation about fast-forwards is scattered, by having
a standalone command users can be referred to it very simply:

  git help fast-forward

This is basically the same as `git merge --ff-only` (for now).

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 .gitignore                             |  1 +
 Documentation/git-fast-forward.txt     | 26 ++++++++++++++++++++++++++
 Makefile                               |  1 +
 builtin.h                              |  1 +
 builtin/merge.c                        | 15 +++++++++++++++
 contrib/completion/git-completion.bash | 10 ++++++++++
 git.c                                  |  1 +
 t/t7600-merge.sh                       | 21 +++++++++++++++++++++
 8 files changed, 76 insertions(+)
 create mode 100644 Documentation/git-fast-forward.txt

diff --git a/.gitignore b/.gitignore
index 311841f9be..45703399b0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -62,6 +62,7 @@
 /git-describe
 /git-env--helper
 /git-fast-export
+/git-fast-forward
 /git-fast-import
 /git-fetch
 /git-fetch-pack
diff --git a/Documentation/git-fast-forward.txt b/Documentation/git-fast-forward.txt
new file mode 100644
index 0000000000..d457022629
--- /dev/null
+++ b/Documentation/git-fast-forward.txt
@@ -0,0 +1,26 @@
+git-fast-forward(1)
+===================
+
+NAME
+----
+git-fast-forward - Advance the branch pointer
+
+SYNOPSIS
+--------
+[verse]
+'git fast-forward' [<commit>]
+
+DESCRIPTION
+-----------
+Incorporates changes into the current branch. By default the upstream branch is
+used, but a different commit can be specified in the arguments.
+
+THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOUR MAY CHANGE.
+
+SEE ALSO
+--------
+linkgit:git-merge[1]
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Makefile b/Makefile
index c7c46c017d..a05c309188 100644
--- a/Makefile
+++ b/Makefile
@@ -777,6 +777,7 @@ BUILT_INS += $(patsubst builtin/%.o,git-%$X,$(BUILTIN_OBJS))
 
 BUILT_INS += git-cherry$X
 BUILT_INS += git-cherry-pick$X
+BUILT_INS += git-fast-forward$X
 BUILT_INS += git-format-patch$X
 BUILT_INS += git-fsck-objects$X
 BUILT_INS += git-init$X
diff --git a/builtin.h b/builtin.h
index 16ecd5586f..601e438c9b 100644
--- a/builtin.h
+++ b/builtin.h
@@ -151,6 +151,7 @@ int cmd_diff_tree(int argc, const char **argv, const char *prefix);
 int cmd_difftool(int argc, const char **argv, const char *prefix);
 int cmd_env__helper(int argc, const char **argv, const char *prefix);
 int cmd_fast_export(int argc, const char **argv, const char *prefix);
+int cmd_fast_forward(int argc, const char **argv, const char *prefix);
 int cmd_fast_import(int argc, const char **argv, const char *prefix);
 int cmd_fetch(int argc, const char **argv, const char *prefix);
 int cmd_fetch_pack(int argc, const char **argv, const char *prefix);
diff --git a/builtin/merge.c b/builtin/merge.c
index 2770dabf22..1836f98f82 100644
--- a/builtin/merge.c
+++ b/builtin/merge.c
@@ -61,6 +61,11 @@ static const char * const builtin_merge_usage[] = {
 	NULL
 };
 
+static const char * const builtin_ff_usage[] = {
+	N_("git fast-forward [<commit>]"),
+	NULL
+};
+
 static int show_diffstat = 1, shortlog_len = -1, squash;
 static int option_commit = -1;
 static int option_edit = -1;
@@ -304,6 +309,10 @@ static struct option builtin_merge_options[] = {
 	OPT_END()
 };
 
+static struct option builtin_ff_options[] = {
+	OPT_END()
+};
+
 static int save_state(struct object_id *stash)
 {
 	int len;
@@ -1742,3 +1751,9 @@ int cmd_merge(int argc, const char **argv, const char *prefix)
 {
 	return merge_common(argc, argv, prefix, builtin_merge_options, builtin_merge_usage);
 }
+
+int cmd_fast_forward(int argc, const char **argv, const char *prefix)
+{
+	fast_forward = FF_ONLY;
+	return merge_common(argc, argv, prefix, builtin_ff_options, builtin_ff_usage);
+}
diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index 4bdd27ddc8..ec00c20656 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -1787,6 +1787,16 @@ _git_difftool ()
 	__git_complete_revlist_file
 }
 
+_git_fast_forward ()
+{
+	case "$cur" in
+	--*)
+		__gitcomp_builtin fast-forward
+		return
+	esac
+	__git_complete_refs
+}
+
 __git_fetch_recurse_submodules="yes on-demand no"
 
 _git_fetch ()
diff --git a/git.c b/git.c
index 18bed9a996..6ab1fb9251 100644
--- a/git.c
+++ b/git.c
@@ -524,6 +524,7 @@ static struct cmd_struct commands[] = {
 	{ "difftool", cmd_difftool, RUN_SETUP_GENTLY },
 	{ "env--helper", cmd_env__helper },
 	{ "fast-export", cmd_fast_export, RUN_SETUP },
+	{ "fast-forward", cmd_fast_forward, RUN_SETUP | NEED_WORK_TREE },
 	{ "fast-import", cmd_fast_import, RUN_SETUP | NO_PARSEOPT },
 	{ "fetch", cmd_fetch, RUN_SETUP },
 	{ "fetch-pack", cmd_fetch_pack, RUN_SETUP | NO_PARSEOPT },
diff --git a/t/t7600-merge.sh b/t/t7600-merge.sh
index 1cbc9715a8..9df1931236 100755
--- a/t/t7600-merge.sh
+++ b/t/t7600-merge.sh
@@ -205,6 +205,16 @@ test_expect_success 'merge c0 with c1 with --ff-only' '
 
 test_debug 'git log --graph --decorate --oneline --all'
 
+test_expect_success 'fast-forward c0 with c1' '
+	git reset --hard c0 &&
+	git fast-forward c1 &&
+	git fast-forward HEAD c0 c1 &&
+	verify_merge file result.1 &&
+	verify_head "$c1"
+'
+
+test_debug 'git log --graph --decorate --oneline --all'
+
 test_expect_success 'merge from unborn branch' '
 	git checkout -f main &&
 	test_might_fail git branch -D kid &&
@@ -322,6 +332,17 @@ test_expect_success 'merges with --ff-only' '
 	verify_head $c3
 '
 
+test_expect_success 'fast-forward' '
+	git reset --hard c1 &&
+	test_tick &&
+	test_must_fail git fast-forward c2 &&
+	test_must_fail git fast-forward c3 &&
+	test_must_fail git fast-forward c2 c3 &&
+	git reset --hard c0 &&
+	git fast-forward c3 &&
+	verify_head $c3
+'
+
 test_expect_success 'merges with merge.ff=only' '
 	git reset --hard c1 &&
 	test_tick &&
-- 
2.32.0.40.gb9b36f9b52

[PATCH 6/7] doc: fast-forward: explain what it is

[Felipe Contreras]

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/git-fast-forward.txt | 35 +++++++++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-fast-forward.txt b/Documentation/git-fast-forward.txt
index d457022629..38c920964f 100644
--- a/Documentation/git-fast-forward.txt
+++ b/Documentation/git-fast-forward.txt
@@ -15,11 +15,44 @@ DESCRIPTION
 Incorporates changes into the current branch. By default the upstream branch is
 used, but a different commit can be specified in the arguments.
 
+Assume the following history exists and the current branch is
+`master`:
+
+------------
+    D---C---B---A origin/master
+	^
+	|
+      master
+------------
+
+Then `git fast-forward` will advance the local `master` to `origin/master`:
+
+------------
+    D---C---B---A origin/master
+		^
+		|
+	      master
+------------
+
+This operation is not always possible; if you've made changes and the branches
+diverged:
+
+------------
+    D---C---B---A origin/master
+	 \
+	  X---Y master
+------------
+
+then the fast-forward command will fail.
+
+In those cases you need to either `git merge`, or `git rebase` in order to
+synchronize the two branches.
+
 THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOUR MAY CHANGE.
 
 SEE ALSO
 --------
-linkgit:git-merge[1]
+linkgit:git-merge[1], linkgit:git-rebase[1]
 
 GIT
 ---
-- 
2.32.0.40.gb9b36f9b52

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

[Felipe Contreras]

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
+    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"));
 }
-- 
2.32.0.40.gb9b36f9b52

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

[Philip Oakley]

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

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

[Felipe Contreras]

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/

-- 
Felipe Contreras

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

[Philip Oakley]

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

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

[Felipe Contreras]

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.

-- 
Felipe Contreras