git-merge-index

git-merge-index [--reread-full-tree] <merge_program> [<arguments_to_merge_program>...]

--reread-full-tree
    Forces git-merge-index to re-read the entire index from disk before processing, rather than relying on its in-memory cache. This can be useful if the index might have been modified by another process outside of git-merge-index.

<merge_program>
    The path to the external merge program that git-merge-index should invoke for each file that needs merging. This program is expected to take specific arguments (typically paths to the common ancestor, 'ours', and 'theirs' versions of the file, and the output path) and resolve the conflict.

<arguments_to_merge_program>...
    Any additional arguments that should be passed directly to the merge_program. These arguments follow the merge_program itself.

git-merge-index is a low-level "plumbing" command in Git, primarily used internally by higher-level merge commands like git merge. Its main purpose is to manage the Git index during a three-way merge operation. When git merge encounters a conflict, git-merge-index is responsible for invoking an external merge program (specified by merge_program) for each conflicted file. It prepares the index entries (stage 1 for common ancestor, stage 2 for 'ours', and stage 3 for 'theirs') for the external tool.

After the external tool completes, git-merge-index updates the working tree with the tool's output, and then stages the resolved content back into the index. This command doesn't perform the merge itself; it orchestrates the process of resolving conflicts by delegating to a user-configured or default merge tool. It's a crucial component for enabling flexible conflict resolution using various external diff/merge utilities configured via git config merge.tool. It effectively bridges the gap between Git's internal index representation of conflicts and the user's preferred method for conflict resolution.

git-merge-index is a plumbing command, meaning it's designed for internal Git operations and script usage, not for direct interactive use by end-users. Incorrect usage can lead to a corrupted index or working tree state. It relies on the specified merge_program to correctly handle file merging and return a zero exit status upon success; otherwise, it treats the merge as failed.

git-merge-index primarily interacts with the three conflict stages in the Git index: stage 1 (the common ancestor version of the file), stage 2 (the 'ours' version, from the current branch), and stage 3 (the 'theirs' version, from the branch being merged). It extracts these versions for the external merge tool.

The merge_program is invoked with specific arguments that represent the different file versions (ancestor, ours, theirs) and the output path. After the tool completes, git-merge-index examines its exit status and the output file to update the index and working tree accordingly.

Upon successful resolution by the merge_program, git-merge-index updates the working directory file with the merged content and clears the conflict entries from the index, replacing them with a single, resolved entry.

git-merge-index has been a fundamental part of Git's merge machinery since its very early days. It was introduced as a core component to enable the robust three-way merge strategy and the integration of external merge tools. Its design reflects Git's philosophy of providing low-level plumbing commands that can be composed to build higher-level "porcelain" commands. Over time, its functionality has remained consistent as the underlying mechanism for handling index entries during merges, adapting to minor changes in Git's internal object model and index format.

git-merge(1), git-read-tree(1), git-ls-files(1), git-write-tree(1)