{"id":19111111,"url":"https://github.com/jonathanxdr/git-submodules","last_synced_at":"2025-06-10T08:05:53.320Z","repository":{"id":118718596,"uuid":"460356501","full_name":"JonathanXDR/Git-Submodules","owner":"JonathanXDR","description":"A preview, cheatsheet and guide for git submodules","archived":false,"fork":false,"pushed_at":"2023-12-19T14:13:34.000Z","size":6,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-02T14:27:48.638Z","etag":null,"topics":["cheatsheet","git","guide","preview","submodules"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JonathanXDR.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-17T09:01:14.000Z","updated_at":"2022-05-20T07:49:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"10240eb2-b22e-4cfd-9a59-652d1367fbc1","html_url":"https://github.com/JonathanXDR/Git-Submodules","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonathanXDR%2FGit-Submodules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonathanXDR%2FGit-Submodules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonathanXDR%2FGit-Submodules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonathanXDR%2FGit-Submodules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JonathanXDR","download_url":"https://codeload.github.com/JonathanXDR/Git-Submodules/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonathanXDR%2FGit-Submodules/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259033823,"owners_count":22795769,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cheatsheet","git","guide","preview","submodules"],"created_at":"2024-11-09T04:27:07.475Z","updated_at":"2025-06-10T08:05:53.253Z","avatar_url":"https://github.com/JonathanXDR.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Using submodules in Git\n\n## [1. Submodules - repositories inside other Git repositories](https://www.vogella.com/tutorials/GitSubmodules/article.html#submodules)\n\n### [1.1. Using Git repositories inside other Git repositories](https://www.vogella.com/tutorials/GitSubmodules/article.html#using-git-repositories-inside-other-git-repositories)\n\nGit allows you to include other Git repositories called _submodules_ into a repository. This allows you to track changes in several repositories via a central one. Submodules are Git repositories nested inside a parent Git repository at a specific path in the parent repository’s working directory. A submodule can be located anywhere in a parent Git repository’s working directory and is configured via a `.gitmodules` file located at the root of the parent repository. This file contains which paths are submodules and what URL should be used when cloning and fetching for that submodule. Submodule support includes support for adding, updating, synchronizing, and cloning submodules.\n\nGit allows you to commit, pull and push to these repositories independently.\n\nSubmodules allow you to keep projects in separate repositories but still be able to reference them as folders in the working directory of other repositories.\n\n## [2. Working with repositories that contain submodules](https://www.vogella.com/tutorials/GitSubmodules/article.html#working-with-repositories-that-contain-submodules)\n\n### [2.1. Cloning a repository that contains submodules](https://www.vogella.com/tutorials/GitSubmodules/article.html#cloning-a-repository-that-contains-submodules)\n\nIf you want to clone a repository including its submodules you can use the `--recursive` parameter.\n\n```\ngit clone --recursive [URL to Git repo]\n```\n\nIf you already have cloned a repository and now want to load it’s submodules you have to use `submodule update`.\n\n```\ngit submodule update --init\n# if there are nested submodules:\ngit submodule update --init --recursive\n```\n\n### [2.2. Downloading multiple submodules at once](https://www.vogella.com/tutorials/GitSubmodules/article.html#downloading-multiple-submodules-at-once)\n\nSince a repository can include many submodules, downloading them all sequentially can take much time. For this reason `clone` and `submodule update` command support the `--jobs` parameter to fetch multiple submodules at the same time.\n\n```\n# download up to 8 submodules at once\ngit submodule update --init --recursive --jobs 8\ngit clone --recursive --jobs 8 [URL to Git repo]\n# short version\ngit submodule update --init --recursive -j 8\n```\n\n### [2.3. Pulling with submodules](https://www.vogella.com/tutorials/GitSubmodules/article.html#submodules_pulling)\n\nOnce you have set up the submodules you can update the repository with fetch/pull like you would normally do. To pull everything including the submodules, use the `--recurse-submodules` and the `--remote` parameter in the `git pull command`.\n\n```\n# pull all changes in the repo including changes in the submodules\ngit pull --recurse-submodules\n\n# pull all changes for the submodules\ngit submodule update --remote\n```\n\n### [2.4. Executing a command on every submodule](https://www.vogella.com/tutorials/GitSubmodules/article.html#executing-a-command-on-every-submodule)\n\nGit provides a command that lets us execute an arbitrary shell command on every submodule. To allow execution in nested subprojects the `--recursive` parameter is supported. For our example we assume that we want to reset all submodules.\n\n```\ngit submodule foreach 'git reset --hard'\n# including nested submodules\ngit submodule foreach --recursive 'git reset --hard'\n```\n\n## [3. Creating repositories with submodules](https://www.vogella.com/tutorials/GitSubmodules/article.html#creating-repositories-with-submodules)\n\n### [3.1. Adding a submodule to a Git repository and tracking a branch](https://www.vogella.com/tutorials/GitSubmodules/article.html#submodules_trackbranch)\n\nIf you add a submodule, you can specify which branch should be tracked via the `-b` parameter of the `submodule add` command. The `git submodule init` command creates the local configuration file for the submodules, if this configuration does not exist.\n\n```\n# add submodule and define the master branch as the one you want to track\ngit submodule add -b master [URL to Git repo]\n\n# initialize submodule configuration\ngit submodule init\n```\n\nIf you track branches in your submodules, you can update them via the `--remote` parameter of the `git submodule update` command. This pulls in new commits into the main repository and its submodules. It also changes the working directories of the submodules to the commit of the tracked branch.\n\n```\n# update your submodule --remote fetches new commits in the submodules\n# and updates the working tree to the commit described by the branch\ngit submodule update --remote\n```\n\n### [3.2. Adding a submodule and tracking commits](https://www.vogella.com/tutorials/GitSubmodules/article.html#submodules_adding)\n\nAlternatively to the tracking of a branch, you can also control which commit of the submodule should be used. In this case the Git parent repository tracks the commit that should be checked out in each configured submodule. Performing a submodule update checks out that specific revision in the submodule’s Git repository. You commonly perform this task after you pull a change in the parent repository that updates the revision checked out in the submodule. You would then fetch the latest changes in the submodule’s Git repository and perform a submodule update to check out the current revision referenced in the parent repository. Performing a submodule update is also useful when you want to restore your submodule’s repository to the current commit tracked by the parent repository. This is common when you are experimenting with different checked out branches or tags in the submodule and you want to restore it back to the commit tracked by the parent repository. You can also change the commit that is checked out in each submodule by performing a checkout in the submodule repository and then committing the change in the parent repository.\n\nYou add a submodule to a Git repository via the `git submodule add` command.\n\n```\n# add a submodule to the existing Git repository\ngit submodule add [URL to Git repo]\n\n# initialize submodule configuration\ngit submodule init\n```\n\n### [3.3. Updating which commit your are tracking](https://www.vogella.com/tutorials/GitSubmodules/article.html#submodules_track)\n\nThe relevant state for the submodules are defined by the main repository. If you commit in your main repository, the state of the submodule is also defined by this commit.\n\nThe `git submodule update` command sets the Git repository of the submodule to that particular commit. The submodule repository tracks its own content which is nested into the main repository. The main repository refers to a commit of the nested submodule repository.\n\nUse the `git submodule update` command to set the submodules to the commit specified by the main repository. This means that if you pull in new changes into the submodules, you need to create a new commit in your main repository in order to track the updates of the nested submodules.\n\nThe following example shows how to update a submodule to its latest commit in its master branch.\n\n```\n# update submodule in the master branch\n# skip this if you use --recurse-submodules\n# and have the master branch checked out\ncd [submodule directory]\ngit checkout master\ngit pull\n\n# commit the change in main repo\n# to use the latest commit in master of the submodule\ncd ..\ngit add [submodule directory]\ngit commit -m \"move submodule to latest commit in master\"\n\n# share your changes\ngit push\n```\n\nAnother developer can get the update by pulling in the changes and running the submodules update command.\n\n```\n# another developer wants to get the changes\ngit pull\n\n# this updates the submodule to the latest\n# commit in master as set in the last example\ngit submodule update\n```\n\n**_Warning_**\n\n\u003e _With this setup you need to create a new commit in the master repository, to use a new state in the submodule. You need to repeat this procedure every time you want to use another state in one of the submodules. See[Adding a submodule to a Git repository and tracking a branch](https://www.vogella.com/tutorials/GitSubmodules/article.html#submodules_trackbranch) for tracking a certain branch of a submodule._\n\n### [3.4. Delete a submodule from a repository](https://www.vogella.com/tutorials/GitSubmodules/article.html#delete-a-submodule-from-a-repository)\n\nCurrently Git provides no standard interface to delete a submodule. To remove a submodule called `mymodule` you need to:\n\n- git submodule deinit -f — mymodule\n- rm -rf .git/modules/mymodule\n- git rm -f mymodule\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonathanxdr%2Fgit-submodules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonathanxdr%2Fgit-submodules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonathanxdr%2Fgit-submodules/lists"}