Merging Local and Remote Git Repos: Fixing Unrelated Histories

Let's explore the context of merging files from a remote repository with a local source code branch.

We often encounter a scenario where we have a local Git repository with source code and create a remote Git repository with a README.md and/or .gitignore file. We then want our local repo to seamlessly merge these files in preparation for git push -u origin main. However, we sometimes face those pesky merge notifications locally during the merging process.

Let me give an example.

Usually we perform the git remote add origin https://github.com/rajks24/projectname.git , and perform git pull to merge the remote files to local git branch, before final git push , but we get errors like below.

❯ git pull                                     
hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint: 
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
hint: 
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.
fatal: Need to specify how to reconcile divergent branches.

❯ git pull hint: You have divergent branches and need to specify how to reconcile them. 
hint: You can do so by running one of the following commands sometime before hint: your next pull: hint: hint: git confi g pull.rebase false # merge hint: git confi g pull.rebasetrue # rebase hint: git confi g pull.ff only # fast-forward only hint: hint: You can replace “git confi g” with “gitconfi g --global” to set a default hint: preference for all repositories. You can also pass --rebase, --no-rebase,hint: or --ff-only on the command line to override the confi gured default per hint: invocation. fatal: Need tospecify how to reconcile divergent branches.

To start with the resolution, we need to configure local git to merge by default with git config pull.rebase false .

Even with above settings, for git pull or git merge, we might also get an error as From https://github.com/rajks24/projectname branch main -> FETCH_HEAD fatal: refusing to merge unrelated histories.

So, to get through above error, we can perform following actions.

Pull and Merge with Unrelated Histories

Since the remote repo has some initial files, we will need to pull and merge with the
--allow-unrelated-histories flag:

❯ git pull origin main --allow-unrelated-histories 
From https://github.com/rajks24/projectname
 * branch            main       -> FETCH_HEAD
Merge made by the 'ort' strategy.
 LICENSE | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 LICENSE

Resolve Merge Conflicts (If Any)

If we encounter any merge conflicts, Git will prompt us to resolve them. Open the conflicting files, fix the conflicts, and then stage the changes:

git add <conflicting_file>

Commit the Merge

Once you’ve resolved the conflicts, commit the merge:

git commit -m"Merge remote-tracking branch 'origin/main' into main"

Push the Main Branch

Now, push the main branch to the remote repository with git push -u origin main .

Push All Other Branches (optional)

Push all your other branches to the remote repository with git push --all origin .

Final Thoughts

Merging repositories might seem daunting at first, but it's an essential skill for any developer working in a collaborative environment. By understanding these concepts and techniques, you're not just solving immediate problems – you're building a foundation for smoother, more efficient workflow in all your future projects.

Keep experimenting, keep learning, and most importantly, keep Git-ing it together!