Repository.merge_file_from_index() returns MergeFileResult by default

The previous string-returning behavior is still available with
`use_deprecated=True`, but is deprecated.

Author: jdavid

CHANGELOG.md

@@ -11,6 +11,10 @@ Breaking changes:
 - Remove deprecated support for passing `str` to `Repository.merge(...)`,
   pass a `Commit`, `Oid`, or `Reference` object instead
 
+- `Repository.merge_file_from_index(...)` now returns `MergeFileResult`
+  by default. The previous string-returning behavior is still available
+  with `use_deprecated=True`, but is deprecated.
+
 
 # 1.19.3 (2026-06-13)
 

pygit2/repository.py

@@ -813,13 +813,13 @@ def merge_file_from_index(
         ancestor: 'IndexEntry | None',
         ours: 'IndexEntry | None',
         theirs: 'IndexEntry | None',
-        use_deprecated: bool = True,
-    ) -> 'str | MergeFileResult | None':
+        use_deprecated: bool = False,
+    ) -> 'MergeFileResult | str | None':
         """Merge files from index.
 
-        Returns: A string with the content of the file containing
-        possible conflicts if use_deprecated==True.
-        If use_deprecated==False then it returns an instance of MergeFileResult.
+        Returns: An instance of MergeFileResult by default.
+        If use_deprecated==True then it returns a string with the content of
+        the file containing possible conflicts.
 
         ancestor
             The index entry which will be used as a common
@@ -829,9 +829,9 @@ def merge_file_from_index(
         theirs
             The index entry which will be merged into "ours"
         use_deprecated
-            This controls what will be returned. If use_deprecated==True (default),
-            a string with the contents of the file will be returned.
-            An instance of MergeFileResult will be returned otherwise.
+            This controls what will be returned. If use_deprecated==False (default),
+            an instance of MergeFileResult will be returned.
+            A string with the contents of the file will be returned otherwise.
         """
         cmergeresult = ffi.new('git_merge_file_result *')
 

test/test_repository.py

@@ -1073,46 +1073,63 @@ def get_hello_txt_from_repo() -> str:
         assert isinstance(blob, Blob)
         return blob.data.decode()
 
-    # no change
-    res = testrepo.merge_file_from_index(hello_txt, hello_txt, hello_txt)
-    assert res == get_hello_txt_from_repo()
+    with pytest.warns(DeprecationWarning, match='Getting an str'):
+        # no change
+        res = testrepo.merge_file_from_index(
+            hello_txt, hello_txt, hello_txt, use_deprecated=True
+        )
+        assert res == get_hello_txt_from_repo()
 
-    # executable switch on ours
-    res = testrepo.merge_file_from_index(hello_txt, hello_txt_executable, hello_txt)
-    assert res == get_hello_txt_from_repo()
+        # executable switch on ours
+        res = testrepo.merge_file_from_index(
+            hello_txt, hello_txt_executable, hello_txt, use_deprecated=True
+        )
+        assert res == get_hello_txt_from_repo()
 
-    # executable switch on theirs
-    res = testrepo.merge_file_from_index(hello_txt, hello_txt, hello_txt_executable)
-    assert res == get_hello_txt_from_repo()
+        # executable switch on theirs
+        res = testrepo.merge_file_from_index(
+            hello_txt, hello_txt, hello_txt_executable, use_deprecated=True
+        )
+        assert res == get_hello_txt_from_repo()
 
-    # executable switch on both
-    res = testrepo.merge_file_from_index(
-        hello_txt, hello_txt_executable, hello_txt_executable
-    )
-    assert res == get_hello_txt_from_repo()
+        # executable switch on both
+        res = testrepo.merge_file_from_index(
+            hello_txt, hello_txt_executable, hello_txt_executable, use_deprecated=True
+        )
+        assert res == get_hello_txt_from_repo()
 
-    # path switch on ours
-    res = testrepo.merge_file_from_index(hello_txt, hello_world, hello_txt)
-    assert res == get_hello_txt_from_repo()
+        # path switch on ours
+        res = testrepo.merge_file_from_index(
+            hello_txt, hello_world, hello_txt, use_deprecated=True
+        )
+        assert res == get_hello_txt_from_repo()
 
-    # path switch on theirs
-    res = testrepo.merge_file_from_index(hello_txt, hello_txt, hello_world)
-    assert res == get_hello_txt_from_repo()
+        # path switch on theirs
+        res = testrepo.merge_file_from_index(
+            hello_txt, hello_txt, hello_world, use_deprecated=True
+        )
+        assert res == get_hello_txt_from_repo()
 
-    # path switch on both
-    res = testrepo.merge_file_from_index(hello_txt, hello_world, hello_world)
-    assert res == get_hello_txt_from_repo()
+        # path switch on both
+        res = testrepo.merge_file_from_index(
+            hello_txt, hello_world, hello_world, use_deprecated=True
+        )
+        assert res == get_hello_txt_from_repo()
 
