Git Submodules

There are many repositories in GitHub for CDISC projects.  In many cases, as these projects mature, they are required by other projects held in separate repositories. In some cases, developers have been migrating their code from one repo into another making maintaining the code in two repositories difficult and prone to divergence.

There is a better approach to including the code from one repository in another - Git submodules.

Features:

• Way to include one repo in another as a subdirectory
• Managed separately from main project/repo
• Repo nested in another repo
• Track version history of external code without merging directly into main project
• Allows strict version control of submodule
• Facilitates collaboration by allowing teams to work on different components independently
• Maintains separate histories
• Reduces duplication of code in multiple projects
• By default, submodules are pinned to specific commits (versions)
• This approach allows development to continue in the submodule repos without impacting the main repo (superproject) and vice versa.
• Development changes can be made to the submodule from within the superproject and the updates can be committed and pushed from the superproject into the submodule repo.
• submodule maintains a separate reference to the external repo

Add a submodule to another repo/project:

% git submodule add <url> [<path>]
% git submodule update --init

To update the submodule to its latest commit:

% cd <submodule_path>
% git pull

Or, udpate submodules to their latest commit:

% git submodule update --remote

Once the submodule has been initialized, a user can clone the main repo/project with submodules:

% git clone --recurse-submodules <repo.git>

This command will clone the main repo with all of its submodules.

To update a submodule within the main repo:

% cd <submodule_path>
% git add .
% git commit -m "Update to submodule content"

Then push the changes to the submodule repo:

% git push

Now update the superproject:

% cd ..
% git add <submodule_path>
% git commit -m "Update submodule reference"

n order to delete a submodule from the superproject, remove the reference in .gitmodules and delete the <submodule_path> directory.

There is more information and examples here: 

https://www.geeksforgeeks.org/git/git-submodule/

https://www.geeksforgeeks.org/git/git-subtree-vs-git-submodule/