* [PATCH 1/7] merge: improve fatal fast-forward message
2021-07-22 0:08 [PATCH 0/7] fast-forward: new command with advice and documentation Felipe Contreras
@ 2021-07-22 0:08 ` Felipe Contreras
2021-07-22 0:08 ` [PATCH 2/7] merge: add diverging advice for novices Felipe Contreras
` (5 subsequent siblings)
6 siblings, 0 replies; 12+ messages in thread
From: Felipe Contreras @ 2021-07-22 0:08 UTC (permalink / raw)
To: git
Cc: Alex Henrie, Ævar Arnfjörð Bjarmason,
Randall S . Becker, Nguyễn Thái Ngọc Duy,
Denton Liu, Elijah Newren, Junio C Hamano, 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
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 2/7] merge: add diverging advice for novices
2021-07-22 0:08 [PATCH 0/7] fast-forward: new command with advice and documentation Felipe Contreras
2021-07-22 0:08 ` [PATCH 1/7] merge: improve fatal fast-forward message Felipe Contreras
@ 2021-07-22 0:08 ` Felipe Contreras
2021-07-22 0:08 ` [PATCH 3/7] merge: make the diverging advise configurable Felipe Contreras
` (4 subsequent siblings)
6 siblings, 0 replies; 12+ messages in thread
From: Felipe Contreras @ 2021-07-22 0:08 UTC (permalink / raw)
To: git
Cc: Alex Henrie, Ævar Arnfjörð Bjarmason,
Randall S . Becker, Nguyễn Thái Ngọc Duy,
Denton Liu, Elijah Newren, Junio C Hamano, 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
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 3/7] merge: make the diverging advise configurable
2021-07-22 0:08 [PATCH 0/7] fast-forward: new command with advice and documentation Felipe Contreras
2021-07-22 0:08 ` [PATCH 1/7] merge: improve fatal fast-forward message Felipe Contreras
2021-07-22 0:08 ` [PATCH 2/7] merge: add diverging advice for novices Felipe Contreras
@ 2021-07-22 0:08 ` Felipe Contreras
2021-07-22 0:08 ` [PATCH 4/7] merge: split cmd_merge() Felipe Contreras
` (3 subsequent siblings)
6 siblings, 0 replies; 12+ messages in thread
From: Felipe Contreras @ 2021-07-22 0:08 UTC (permalink / raw)
To: git
Cc: Alex Henrie, Ævar Arnfjörð Bjarmason,
Randall S . Becker, Nguyễn Thái Ngọc Duy,
Denton Liu, Elijah Newren, Junio C Hamano, 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
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 4/7] merge: split cmd_merge()
2021-07-22 0:08 [PATCH 0/7] fast-forward: new command with advice and documentation Felipe Contreras
` (2 preceding siblings ...)
2021-07-22 0:08 ` [PATCH 3/7] merge: make the diverging advise configurable Felipe Contreras
@ 2021-07-22 0:08 ` Felipe Contreras
2021-07-22 0:08 ` [PATCH 5/7] fast-forward: add new builtin Felipe Contreras
` (2 subsequent siblings)
6 siblings, 0 replies; 12+ messages in thread
From: Felipe Contreras @ 2021-07-22 0:08 UTC (permalink / raw)
To: git
Cc: Alex Henrie, Ævar Arnfjörð Bjarmason,
Randall S . Becker, Nguyễn Thái Ngọc Duy,
Denton Liu, Elijah Newren, Junio C Hamano, 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
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 5/7] fast-forward: add new builtin
2021-07-22 0:08 [PATCH 0/7] fast-forward: new command with advice and documentation Felipe Contreras
` (3 preceding siblings ...)
2021-07-22 0:08 ` [PATCH 4/7] merge: split cmd_merge() Felipe Contreras
@ 2021-07-22 0:08 ` Felipe Contreras
2021-07-22 0:08 ` [PATCH 6/7] doc: fast-forward: explain what it is Felipe Contreras
2021-07-22 0:08 ` [PATCH 7/7] fast-forward: add help about merge vs. rebase Felipe Contreras
6 siblings, 0 replies; 12+ messages in thread
From: Felipe Contreras @ 2021-07-22 0:08 UTC (permalink / raw)
To: git
Cc: Alex Henrie, Ævar Arnfjörð Bjarmason,
Randall S . Becker, Nguyễn Thái Ngọc Duy,
Denton Liu, Elijah Newren, Junio C Hamano, 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
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 6/7] doc: fast-forward: explain what it is
2021-07-22 0:08 [PATCH 0/7] fast-forward: new command with advice and documentation Felipe Contreras
` (4 preceding siblings ...)
2021-07-22 0:08 ` [PATCH 5/7] fast-forward: add new builtin Felipe Contreras
@ 2021-07-22 0:08 ` Felipe Contreras
2021-07-22 0:08 ` [PATCH 7/7] fast-forward: add help about merge vs. rebase Felipe Contreras
6 siblings, 0 replies; 12+ messages in thread
From: Felipe Contreras @ 2021-07-22 0:08 UTC (permalink / raw)
To: git
Cc: Alex Henrie, Ævar Arnfjörð Bjarmason,
Randall S . Becker, Nguyễn Thái Ngọc Duy,
Denton Liu, Elijah Newren, Junio C Hamano, 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
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 7/7] fast-forward: add help about merge vs. rebase
2021-07-22 0:08 [PATCH 0/7] fast-forward: new command with advice and documentation Felipe Contreras
` (5 preceding siblings ...)
2021-07-22 0:08 ` [PATCH 6/7] doc: fast-forward: explain what it is Felipe Contreras
@ 2021-07-22 0:08 ` Felipe Contreras
2021-07-22 22:57 ` Philip Oakley
6 siblings, 1 reply; 12+ messages in thread
From: Felipe Contreras @ 2021-07-22 0:08 UTC (permalink / raw)
To: git
Cc: Alex Henrie, Ævar Arnfjörð Bjarmason,
Randall S . Becker, Nguyễn Thái Ngọc Duy,
Denton Liu, Elijah Newren, Junio C Hamano, 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
^ permalink raw reply related [flat|nested] 12+ messages in thread* Re: [PATCH 7/7] fast-forward: add help about merge vs. rebase
2021-07-22 0:08 ` [PATCH 7/7] fast-forward: add help about merge vs. rebase Felipe Contreras
@ 2021-07-22 22:57 ` Philip Oakley
2021-07-23 17:10 ` Felipe Contreras
0 siblings, 1 reply; 12+ messages in thread
From: Philip Oakley @ 2021-07-22 22:57 UTC (permalink / raw)
To: Felipe Contreras, git
Cc: Alex Henrie, Ævar Arnfjörð Bjarmason,
Randall S . Becker, Nguyễn Thái Ngọc Duy,
Denton Liu, Elijah Newren, Junio C Hamano
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
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 7/7] fast-forward: add help about merge vs. rebase
2021-07-22 22:57 ` Philip Oakley
@ 2021-07-23 17:10 ` Felipe Contreras
2021-07-23 19:14 ` Philip Oakley
0 siblings, 1 reply; 12+ messages in thread
From: Felipe Contreras @ 2021-07-23 17:10 UTC (permalink / raw)
To: Philip Oakley, Felipe Contreras, git
Cc: Alex Henrie, Ævar Arnfjörð Bjarmason,
Randall S . Becker, Nguyễn Thái Ngọc Duy,
Denton Liu, Elijah Newren, Junio C Hamano
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
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 7/7] fast-forward: add help about merge vs. rebase
2021-07-23 17:10 ` Felipe Contreras
@ 2021-07-23 19:14 ` Philip Oakley
2021-07-23 20:14 ` Felipe Contreras
0 siblings, 1 reply; 12+ messages in thread
From: Philip Oakley @ 2021-07-23 19:14 UTC (permalink / raw)
To: Felipe Contreras, git
Cc: Alex Henrie, Ævar Arnfjörð Bjarmason,
Randall S . Becker, Nguyễn Thái Ngọc Duy,
Denton Liu, Elijah Newren, Junio C Hamano
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
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 7/7] fast-forward: add help about merge vs. rebase
2021-07-23 19:14 ` Philip Oakley
@ 2021-07-23 20:14 ` Felipe Contreras
0 siblings, 0 replies; 12+ messages in thread
From: Felipe Contreras @ 2021-07-23 20:14 UTC (permalink / raw)
To: Philip Oakley, Felipe Contreras, git
Cc: Alex Henrie, Ævar Arnfjörð Bjarmason,
Randall S . Becker, Nguyễn Thái Ngọc Duy,
Denton Liu, Elijah Newren, Junio C Hamano
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
^ permalink raw reply [flat|nested] 12+ messages in thread