git-submodule Documentation
The commit recorded in the superproject will bechecked out in the submodule on a detached HEAD. This will download the submodule repository from the URL and clone it into the submodule_directory folder. Submodules also make it easier to maintain and use forks of common libraries, which is something that many companies opt for when additional features or customization is necessary.
.jpeg)
Each SHA-1 will possibly be prefixed with – if the submodule isnot initialized, + if the currently checked out submodule commitdoes not match the SHA-1 found in the index of the containingrepository and U if the submodule has merge conflicts. If there are new commits in the submodule repositories, you may need to run git submodule update to update the submodules to the latest state. It’s important to note that submodules these days keep all their Git data in the top project’s .git directory, so unlike much older versions of Git, destroying a submodule directory won’t lose any commits or branches that you had. There is another way to do this which is a little simpler, however.If you pass –recurse-submodules to the git clone command, it will automatically initialize and update each submodule in the repository, including nested submodules if any of the submodules in the repository have submodules themselves.
.jpeg)
Configuration settings
So let me get this straight, this official guide still contains errors? It comes up as top hit on Google when people search for how to use git submodules. Also git pull does a git fetch, and most people typically just use git pull. And advanced users, that use git fetch, will know that git pull does a git fetch and will receive new information about the repository.
Working with Branches in Submodules
If this option is given, the submodule’s HEAD willnot be detached. If a merge failure prevents this process, you willhave to resolve the resulting conflicts within the submodule with theusual conflict resolution tools.If the key submodule.$name.update is set to merge, this option isimplicit. Mechanism for running arbitrary commands with thecommit ID as an argument.
If you really want to remove a submodule from the repository and committhat use git-rm1 instead. Optional arguments limit which submodules will be initialized.If no path is specified and submodule.active has been configured, submodulesconfigured to be active will be initialized, otherwise all submodules areinitialized. If –recursive is specified, this command will recurse into nestedsubmodules, and show their status as well. You should see changes both on the submodule’s Github repository as well as the parent repository. Git submodules allow you to manage dependencies more closely than most package managers. With submodules, you can choose exactly which versions of each dependency you want to include in your project, and it’s easier to update the commit ID of the submodule than it is to publish a new package.
Because of this, a submodule does not automatically upgrade which is a blessing in disguise when it comes to reliability, maintenance and QA (just ask Subversionians using externals how many times they have to specify — ignore-externals in their commands to avoid untimely upgrades…). In simple terms, a Git submodule is a repository nested inside another Git repository. This allows you to include and manage a separate project within your main project. Submodules are particularly useful when your project relies on external libraries or components that you want to keep as separate repositories. Both settings can be overridden on the command line by using the–ignore-submodules option. If this option is also present in the submodule’s entry in .git/configof the superproject, the setting there will override the one found in.gitmodules.
When you add a submodule in Git, you don’t add the code of thesubmodule to the main repository, you only add information about thesubmodule that is added to the main repository. This informationdescribes which commit the submodule is pointing at. This way, thesubmodule’s code won’t automatically be updated if the submodule’srepository is updated. This is good, because your mainrepository might not work with the latest commit of the submodule; itprevents unexpected behaviour. Any later subcommand of git submodule will blissfully ignore this submodule until you init it again, as the submodule won’t even be in local config.
If this happens, don’t worry, you can simply go back into the directory and check out your branch again (which will still contain your work) and merge or rebase origin/stable (or whatever remote branch you want) manually. If you forget the –rebase or –merge, Git will just update the submodule to whatever is on the server and reset your project to a detached HEAD state. Let’s try updating our submodule with the “merge” option.To specify it manually, we can just add the –merge option to our update call.Here we’ll see that there was a change on the server for this submodule and it gets merged in. First of all, let’s go into our submodule directory and check out a branch. When we run git status at this point, Git will show us that we have “new commits” on the submodule.
There are no other local changes right now besides the submodule’s referenced commit… Notice this matches almost exactly the lower part of our enhanced git status display. In order to illustrate the issues with collaborating on a repo Git Submodules that uses submodules, we’ll split personalities and act as our colleague, who clones the container’s remote to start working with us. We’ll clone that in a colleague directory, so we can immediately tell which personality cap we have on at any given time.
Git submodules provide a structured way of including external repositories in a project while retaining the benefits of having a repository maintained separately. So, we will go into our submodule directory, create a branch named “try-merge” based on that second SHA-1 from git diff, and manually merge. So basically what has happened here is that Git has figured out that the two branches record points in the submodule’s history that are divergent and need to be merged.It explains it as “merge following commits not found”, which is confusing but we’ll explain why that is in a bit.
Let’s start by adding an existing Git repository as a submodule of the repository that we’re working on.To add a new submodule you use the git submodule add command with the absolute or relative URL of the project you would like to start tracking.In this example, we’ll add a library called “DbConnector”. The code is never added to the main repository, only a pointer to the commit of the submodule. The code will be checked out on your file system, but it does not appear in the actual main git repository. When initializing submodules, a .gitmodules file in the top-level directoryof the containing repository is used to find the url of each submodule.This file should be formatted in the same way as $GIT_DIR/config.
The main repository, known as the superproject, tracks the submodule’s state via a specific commit hash. This allows the superproject to reference a particular version of the submodule, making it easy to include third-party libraries or shared codebases as part of your project while maintaining separation between them. In order to ensure a current tracking branch state, update –remotefetches the submodule’s remote repository before calculating theSHA-1. If you don’t want to fetch, you should use submodule update–remote –no-fetch.
