refactor!: introduce new update algorithm based on git merge

Author: sisp

copier/_cli.py

@@ -375,23 +375,6 @@ class CopierUpdateSubApp(_Subcommand):
         """
     )
 
-    conflict = cli.SwitchAttr(
-        ["-o", "--conflict"],
-        cli.Set("rej", "inline"),
-        default="inline",
-        help=(
-            "Behavior on conflict: Create .rej files, or add inline conflict markers."
-        ),
-    )
-    context_lines = cli.SwitchAttr(
-        ["-c", "--context-lines"],
-        int,
-        default=3,
-        help=(
-            "Lines of context to use for detecting conflicts. Increase for "
-            "accuracy, decrease for resilience."
-        ),
-    )
     defaults = cli.Flag(
         ["-l", "-f", "--defaults"],
         help="Use default answers to questions, which might be null if not specified.",
@@ -417,8 +400,6 @@ def main(self, destination_path: cli.ExistingDirectory = ".") -> int:
         def inner() -> None:
             with self._worker(
                 dst_path=destination_path,
-                conflict=self.conflict,
-                context_lines=self.context_lines,
                 defaults=self.defaults,
                 skip_answered=self.skip_answered,
                 overwrite=True,

copier/_main.py

@@ -785,43 +785,6 @@ will delete that folder.
 Copier will never delete the folder if it didn't create it. For this reason, when
 running `copier update`, this setting has no effect.
 
-!!! info
-
-    Not supported in `copier.yml`.
-
-### `conflict`
-
--   Format: `Literal["rej", "inline"]`
--   CLI flags: `-o`, `--conflict` (only available in `copier update` subcommand)
--   Default value: `inline`
-
-When updating a project, sometimes Copier doesn't know what to do with a diff code hunk.
-This option controls the output format if this happens. Using `rej`, creates `*.rej`
-files that contain the unresolved diffs. The `inline` option (default) includes the diff
-code hunk in the file itself, similar to the behavior of `git merge`.
-
-!!! info
-
-    Not supported in `copier.yml`.
-
-### `context_lines`
-
--   Format: `Int`
--   CLI flags: `-c`, `--context-lines` (only available in `copier update` subcommand)
--   Default value: `1`
-
-During a project update, Copier needs to compare the template evolution with the
-subproject evolution. This way, it can detect what changed, where and how to merge those
-changes. [Refer here for more details on this process](updating.md).
-
-The more lines you use, the more accurate Copier will be when detecting conflicts. But
-you will also have more conflicts to solve by yourself. FWIW, Git uses 3 lines by
-default.
-
-The less lines you use, the less conflicts you will have. However, Copier will not be so
-accurate and could even move lines around if the file it's comparing has several similar
-code chunks.
-
 !!! info
 
     Not supported in `copier.yml`.

docs/configuring.md

@@ -108,8 +108,6 @@ Attributes:
 | ------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `answers_file`     | `PurePath`                                                    | The path for [the answers file][the-copier-answersyml-file] relative to `dst_path`.<br>See the [`answers_file`][] setting for related information.                                                                                                         |
 | `cleanup_on_error` | `bool`                                                        | When `True`, delete `dst_path` if there's an error.<br>See the [`cleanup_on_error`][] setting for related information.                                                                                                                                     |
-| `conflict`         | `Literal["inline", "rej"]`                                    | The output format of a diff code hunk when [updating][updating-a-project] a file yields conflicts.<br>See the [`conflict`][] setting for related information.                                                                                              |
-| `context_lines`    | `PositiveInt`                                                 | Lines of context to consider when solving conflicts in updates.<br>See the [`context_lines`][] setting for related information.                                                                                                                            |
 | `data`             | `dict[str, Any]`                                              | Answers to the questionnaire, defined in the template, provided via CLI (`-d,--data`) or API (`data`).<br>See the [`data`][] setting for related information.<br>⚠️ May contain secret answers.                                                            |
 | `defaults`         | `bool`                                                        | When `True`, use default answers to questions.<br>See the [`defaults`][] setting for related information.                                                                                                                                                  |
 | `dst_path`         | `PurePath`                                                    | Destination path where to render the subproject.<br>⚠️ When [updating a project][updating-a-project], it may be a temporary directory, as Copier's update algorithm generates fresh copies using the old and new template versions in temporary locations. |

docs/creating.md

@@ -38,15 +38,11 @@ other Git ref you want.
 
 When updating, Copier will do its best to respect your project evolution by using the
 answers you provided when copied last time. However, sometimes it's impossible for
-Copier to know what to do with a diff code hunk. In those cases, copier handles the
-conflict in one of two ways, controlled with the `--conflict` option:
-
--   `--conflict rej`: Creates a separate `.rej` file for each file with conflicts. These
-    files contain the unresolved diffs.
--   `--conflict inline` (default): Updates the file with conflict markers. This is quite
-    similar to the conflict markers created when a `git merge` command encounters a
-    conflict. For more information, see the "Checking Out Conflicts" section of the
-    [`git` documentation](https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging).
+Copier to know what to merge the changes from the evolved template into the evolved
+project. In those cases, Copier updates a conflicting file with conflict markers in the
+same ways as a `git merge` command encounters conflicts; in fact, Copier uses
+`git merge` internally. For more information, see the "Checking Out Conflicts" section
+of the [`git` documentation](https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging).
 
 If the update results in conflicts, _you should review those manually_ before
 committing.
@@ -56,13 +52,11 @@ Git history, but if you aren't careful, it's easy to make mistakes.
 
 That's why the recommended way to prevent these mistakes is to add a
 [pre-commit](https://pre-commit.com/) (or equivalent) hook that forbids committing
-conflict files or markers. The recommended hook configuration depends on the `conflict`
-setting you use.
+conflict markers.
 
 ## Preventing Commit of Merge Conflicts
 
-If you use `--conflict inline` (the default) then you need to check for conflicts
-markers in your files:
+You need to check for conflicts markers in your files:
 
 ```yaml title=".pre-commit-config.yaml"
 repos:
@@ -74,29 +68,6 @@ repos:
             args: [--assume-in-merge]
 ```
 
-If you use `--conflict rej` then you need to review and remove all generated `.rej`
-files:
-
-```yaml title=".pre-commit-config.yaml"
-repos:
-    - repo: local
-      hooks:
-          # Prevent committing .rej files
-          - id: forbidden-files
-            name: forbidden files
-            entry:
-                found Copier update rejection files; review and remove them before
-                merging.
-            language: fail
-            files: "\\.rej$"
-```
-
-!!! note
-
-    For projects that use both `rej` and `inline` depending on each user's preference,
-    you can add both hooks to your `pre-commit-config.yaml` file, making sure that no
-    unresolved merge conflicts are committed.
-
 ## Never change the answers file manually
 
 !!! important
@@ -157,42 +128,40 @@ graph TD
 
 %% nodes ----------------------------------------------------------
 template_repo("template repository")
-template_current("/tmp/template<br>(current tag)")
-template_latest("/tmp/template<br>(latest tag)")
+template_current("/tmp/template-old<br>(current tag)")
+template_latest("/tmp/template-new<br>(latest tag)")
 
-project_regen("/tmp/project<br>(fresh, current version)")
+project_regen_current("/tmp/project-old<br>(fresh, current version)")
+project_regen_latest("/tmp/project-new<br>(fresh, latest version)")
 project_current("current project")
 project_half("half migrated<br>project")
 project_updated("updated project")
-project_applied("updated project<br>(diff applied)")
 project_full("fully updated<br>and migrated project")
 
-update["update current<br>project in-place<br>(prompting)<br>+ run tasks again"]
-compare["compare to get diff"]
-apply["apply diff"]
-
-diff("diff")
+update["3-way merge<br>& run tasks again"]
+regen_current["generate and run tasks"]
+regen_latest["generate and run tasks"]
 
 %% edges ----------------------------------------------------------
         template_repo --> |git clone| template_current
         template_repo --> |git clone| template_latest
 
-     template_current --> |generate and run tasks| project_regen
-      project_current --> compare
+     template_current --> regen_current
+      project_current .-> |use answers| regen_current
+        regen_current --> project_regen_current
+      template_latest --> regen_latest
+         regen_latest --> project_regen_latest
       project_current --> |apply pre-migrations| project_half
-        project_regen --> compare
+         project_half .-> |use answers| regen_latest
          project_half --> update
-      template_latest --> update
+project_regen_current --> update
+ project_regen_latest --> update
                update --> project_updated
-              compare --> diff
-                 diff --> apply
-      project_updated --> apply
-                apply --> project_applied
-      project_applied --> |apply post-migrations| project_full
+      project_updated --> |apply post-migrations| project_full
 
 %% style ----------------------------------------------------------
 classDef blackborder stroke:#000;
-class compare,update,apply blackborder;
+class regen_current,regen_latest,update blackborder;
 ```
 
 As you can see here, `copier` does several things:
@@ -247,15 +216,18 @@ branch. The following strategies won't work:
 
 -   `git checkout <branch>` – _error: you need to resolve your current index first_
 -   `git checkout .` – _error: path '&lt;filename&gt;' is unmerged_
--   `git merge --abort` – _fatal: There is no merge to abort (MERGE_HEAD missing)_
 
 Here is what you can do using Git in the terminal to throw away all changes:
 
-```shell
-git reset           # throw away merge conflict information
-git checkout .      # restore modified files
-git clean -d -i     # remove untracked files and folders
-```
+-   ```shell
+    git merge --abort
+    ```
+
+-   ```shell
+    git reset           # throw away merge conflict information
+    git checkout .      # restore modified files
+    git clean -d -i     # remove untracked files and folders
+    ```
 
 If you want fine-grained control to restore files selectively, read the output of the
 `git status` command attentively. It shows all the commands you may need as hints!

docs/updating.md

@@ -377,7 +377,6 @@ def test_copy_help() -> None:
 
 def test_update_help() -> None:
     _help = COPIER_CMD("update", "--help")
-    assert "-o, --conflict" in _help
     assert "copier update [SWITCHES] [destination_path=.]" in _help
     assert "--skip-answered" in _help
 

tests/test_cli.py

@@ -1,6 +1,5 @@
 from pathlib import Path
 from textwrap import dedent
-from typing import Literal
 
 import pytest
 from plumbum import local
@@ -177,34 +176,8 @@ def test_update_subdirectory_from_root_path(
     assert (dst / "subfolder" / "file1").read_text() == "version 2\nhello\na1\nbye\n"
 
 
-@pytest.mark.parametrize(
-    "conflict, readme, expect_reject",
-    [
-        (
-            "rej",
-            "upstream version 2\n",
-            True,
-        ),
-        (
-            "inline",
-            dedent(
-                """\
-                <<<<<<< before updating
-                downstream version 1
-                =======
-                upstream version 2
-                >>>>>>> after updating
-                """
-            ),
-            False,
-        ),
-    ],
-)
 def test_new_version_uses_subdirectory(
     tmp_path_factory: pytest.TempPathFactory,
-    conflict: Literal["rej", "inline"],
-    readme: str,
-    expect_reject: bool,
 ) -> None:
     # Template in v1 doesn't have a _subdirectory;
     # in v2 it moves all things into a subdir and adds that key to copier.yml.
@@ -259,15 +232,22 @@ def test_new_version_uses_subdirectory(
         git("tag", "v2")
 
     # Finally, update the generated project
-    copier.run_update(dst_path=dst, defaults=True, overwrite=True, conflict=conflict)
+    copier.run_update(dst_path=dst, defaults=True, overwrite=True)
     assert load_answersfile_data(dst).get("_commit") == "v2"
 
     # Assert that the README still exists, and the conflicts were handled
     # correctly.
     assert (dst / "README.md").exists()
 
-    assert (dst / "README.md").read_text().splitlines() == readme.splitlines()
-    assert (dst / "README.md.rej").exists() == expect_reject
+    assert (dst / "README.md").read_text() == dedent(
+        """\
+        <<<<<<< HEAD
+        downstream version 1
+        =======
+        upstream version 2
+        >>>>>>> copier/after-updating
+        """
+    )
 
     # Also assert the subdirectory itself was not rendered
     assert not (dst / subdir).exists()