Git/GitHub: fork, subtree merge or submodule for external code?

Question

Hi! I'd like to incorporate an existing project (hosted on GitHub) as a part of my project (into a subdirectory) while maintaining the history and the ability to update that project. I've found that there can be about three approaches:

1. Fork the original project, move the original contents into a subdirectory and push it to my GitHub repo.
2. Init a new repo, do a subtree merge with the existing repo and push to my GitHub repo.
3. Clone the existing repo, make a new main repo, put the cloned repo into the main one as a submodule, push.

The (1) variant could be the preferable one at GitHub as they can probably share the sources. But logically my project is not a fork of the existing one. Rather the existing one is just a module. Also I'm not sure if moving the existing code into a subdirectory might not make problems. I would probably prefer the (2) variant as there is only one repo. (3) would require working with several repos but logically is the closest to my situation.

I have researched this quite a bit, but I'm not definitely sure. What would you recommend in this situation? Thank you in advance!

Answer 1

You can add original project as a submodule to your git application:

git submodule add git://github.com/__orig_repo.git __orig_repo_dir
git submodule update --init

Another way is to clone existing repo:

git clone git://github.com/__orig_repo.git __orig_repo_dir

then you can update it using git:

cd __orig_repo_dir
git submodule update --init

Answer 2

If the development lifecycle of the two projects (the one on GitHub, and yours) are different, then the submodule approach is better.
I.e: if you change your project without having systematically to change the other GitHub project, then you should consider the submodule approach.

However, to implement this, you would need a combination of (1) and (3):

• if you cannot contribute (push) directly to the GitHub project, you need to fork it (1).
• then you need to reference that forked project as a submodule in your project (3).

It will allow you to refer one specific revision of the GitHub project, while allowing you to update that submodule and make specific push for it (as described in "true nature of submodules").
But once you have updated the submodule, don't forget to commit your project (which is the "parent project" for the submodule), in order to register the new revision of the submodule you are now referencing.