git-merge-repo

Merge a repository's branch into the current repository's directory

$ git merge-repo [path/to/repo] [branch_name] [path/to/directory]

$ git merge-repo [path/to/remote_repo] [branch_name] .

git-merge-repo <source_repo_url> <source_branch> [<target_path>] [options]

Note: This is a conceptual synopsis for a common user-defined script or operation, not a standard command. Its actual syntax and capabilities depend entirely on the specific implementation used.

<source_repo_url>
    The URL or local path to the Git repository whose history is to be merged.

<source_branch>
    The specific branch from the source repository to be merged.

[<target_path>]
    Optional. The path within the current repository where the contents of the source repository should reside. If omitted, the source's content might be merged into the root.

[options]
    Placeholder for any implementation-specific options, such as `--no-commit`, `--squash`, or options related to history rewriting.

The term git-merge-repo does not refer to a standard, built-in Git command. Instead, it typically describes a common, advanced Git operation or a custom script designed to merge the complete history of an independent Git repository, or a specific subdirectory within it, into another existing repository.

The primary goal is often to consolidate separate projects into a single, unified repository while preserving their full commit histories. This task is more complex than a standard branch merge, as it involves integrating fundamentally different project histories and potentially rewriting parts of the commit graph to fit the new structure. Common methods to achieve this involve sophisticated use of commands like git subtree, git filter-branch, git remote, git fetch, and git read-tree.

Because git-merge-repo is a custom operation rather than a standard command, its usage comes with significant caveats:
Complexity: It often involves intricate Git commands and can be challenging to execute correctly, especially for those unfamiliar with advanced Git history manipulation.
History Rewriting: Many implementations involve rewriting commit history, which can be disruptive and dangerous in shared repositories if not handled with extreme care. Always back up your repository before attempting such operations.
Repository Size: Merging full histories can significantly increase the size of your repository, as all objects from the merged history are retained.
Merge Conflicts: Integrating disparate histories can lead to complex and numerous merge conflicts that require careful resolution.
Maintenance: If the merged repository was intended to be updated regularly from the source, setting up a robust, maintainable workflow (e.g., with git subtree) is crucial.

Consolidating Projects: Merging several independent Git repositories into a single, unified monorepo, where each original repo becomes a subdirectory.
Migrating Subdirectories: Extracting a subdirectory from one repository and moving it, with its full commit history, into a new location (often the root) of another repository.
Integrating External Codebases: Incorporating a third-party library or framework's development history directly into your project's main repository.

Using git subtree: The recommended modern approach. It allows embedding a subproject into your repository as a subdirectory. It can import history and push/pull changes relatively easily.
git filter-branch with git read-tree: A powerful but complex method. Involves fetching the source repository, then using git filter-branch to rewrite its history (e.g., prefixing all paths) before merging it into the target repository.
Manual git remote, git fetch, and git cherry-pick/rebase: A more manual approach suitable for smaller, controlled merges, where specific commits are picked from the source repository's history and applied to the target.

The concept of merging entire repository histories predates specific tool support. Early Git users often resorted to manual sequences of commands like git remote add, git fetch, and git read-tree, followed by careful commits and potentially git filter-branch to adjust paths or prune unwanted history.

The need for a more streamlined approach led to the development of custom scripts and aliases (often named conceptually like git-merge-repo) to automate these complex steps. The introduction of git subtree in Git 1.7.11 (July 2012) provided a more robust and officially supported mechanism for managing subprojects within a superproject, significantly simplifying many scenarios that previously required ad-hoc git-merge-repo scripts. Despite this, bespoke scripts are still common for highly specific or one-off repository consolidation tasks.

git merge(1), git remote(1), git fetch(1), git subtree(1), git filter-branch(1), git read-tree(1), git rebase(1)