[PATCH 0/7] fast-forward: new command with advice and documentation
From: Felipe Contreras <hidden>
Date: 2021-07-22 00:08:59
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 [off-list ref]
## builtin/merge.c ##
5: fbbde141b3 ! 2: d99c5ec51e fast-forward: add advice for novices
@@ Metadata
Author: Felipe Contreras [off-list ref]
## 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 [off-list ref]
@@ 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 [off-list ref]
## 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 [off-list ref]
@@ 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 [off-list ref]
## 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