From 71b0233efbe7694fbaae0cf9834abb5d2d240569 Mon Sep 17 00:00:00 2001 From: Martin von Zweigbergk Date: Sun, 12 Dec 2021 00:19:39 -0800 Subject: [PATCH] docs: add doc about a first-class conflicts --- README.md | 4 ++-- docs/conflicts.md | 48 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 2 deletions(-) create mode 100644 docs/conflicts.md diff --git a/README.md b/README.md index bc5585476..5e3641447 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,8 @@ Jujutsu is a Git-compatible [DVCS](https://en.wikipedia.org/wiki/Distributed_version_control). It combines features from Git (data model, speed), Mercurial (anonymous branching, simple CLI free from "the index", [revsets](docs/revsets.md)), and Pijul/Darcs -(first-class conflicts), with features not found in either of them -([working-copy-as-a-commit](docs/working-copy.md), +([first-class conflicts](docs/conflicts.md)), with features not found in either +of them ([working-copy-as-a-commit](docs/working-copy.md), [undo functionality](docs/operation-log.md), automatic rebase). The command-line tool is called `jj` for now because it's easy to type and easy diff --git a/docs/conflicts.md b/docs/conflicts.md new file mode 100644 index 000000000..5983fd9f1 --- /dev/null +++ b/docs/conflicts.md @@ -0,0 +1,48 @@ +# First-class conflicts + + +## Introduction + +Like [Pijul](https://pijul.org/) and [Darcs](http://darcs.net/) but unlike most +other VCSs, Jujutsu can record conflicted states in commits. For example, if you +rebase a commit and it results in a conflict, the conflict will be recorded in +the rebased commit and the rebase operation will succeed. You can then resolve +the conflict whenever you want. Conflicted states can be further rebased, +merged, or backed out. Note that what's stored in the commit is a logical +representation of the conflict, not conflict *markers*; rebasing a conflict +doesn't result in a nested conflict markers. + + +## Advantages + +The deeper understanding of conflicts has many advantages: + +* Removes the need for things like + `git rebase/merge/cherry-pick/etc --continue`. Instead, you get a single + workflow for resolving conflicts: check out the conflicted commit, resolve + conflicts, and amend. +* Enables the "auto-rebase" feature, where descendants of rewritten commits + automatically get rewritten. This feature mostly replaces Mercurial's + [Changeset Evolution](https://www.mercurial-scm.org/wiki/ChangesetEvolution). +* Lets us define the change in a merge commit as being compared to the merged + parents. That way, we can rebase merge commits correctly (unlike both Git and + Mercurial). That includes conflict resolutions done in the merge commit, + addressing a common use case for + [git rerere](https://git-scm.com/docs/git-rerere). + Since the changes in a merge commit are displayed and rebased as expected, + [evil merges](https://git-scm.com/docs/gitglossary/2.22.0#Documentation/gitglossary.txt-aiddefevilmergeaevilmerge) + are arguably not as evil anymore. +* Allows you to postpone conflict resolution until you're ready for it. You + can easily keep all your work-in-progress commits rebased onto upstream's head + if you like. +* [Criss-cross merges](https://stackoverflow.com/questions/26370185/how-do-criss-cross-merges-arise-in-git) + and [octopus merges](https://git-scm.com/docs/git-merge#Documentation/git-merge.txt-octopus) + become trivial (implementation-wise); some cases that Git can't currently + handle, or that would result in nested conflict markers, can be automatically + resolved. +* Enables collaborative conflict resolution. (This assumes that you can share + the conflicts with others, which you probably shouldn't do if some people + interact with your project using Git.) + +For information about how conflicts are handled in the working copy, see +[here](working_copy.md#conflicts).