In this post, we feature a comprehensive Example on Git Add Submodule.<\/p>\n
An important concept in software development is reusability. When working on a software project you may have situations where a function or method is used in many places of an application. Rather than interspersing the function\/method code throughout the application, it is useful to place it in a utility class. In a large project where you have many such classes, you may want to move them to a separate project.<\/p>\n
If your codebase becomes very large, you may also want to consider creating subprojects. There are advantages to breaking up a large project into smaller projects. For example:<\/p>\n
\n
\nLet\u2019s assume that these separate projects have their own Git repositories. How can you use the utility project within the main project? In Git, you can include the utility project by adding it as a submodule to the main project.<\/p>\n
A submodule is a repository that is contained inside a subdirectory of another repository. Logically, it can be thought of child project of a parent project. Git tracking for the submodule is managed separately from that of the main project. Code that is developed by a 3rd party is often included as a submodule in Git. Themes and plugins in WordPress too are typically included as submodules when Git is used as the Version Control System.<\/p>\n
In Git you can add, clone, update and remove submodules within the main project. In this example, we will demonstrate how to add a repository as a submodule of another repository.<\/p>\n
Git downloads are available here: https:\/\/git-scm.com\/downloads<\/a>.<\/p>\n In this example, we will create a local repository that contains a utility class. We will then add the new repository as a submodule of an existing main project.<\/p>\n First, download the “Submodule Demo” archive from the Download<\/a> section and extract it in a directory of your choice.<\/p>\n We have a main project (named “demo”) that is tracked in a local repository. If you view the Git config file, you will see configuration information for the main project.<\/p>\n Let us suppose that the “demo” project uses file input\/output operations. Let us further assume that these operations are used in many places within the application. With these points in mind, we created a utility class for those operations and placed it into its own project named “ioutils”. We’ll add the “ioutils” project to its own local Git repository next. Open a terminal (shell) in the “ioutils” directory where the archive was extracted and run the following command:<\/p>\n Git init Command Output<\/em><\/span><\/p>\n This creates an empty Git repository. The repository metadata has been generated in the \u201c.git\u201d folder.<\/p>\n (Note:<\/strong> This folder is hidden by default as you would, typically, not edit its contents.)<\/p>\n Let\u2019s add the file to the repository. Run the following command:<\/p>\n This will add the Commit the file from the staging area to the repository with the following command:<\/p>\n Note:<\/strong> The -m option allows us to add a commit message inline.<\/p>\n Git commit Command Output<\/em><\/span><\/p>\n Now that we have our utility class in its own Git repository, let’s add it as a submodule to the “demo” project. Run the following command:<\/p>\n Note:<\/strong> The -f option is used to force the creation of Git Submodule Add Command Output<\/em><\/span><\/p>\n The If you view the Git config file for the main project after running the This submodule is identified by the path where the Next, check the status of the main project with the following command:<\/p>\n Git status Command Output<\/em><\/span><\/p>\n The It is important to note that main and submodule repositories track independently of each other. Go to the submodule\u2019s directory (“src\/main\/java\/com\/javacodegeeks\/example\/ioutils”) and run the Git status command:<\/p>\n As you can see, the submodule\u2019s Git is unaware of any changes made to the main project.<\/p>\n The Git status for the main project provides some basic information about the staged files. You can get additional information by making the status command submodule-aware. Navigate back to the ‘demo’ directory and run the following command:<\/p>\n Now run the Git status command again.<\/p>\n The status now shows that the remote repository has 1 commit and that the commit was an addition with the commit message ‘Initial commit’.<\/p>\n To commit the files from the staging area to the repository, run the following command:<\/p>\n Git commit Command Output<\/em><\/span><\/p>\n Let’s take a look at the .gitmodules file.<\/p>\n The .gitmodules file holds all the submodule configuration information for this project. The data contained in this file is read by Git when anyone clones our project. It is used to locate the submodule repository (url = ..\/ioutils<\/em>) and to specify the subdirectory of the main project where the submodule will be integrated (path = src\/main\/java\/com\/javacodegeeks\/example\/ioutils<\/em>).<\/p>\n If you simply want to see the locations of your submodules, use the following command:<\/p>\n Git submodule status Command Output<\/em><\/span><\/p>\n The output displays the SHA-1 of the currently checked out commit for each submodule in the main project and the path locations where the submodules reside. (In our example, there is only one submodule.)<\/p>\n Adding submodules is a great way of integrating other Git repositories to your main project, whether these repositories are from a 3rd party or projects you created yourself for reuse.<\/p>\n That was Git Add Submodule Example.<\/p>\n2. Git Add Submodule Example<\/h2>\n
2.1 Download and Extract the Sample Project<\/h3>\n
$ ls -R\n.:\ndemo\/ ioutils\/\n\n.\/demo:\nmvnw* mvnw.cmd pom.xml src\/\n\n.\/demo\/src:\nmain\/ test\/\n\n.\/demo\/src\/main:\njava\/ resources\/\n\n.\/demo\/src\/main\/java:\ncom\/\n\n.\/demo\/src\/main\/java\/com:\njavacodegeeks\/\n\n.\/demo\/src\/main\/java\/com\/javacodegeeks:\nexample\/\n\n.\/demo\/src\/main\/java\/com\/javacodegeeks\/example:\ndemo\/\n\n.\/demo\/src\/main\/java\/com\/javacodegeeks\/example\/demo:\nDemoApplication.java\n\n.\/demo\/src\/main\/resources:\napplication.properties\n\n.\/demo\/src\/test:\njava\/\n\n.\/demo\/src\/test\/java:\ncom\/\n\n.\/demo\/src\/test\/java\/com:\njavacodegeeks\/\n\n.\/demo\/src\/test\/java\/com\/javacodegeeks:\nexample\/\n\n.\/demo\/src\/test\/java\/com\/javacodegeeks\/example:\ndemo\/\n\n.\/demo\/src\/test\/java\/com\/javacodegeeks\/example\/demo:\nDemoApplicationTests.java\n\n.\/ioutils:\nFileUtil.java\n<\/pre>\n
$ cat .git\/config\n[core]\n repositoryformatversion = 0\n filemode = false\n bare = false\n logallrefupdates = true\n symlinks = false\n ignorecase = true\n\n<\/pre>\n
2.2 Create a Local Repository<\/h3>\n
$ git init<\/pre>\n
Initialized empty Git repository in \/Users\/gilbertlopez\/ioutils\/.git\/\n<\/pre>\n
2.3 Add and Commit the File to the Project Repository<\/h3>\n
$ git add FileUtil.java<\/pre>\n
FileUtil.java<\/code> file to the repository index. The file is now in the staging area.<\/p>\n$ git commit -m 'Initial commit of project'<\/pre>\n
[master (root-commit) 45e1f63] initial commit\n 1 file changed, 49 insertions(+)\n create mode 100644 FileUtil.java<\/pre>\n
2.4 Add a Submodule to the Main Project<\/h3>\n
git submodule add -f ..\/ioutils src\/main\/java\/com\/javacodegeeks\/example\/ioutils<\/pre>\n
src\/main\/java\/com\/javacodegeeks\/example\/ioutils<\/code>, the directory where we want the submodule to reside.<\/p>\n\n
submodule add<\/code> command specifies the location of the repository to be added as a submodule. This could be a local repository (“ioutils” in this example) or a remote repository, e.g. https:\/\/github.com\/gilbertlopez\/example.git. It probably goes without saying that you need to be able to clone the repository in order to add it as a submodule.<\/li>\nioutils <\/code>repository to be integrated. If you omit this parameter, Git will add the subproject to directory named the same as the repository (in this case, “ioutils”).<\/li>\n<\/ul>\nCloning into 'C:\/Users\/Gilbert\/gittest\/demo\/src\/main\/java\/com\/javacodegeeks\/example\/ioutils'...\ndone.\nwarning: LF will be replaced by CRLF in .gitmodules.\nThe file will have its original line endings in your working directory.\n<\/pre>\n
add submodule<\/code> command registered the ioutils <\/code>repository within the main project repository’s configuration. It also cloned the repository into the \/src\/main\/java\/com\/javacodegeeks\/example\/ioutils<\/code> directory.<\/p>\nsubmodule add<\/code> command, you will notice an additional section.<\/p>\n$ cat .git\/config\n[core]\n repositoryformatversion = 0\n filemode = false\n bare = false\n logallrefupdates = true\n symlinks = false\n ignorecase = true\n[submodule \"src\/main\/java\/com\/javacodegeeks\/example\/ioutils\"]\n url = C:\/Users\/Gilbert\/gittest\/ioutils\n active = true\n<\/pre>\n
ioutils <\/code>repository resides. The \u2018url\u2019 value in the submodule section shows the repository URL link (or directory path for a local repository) of the submodule that Git uses to clone the project.[ulp id=’pzgfvmZhgslwSymm’]<\/p>\n$ git status<\/pre>\n
On branch master\nChanges to be committed:\n (use \"git reset HEAD ...\" to unstage)\n\n new file: .gitmodules\n new file: src\/main\/java\/com\/javacodegeeks\/example\/ioutils\n<\/pre>\n
submodule add<\/code> command staged two new files: “.gitmodules” and “src\/main\/java\/com\/javacodegeeks\/example\/ioutils”. (Submodule directories and their contents appear as a single file when viewed by the main project’s Git repository.) If you look in the ioutils <\/code>subdirectory of the main project, you will see that FileUtil.java<\/code> from the “ioutils” repository was cloned into that location.<\/p>\n$ git status\nOn branch master\nYour branch is up to date with 'origin\/master'.\n\nnothing to commit, working tree clean\n<\/pre>\n
$ git config --global status.submoduleSummary true<\/pre>\n
$ git status\nOn branch master\nChanges to be committed:\n (use \"git reset HEAD ...\" to unstage)\n\n\tnew file: .gitmodules\n\tnew file: src\/main\/java\/com\/javacodegeeks\/example\/ioutils\n\nSubmodule changes to be committed:\n\n* src\/main\/java\/com\/javacodegeeks\/example\/ioutils 0000000...a3255ca (1):\n > Initial commit\n<\/pre>\n
$ git commit -m 'Added ioutils submodule'<\/pre>\n
[master 992ad34] Added ioutils submodule\n 2 files changed, 4 insertions(+)\n create mode 100644 .gitmodules\n create mode 160000 src\/main\/java\/com\/javacodegeeks\/example\/ioutils\n<\/pre>\n
2.5 View the .gitmodules File<\/h3>\n
$ cat .gitmodules\n[submodule \"src\/main\/java\/com\/javacodegeeks\/example\/ioutils\"]\n path = src\/main\/java\/com\/javacodegeeks\/example\/ioutils\n url = ..\/ioutils\n<\/pre>\n
2.6 View the Status of Submodules<\/h3>\n
$ git submodule status<\/pre>\n
e51bafee08eff11e55817d789d40fe96a216c4a7 src\/main\/java\/com\/javacodegeeks\/example\/ioutils (heads\/master)\n<\/pre>\n
3. Summary<\/h2>\n
<\/a>4. Download the Source Code<\/h2>\n