-    # path switch on ours, executable flag switch on theirs
-    res = testrepo.merge_file_from_index(hello_txt, hello_world, hello_txt_executable)
-    assert res == get_hello_txt_from_repo()
+        # path switch on ours, executable flag switch on theirs
+        res = testrepo.merge_file_from_index(
+            hello_txt, hello_world, hello_txt_executable, use_deprecated=True
+        )
+        assert res == get_hello_txt_from_repo()
 
-    # path switch on theirs, executable flag switch on ours
-    res = testrepo.merge_file_from_index(hello_txt, hello_txt_executable, hello_world)
-    assert res == get_hello_txt_from_repo()
+        # path switch on theirs, executable flag switch on ours
+        res = testrepo.merge_file_from_index(
+            hello_txt, hello_txt_executable, hello_world, use_deprecated=True
+        )
+        assert res == get_hello_txt_from_repo()
 
 
-def test_merge_file_from_index_non_deprecated(testrepo: Repository) -> None:
+def test_merge_file_from_index(testrepo: Repository) -> None:
     hello_txt = testrepo.index['hello.txt']
     hello_txt_executable = IndexEntry(
         hello_txt.path, hello_txt.id, FileMode.BLOB_EXECUTABLE
@@ -1126,15 +1143,15 @@ def get_hello_txt_from_repo() -> str:
 
     # no change
     res = testrepo.merge_file_from_index(
-        hello_txt, hello_txt, hello_txt, use_deprecated=False
+        hello_txt, hello_txt, hello_txt
     )
     assert res == MergeFileResult(
         True, hello_txt.path, hello_txt.mode, get_hello_txt_from_repo()
     )
 
     # executable switch on ours
     res = testrepo.merge_file_from_index(
-        hello_txt, hello_txt_executable, hello_txt, use_deprecated=False
+        hello_txt, hello_txt_executable, hello_txt
     )
     assert res == MergeFileResult(
         True,
@@ -1145,7 +1162,7 @@ def get_hello_txt_from_repo() -> str:
 
     # executable switch on theirs
     res = testrepo.merge_file_from_index(
-        hello_txt, hello_txt, hello_txt_executable, use_deprecated=False
+        hello_txt, hello_txt, hello_txt_executable
     )
     assert res == MergeFileResult(
         True,
@@ -1156,7 +1173,7 @@ def get_hello_txt_from_repo() -> str:
 
     # executable switch on both
     res = testrepo.merge_file_from_index(
-        hello_txt, hello_txt_executable, hello_txt_executable, use_deprecated=False
+        hello_txt, hello_txt_executable, hello_txt_executable
     )
     assert res == MergeFileResult(
         True,
@@ -1167,29 +1184,29 @@ def get_hello_txt_from_repo() -> str:
 
     # path switch on ours
     res = testrepo.merge_file_from_index(
-        hello_txt, hello_world, hello_txt, use_deprecated=False
+        hello_txt, hello_world, hello_txt
     )
     assert res == MergeFileResult(
         True, hello_world.path, hello_txt.mode, get_hello_txt_from_repo()
     )
 
     # path switch on theirs
     res = testrepo.merge_file_from_index(
-        hello_txt, hello_txt, hello_world, use_deprecated=False
+        hello_txt, hello_txt, hello_world
     )
     assert res == MergeFileResult(
         True, hello_world.path, hello_txt.mode, get_hello_txt_from_repo()
     )
 
     # path switch on both
     res = testrepo.merge_file_from_index(
-        hello_txt, hello_world, hello_world, use_deprecated=False
+        hello_txt, hello_world, hello_world
     )
     assert res == MergeFileResult(True, None, hello_txt.mode, get_hello_txt_from_repo())
 
     # path switch on ours, executable flag switch on theirs
     res = testrepo.merge_file_from_index(
-        hello_txt, hello_world, hello_txt_executable, use_deprecated=False
+        hello_txt, hello_world, hello_txt_executable
     )
     assert res == MergeFileResult(
         True,
@@ -1200,7 +1217,7 @@ def get_hello_txt_from_repo() -> str:
 
     # path switch on theirs, executable flag switch on ours
     res = testrepo.merge_file_from_index(
-        hello_txt, hello_txt_executable, hello_world, use_deprecated=False
+        hello_txt, hello_txt_executable, hello_world
     )
     assert res == MergeFileResult(
         True,

test/test_repository_bare.py

@@ -241,7 +241,7 @@ def create_conflict_file(repo: Repository, branch: Branch, content: str) -> Oid:
     (a, t, o) = index.conflicts['conflict']
     diff = barerepo.merge_file_from_index(a, t, o)
     assert (
-        diff
+        diff.contents
         == """<<<<<<< conflict
 ASCII - abc
 =======