(Pssst. Check out Your Git Submodule and You for more in-depth information.)
What you should know
- Submodules are a convenient way of putting a clone of another repository as a subdirectory within your main repository. The submodule is its own repository, and you can commit, branch, merge, etc. from inside it, just as with any other repository.
- A submodule’s contents aren’t stored in the main repository – the main repository stores only the URL and SHA1 hash referring to a commit in the submodule repository. It’s only on your local computer that the submodule files are in a subdirectory of your main repository.
- Unlike svn:externals, submodules point to a specific commit in the other repository, not a branch (whose code can change). Someone who clones your main repository next week will get the correct submodule code, even if the submodule has new commits upstream.
- That means if you want to point to a different (newer) submodule commit, you must make a commit in your main repository to update the reference.
- You cannot include only part of the other repository (e.g. one directory) as a submodule. You must include the entire other repository. Plan your repositories accordingly.
[main]$ bits on each line represents your bash prompt. You should only type the stuff after the $.
- Set up the submodule for the first time:
[~]$ cd ~/main/ [main]$ git submodule add git://github.com/my/submodule.git ./subm [main]$ git submodule update --init [main]$ git commit ./submodule -m "Added submodule as ./subm"
- Fetch submodules after cloning a repository:
[~]$ git clone git://github.com/my/main.git ~/main [~]$ cd ~/main/ [main]$ git submodule update --init
- Pull upstream main repo changes and update submodule contents:
[main]$ git pull origin/master [main]$ git submodule update
- Pull upstream changes to the submodule:
[main]$ cd ./subm [subm]$ git pull origin/master # or fetch then merge [subm]$ cd .. [main]$ git commit ./subm -m "Updated submodule reference"
- Edit and commit files in your submodule:
[main]$ cd ./subm [subm]$ edit whatever.rb [subm]$ git commit whatever.rb -m "Updated whatever.rb" [subm]$ cd .. [main]$ git commit ./subm -m "Updated submodule reference"
- Push your submodule changes to the submodule upstream:
[main]$ cd ./subm [subm]$ git push origin master