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@xxxxxxxxxxxxxx/ [2] https://lore.kernel.org/git/20210705123209.1808663-1-felipe.contreras@xxxxxxxxx/ 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@xxxxxxxxx> ## builtin/merge.c ## 5: fbbde141b3 ! 2: d99c5ec51e fast-forward: add advice for novices @@ Metadata Author: Felipe Contreras <felipe.contreras@xxxxxxxxx> ## 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@xxxxxxxxx> @@ 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@xxxxxxxxx> ## 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@xxxxxxxxx> @@ 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@xxxxxxxxx> ## 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
