Repository: get all values from git_merge_file_from_index

In Repository.merge_file_from_index, pygit2 is only returning
the resulting content out of the merge, however other values might be
relevant like the filemode.

Add an optional flag to make it possible to get all the values
coming out of git_merge_file_from_index instead of just
the file content.

Author: eantoranz

pygit2/repository.py

@@ -682,9 +682,15 @@ def merge_file_from_index(
         ancestor: typing.Union[None, IndexEntry],
         ours: typing.Union[None, IndexEntry],
         theirs: typing.Union[None, IndexEntry],
-    ) -> str:
-        """Merge files from index. Return a string with the merge result
-        containing possible conflicts.
+        return_full: bool = False,
+    ) -> typing.Union[str, tuple[bool, str, int, typing.Union[str,None]]]:
+        """Merge files from index.
+
+        Returns: A string with the content of the file containing
+        possible conflicts.
+        If return_full then it returns a tuple containing
+        whether the file is automergeable, the content of the file,
+        the filemode and the path.
 
         ancestor
             The index entry which will be used as a common
@@ -693,6 +699,8 @@ def merge_file_from_index(
             The index entry to take as "ours" or base.
         theirs
             The index entry which will be merged into "ours"
+        return_full
+            Whether to return the full output of the low-level call.
         """
         cmergeresult = ffi.new('git_merge_file_result *')
 
@@ -709,10 +717,16 @@ def merge_file_from_index(
         )
         check_error(err)
 
-        ret = ffi.string(cmergeresult.ptr, cmergeresult.len).decode('utf-8')
+        automergeable = cmergeresult.automergeable != 0
+        content = ffi.string(cmergeresult.ptr, cmergeresult.len).decode('utf-8')
+        filemode = cmergeresult.mode
+        path = cmergeresult.path
         C.git_merge_file_result_free(cmergeresult)
 
-        return ret
+        if not return_full:
+            return content
+
+        return automergeable, content, filemode, path
 
     def merge_commits(
         self,
@@ -834,6 +848,41 @@ def merge_trees(
 
         return Index.from_c(self, cindex)
 
+    def merge_files(self,
+                    ancestor: typing.Union[str, Oid, Blob],
+                    ours: typing.Union[str, Oid, Blob],
+                    theirs: typing.Union[str, Oid, Blob],
+                    opts: MergeFileFlag=MergeFileFlag.DEFAULT):
+        """
+        Merge two files using the common ancestor as the baseline.
+
+        Returns: an Index that reflects the result of the merge.
+
+        Parameters:
+
+        ancestor:
+        ours:
+        theirs:
+        pots:
+            A combination of enums.MergeFileFlag constants.
+        :return:
+        """
+        cmergeresult = ffi.new('git_merge_file_result *')
+
+        cancestor = ancestor._to_c() if ancestor else ffi.NULL
+        cours = ours._to_c() if ours else ffi.NULL
+        ctheirs = theirs._to_c if theirs else ffi.NULL
+
+        err = C.git_merge_file(
+            cmergeresult, cancestor, cours, ctheirs, opts
+        )
+        check_error(err)
+
+        ret = ffi.string(cmergeresult.ptr, cmergeresult.len).decode('utf-8')
+        C.git_merge_file_result_free(cmergeresult)
+
+        return ret
+
     def merge(
         self,
         source: typing.Union[Reference, Commit, Oid, str],