Git Submodules cheatsheet

Why having a submodule ?

With git you can add a submodule to a repository. A submodule is another repository inside a repository.

How to create a submodule ?

git submodule add [email protected]:my_account/my_submodule.git path_to_my_submodule

git submodule init

This command does is initalizing the local git configuration with the submodules list. The list is retrieved from the .gitmodules file.

Update your submodules

Update from the remote repository (last version) :

git submodule update --remote

Update and initialize if the submodule is not initialized. (1) initialize the git configuration with the submodules list retrieved from the .gitmodule file (2) clone the submodule repository

git submodule update --init

If you have a submodule within a submodule, you will want to use :

git submodule update --init --recursive

The submodule can also be updated by using git pull inside the submodule's directory.

What happens if you don't update your submodules ?

If you don't run this command, the code of your submodule is checked out to an old commit.

Ruby On Rails

In a rails app, it's possible to specify the version number and the submodule path in the Gemfile.

You could download it manually and specify the path :

gem 'my_gem', '0.0.42', path: 'gems/my_gem'

Or use the bundler to download the gem, like another gem.

gem 'my_gem', github: 'https://github.com/my_account/my_repo.git'

In this last case, you may want to use this notation :

git_source(:github) { |repo| "https://github.com/#{repo}.git" }

gem 'my_gem', github: 'my_account/my_repo'

or eventually :

git_source(:github) do |repo_name|
  repo_name = "#{repo_name}/#{repo_name}" unless repo_name.include?("/")
  "https://github.com/#{repo_name}.git"
end

Extra

https://blog.github.com/2016-02-01-working-with-submodules/ : from github, working with submodules (extract a submodule from a repository)

https://git-scm.com/docs/git-submodule : git-submodule documentation

hadrienblanc/git-submodules.md